SosoAPI publishing API: authentication, requests and outcomes

1. Authenticate from your server

Create an API key in SosoAPI App → Settings → Agents & API Access. Store it as SOSOAPI_API_KEY in your server environment. Requests use Authorization: Bearer <your-key> and Content-Type: application/json. Never embed the key in a website, mobile app bundle, URL or public repository.

All endpoints below use POST with a JSON body. Keys and delegated agent grants are constrained by their capabilities, permitted Workspaces and the owner’s current membership. Reads need agent:operate and at least viewer access; publishing mutations need agent:publish and at least editor access. A grant cannot widen the owner’s rights.

Use the app’s current workspace and connected accounts, or call /identity-api/workspace/list and /identity-api/user/social-accounts/list to find IDs you are authorized to use. Do not guess a customer’s workspace or account ID.

// Node.js 20+; run only on your server.
const apiKey = process.env.SOSOAPI_API_KEY;
if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server");
const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1";

async function sosoPost(path, body) {
  const response = await fetch(apiBase + path, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) {
    const requestId = result.request_id ?? response.headers.get("x-request-id");
    // Handler errors use code/message; schema-validation 400s instead use
    // success:false and error:{name:"ZodError",message:...}.
    // Preserve status, available code and requestId in server diagnostics.
    // Never log the key or an Authorization header.
    throw new Error("SosoAPI " + response.status + " (" +
      (requestId ?? "no request id") + ")");
  }
  return result;
}

2. Publishing endpoint map

These paths are relative to the API base used in the server helper. Fetch the Scheduled Post detail to get its current version, available actions and publishing result.

3. List and paginate without losing scope

limit defaults to 50 and accepts 1–200. Optional status is one of scheduled, publishing, published, failed, expired, needs_reschedule, cancelled or deleted. scheduled_from and scheduled_to must be supplied together as ISO-8601 instants with offsets; the end must be after the start.

next_cursor is either null or an object with scheduled_at and id. Send that entire object back as cursor alongside the same Workspace and filters. This endpoint does not accept page, offset, platform or social_account_id filters.

await sosoPost("/studio-api/scheduled-posts/list", {
  "workspace_id": "<workspace-uuid>",
  "limit": 50
});

const first = await sosoPost("/studio-api/scheduled-posts/list", {
  workspace_id: "<workspace-uuid>", limit: 50
});
if (first.next_cursor) {
  const next = await sosoPost("/studio-api/scheduled-posts/list", {
    workspace_id: "<workspace-uuid>", limit: 50, cursor: first.next_cursor
  });
  // Consume next.posts; continue only while next_cursor is not null.
}

4. Validate and create one reviewed post

Replace every placeholder with values from your authorized scope and a future time. This example schedules a real Threads text post when executed. Obtain the person’s confirmation of the account, content and time before the create call.

Set provider_payload.platform and that platform’s publish_options. The server checks that they match the selected account. You may include project_id to record where the post came from; the project does not grant publishing access or control the schedule.

await sosoPost("/studio-api/scheduled-posts/eligibility", {
  "workspace_id": "<workspace-uuid>",
  "include_quota": true,
  "targets": [
    {
      "social_account_id": "<threads-account-uuid>",
      "media": [],
      "provider_payload": {
        "platform": "threads",
        "publish_options": {
          "post_type": "TEXT"
        }
      },
      "draft": {
        "caption": "A reviewed update from our team.",
        "hashtags": [],
        "scheduled_at": "<future-ISO-8601-instant-with-offset>",
        "display_timezone": "Asia/Hong_Kong"
      }
    }
  ]
});

await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});

5. Read the outcome and cancel safely

Create returns { post, deduped }. List returns { posts, next_cursor, returned_count }. Get returns { post, delivery, actions, attempts, outcomes }. A post includes id, status, version, destination, schedule and available provider identity/permalink; delivery and actions explain current progress and permitted next steps.

A post with status scheduled or publishing is still pending. A terminal publish outcome with status published confirms publication and includes the provider evidence available for that post; a permalink may be missing. If the client disconnects or a response is delayed, read the existing post before reporting a result.

Before cancelling, fetch the post detail and pass its current numeric version. The result may be cancellation_pending while SosoAPI cancels a schedule held by the provider. Cancelling a schedule does not delete an already-published post.

await sosoPost("/studio-api/scheduled-posts/get", {
  "id": "<scheduled-post-uuid>"
});

const detail = await sosoPost("/studio-api/scheduled-posts/get", {
  id: "<scheduled-post-uuid>"
});
// Run only after the person confirms cancelling this unpublished post.
await sosoPost("/studio-api/scheduled-posts/cancel", {
  id: detail.post.id, expected_version: detail.post.version
});

6. Idempotency, conflicts and uncertain writes

Use the same idempotency_key when repeating the same create request. A matching replay returns the existing post with deduped=true. Changing the content while reusing the key causes a conflict. This prevents duplicate creates in SosoAPI; it does not guarantee exactly-once delivery by the provider.

For updates and actions, pass expected_version from the latest detail response. If it conflicts, fetch the post again and review your change against the new version. A lost response is a reason to check existing state, not to create another post with a new key.

The duplicate-content guard may reject a separate request with the same normalized public content, account and a nearby publishing time. Inspect the existing-post reference if you are authorized to read it, and ask the user before changing the request. Bulk requests return a result for each destination; some can succeed while others fail.

7. Errors, rate limits and integration limits

Handler errors use an envelope with error, message, optional code, retryable, request_id, optional details and retry_after_seconds. Schema-validation 400s return a different shape: { success: false, error: { name: "ZodError", message: "…" } }. The validation message currently contains the serialized field issues, including their paths; do not assume the handler-envelope fields are present.

When diagnosing a failure, keep the HTTP status, error code and correlation ID from result.request_id ?? response.headers.get("x-request-id"). Use validation field paths to fix the request. For authentication or permission errors, fix the credential or grant before trying again.

The current studio-api limit is 240 requests per minute per human user and 480 per minute in that user’s separate machine-credential bucket. These are request ceilings, not publishing throughput or plan quotas. Other endpoints and social providers have separate limits. Follow the live Retry-After header on 429 or retryable 503; do not busy-loop.

Read status at bounded intervals while the user is following the post, or use the app’s live status view. This API does not promise outbound webhooks, a subscriber SLA, identical features across platforms or a fixed publishing time.

• Platform capability matrix
• Set up your own AI agent