SosoAPI setup guide

Choose your starting point

SosoAPI gives the agent you already use one connection to your social accounts. Your agent helps write and review content; SosoAPI handles supported account operations, scheduling and publishing results. You can review the same posts in the app or use the API from your own code.

This guide starts with one person and one social account. You will connect a local or hosted MCP client, choose access, check a social account, prepare and approve a post, and read its actual result. The advanced walkthrough covers the CLI and HTTP API. Setup itself does not require a test post.

• Let Claude Code or Codex handle setup: step 1
• Configure an MCP client yourself: step 3
• Use a terminal or backend: step 9
• Fix a connection: step 10

Before you start

You need an MCP-compatible AI client, a SosoAPI account and a social account you are allowed to manage. You can create the SosoAPI account when sign-in opens. Have one real piece of content in mind.

Local MCP needs Node.js 20 or later with npm/npx and your chosen AI client. Hosted MCP needs a client supporting remote MCP, OAuth and automatic client registration; it needs no local Node.js installation. Client features can depend on its plan and administrator settings.

SosoAPI connects Instagram, Threads, Facebook Pages, YouTube and X. Choose an account whose type, permissions and post format match your task. An eligible Threads account is a useful first text-only example. Instagram and YouTube need suitable media for their supported publishing formats. A platform in the connection menu does not mean every action is available for every account.

Check account-specific capabilities during setup. Read your current plan and quota in the app before scheduling a batch; X has a separate Organization credit allowance. An example for one platform does not establish support on another.

• Supported platforms
• Publishing capabilities and account requirements

1. Give your agent the setup request

Paste this into your existing Claude Code or Codex conversation.

The agent should check for a working SosoAPI connection first and reuse it. Otherwise it follows the setup recipe and tells you when browser sign-in or a client restart is needed. Expected result: SosoAPI tools are usable in this conversation. An installation message alone is not proof. Continue with sign-in and an account check, or use step 3 for manual configuration.

Set up SosoAPI from https://sosoapi.ai/setup.md. Keep my current content and task. I will sign in and approve access when asked. Do not publish anything during setup.

2. Sign in and choose your agent's access

Use your intended account: continue with Google, or register with email and complete verification. Complete any account or Workspace setup shown. If you belong to several Workspaces, choose the intended brand or project. Review the requested Workspaces and actions before approving, then return to the same conversation.

Keep the sign-in link provided by your agent so the browser can return to the pending authorization. You can start in the app first, then return to your agent. Do not replace a pending approval link with a different sign-in link.

Workspace roles and platform permissions still apply: a viewer does not become an editor because an agent has publishing access. Publishing access is ongoing within the scope you grant; SosoAPI does not require a new browser approval for every post. Tell your agent when to pause for content review. Normal OAuth setup does not require pasting a social password or API key into the agent.

Expected result: sign-in completes with your intended identity, and the agent can retrieve the Workspaces you authorized. Use troubleshooting if the wrong browser profile opens.

• Start in the SosoAPI app

3. Connect your agent manually, if needed

Choose one connection method. Skip this section if your agent already configured a working connection. For local MCP, check Node.js and npx first. Node.js must be version 20 or later.

node --version
npx --version

Local MCP: Claude Code or Codex

Run only the command for your client: the first is for Claude Code and the second for Codex. The core profile covers everyday publishing. Profiles change which tools are shown; they do not grant permissions. Keep a working full-profile connection if you already have one.

Reconnect or restart if the client requests it, then check that SosoAPI tools are available in the current conversation. The first authenticated call starts browser sign-in when needed.

claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

Other local MCP clients

For clients using mcpServers JSON, add this entry to the existing configuration and preserve other servers. Other configuration formats should receive the same command, arguments and environment variable through the client’s own MCP settings.

{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}

• Installation reference and package choices

Hosted MCP: compatible browser or remote clients

In the client’s custom connector or remote MCP settings, add a connection named SosoAPI using the server URL below. Choose OAuth with automatic client registration when offered. Sign in to SosoAPI, choose permitted Workspaces and actions, return to your conversation and enable the connection if required. Ask the agent to check authorized accounts.

Use https://sosoapi.ai for a new hosted connection. The legacy endpoint https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp remains supported. Preserve a working local or hosted connection; there is no need to replace it just to change its URL.

No API key, client ID or client secret needs to be pasted. ChatGPT custom MCP apps depend on the client’s plan, developer mode and administrator settings. These instructions describe a custom connection, not an app-directory listing. Hosted MCP cannot read local files; use a public URL import or local MCP for local-file uploads.

https://sosoapi.ai

• Custom OAuth client registration and token recipe

Optional terminal sign-in check

For a local connection, run auth status first. Run auth login only if it reports that you are not signed in. Complete the browser flow and check status again. Tokens are not printed. This checks local CLI authentication, not a separate hosted connector’s login.

npx -y sosoapi auth status

npx -y sosoapi auth login

4. Connect your social account

Open Connect accounts, or use the local command below. Replace threads with instagram, facebook, youtube or x when appropriate. This opens the connection flow; it does not publish content.

Check the Organization and Workspace shown. Choose the platform, sign in through its authorization page and select the exact account, Page or channel. Complete consent and any account-selection confirmation on return. Then ask the agent to refresh connected accounts for the intended Workspace.

Reuse an existing healthy connection. If it belongs to another Organization or Workspace, resolve that choice in the app; routine setup should not disconnect or move it. Expected result: the correct account appears in the intended Workspace with current health and capability information. A successful callback alone is not proof of publishing permission.

npx -y sosoapi connect threads

• Connect accounts

5. Verify access without publishing

Paste the following into the connected agent conversation.

The agent can use sosoapi_get_workspace_context and sosoapi_list_connected_accounts, reuse known context and pass the selected workspace_id explicitly. Account initialization may create your first Workspace; this setup check does not create a social post.

Before proceeding, confirm the Workspace and destination, your role and agent access, and the destination’s support for the proposed format. Use troubleshooting if a check fails. Reinstalling a package does not fix missing platform permission.

Check my SosoAPI setup without publishing or scheduling anything.
Show the Workspaces I can use and the social accounts in the Workspace I select.
For the account I choose, show the platform, account label, connection health and publishing capabilities for my proposed format.
If several Workspaces or accounts could match, ask me which one to use.
Keep internal IDs for tool calls; do not ask me to find or invent them.

6. Prepare and approve your first post

Start with one real post and one destination. Replace the bracketed fields in this drafting prompt. The agent does the writing; SosoAPI provides the connection and publishing operations. Review claims, spelling, links and media yourself.

Use an explicit date, local time and IANA timezone for a future post. If daylight-saving time makes a local time ambiguous, choose which occurrence you intend before submission. Expected result at this stage: an exact draft for your review, with no publishing request submitted.

Help me prepare one product announcement using SosoAPI.

Product: [public product name]
Verified facts: [what is available today]
Audience: [who this helps]
Destination: [account label and platform]
Language: [language]
Preferred local date and time: [YYYY-MM-DD HH:mm]
Timezone: [IANA timezone, for example Asia/Hong_Kong]
Media: [none, a local file, or a public media URL]

Use only the facts I supplied. Check the destination’s format requirements.
Show the exact draft, media, destination, date, time and timezone for review.
Do not schedule or publish yet.

Approve the exact post before scheduling

When all details are correct, give a specific instruction using the prompt below. This creates a real schedule that can publish publicly. Use content and an account you intend to publish to. Immediate publication also needs an explicit instruction after reviewing the same details.

Expected result: a Scheduled Post ID, intended destination, accepted time and current status. An accepted schedule does not mean the provider has published it.

Schedule the exact approved post below to the named account at the stated date, time and timezone.

[Paste the final content, media, destination, date, time and timezone.]

Check for an existing matching schedule first. Submit this post once and read back the saved result. Return its ID, destination, accepted time and current status. If the result is uncertain, check the existing request before taking another action.

7. Check the result, reschedule or cancel

Ask the agent to read the same Scheduled Post using sosoapi_get_scheduled_post. You can also open https://app.sosoapi.ai/scheduled-posts/<post-id> after signing in with an authorized account. Check each destination separately when a request targets several accounts; some can succeed while others need attention.

Read the current result of Scheduled Post [returned ID].
Show its destination, scheduled time, current status and publishing outcome.
If publication is confirmed, include the live link when available.
Do not retry, reschedule or create another post.

Manage a pending post and return later

To change a pending post, provide its ID and the new details. The agent must read its current version and available actions before using a supported update or cancellation. Cancellation depends on the delivery stage and may stop being available once delivery starts. Cancelling a schedule does not remove an already-published provider post.

After receiving the saved details for a future schedule, you can leave the conversation and return to the same post later. A closed agent conversation does not promise to wake itself or notify you unless that has been separately configured.

8. Add images or video, then reuse the workflow

Get the single-post workflow working before preparing a larger batch. Tell the agent whether the media is a local file, public URL or existing SosoAPI asset.

Local files: local MCP can use sosoapi_upload_asset. The file must be inside an allowed upload folder; the tool explains permitted locations for an out-of-bounds path. Hosted MCP cannot read files on your computer.

Public URLs: use sosoapi_import_asset_url, then sosoapi_get_asset_import_status with include_asset=true. Wait until the asset is ready. For an existing asset, verify that it belongs to the intended Workspace and is ready for the chosen format.

The normal schedule request uses the registered asset ID and canonical asset URL together. A temporary preview URL or original external source URL is not a replacement. For the supported one-image-URL workflow, sosoapi_post_image_url combines import and submission. It is a publishing operation: approve the full post first. Keep an accepted post ID while processing; do not start another import to continue it.

X supports an original TEXT Post without media, or VIDEO with exactly one ready registered MP4 video asset, at least 0.5 seconds long and within the 500 MiB upload limit. Video requires verified can_publish_video for the exact account; text access alone is insufficient. An older connection may need your approval to reconnect with video-upload permission. Any text, hashtags and link must fit X’s weighted text limit. Photos, replies, quotes, reposts and thread publishing are not supported. Upload or video-processing acceptance is not a published outcome.

Before an X submission, read sosoapi_get_x_usage for the intended workspace_id and the final text. Its allowance and cost are separate from general plan quota. Do not bypass a credit limit with repeated submissions; reconcile an uncertain publication before another send.

Prepare a reviewed batch and read performance honestly

After your first successful post, try the product-launch prompt below. Once you approve the exact table, check the batch against plan limits. Report accepted and rejected destinations separately and keep each accepted post’s identity.

Publishing access and analytics access can differ. If you later ask for a performance review, unavailable metrics should be reported as unavailable. Do not invent zeros or infer that every metric is readable because a post was published.

Using the same verified setup, prepare seven product-announcement drafts, one per day, from the public facts I provide. Show a review table with the draft, destination, media, local date, time and timezone for every row. Keep all seven as drafts until I approve the exact table.

9. CLI and API walkthrough

Use this optional path for explicit request files or a backend integration. Agent users can skip it. The examples use the same account, Workspace and publishing permissions as MCP.

Inspect the installed package’s help and embedded contract first; contract inspection does not need login. It shows the operations and schemas shipped with that package. Use those field names rather than another provider’s request format.

npx -y sosoapi --help
npx -y sosoapi api contract --summary
npx -y sosoapi api contract --route /studio-api/scheduled-posts/

CLI: make your first authenticated context request

Complete auth login. With a text editor, save workspaces.json containing the JSON below, then run the command. Use files for request bodies rather than interpolating content into shell commands.

The CLI returns schema_version, http_status and body. A successful response includes body.active_workspace_id and body.workspaces. Choose the intended Workspace from that response; the active Workspace does not silently decide a new task’s destination. A new account’s first call can initialize its first Workspace.

Check http_status and body, not just the shell exit code. A command can return an HTTP error envelope without the API operation succeeding.

{}

npx -y sosoapi api post /identity-api/workspace/list < workspaces.json

CLI: select the connected social account

Save accounts.json using the Workspace ID returned for your account, then run the command. Select the intended account from body.accounts. Its SosoAPI account ID is the social_account_id used in scheduling; a username or provider Page ID is not a substitute.

{
  "workspace_id": "<YOUR_WORKSPACE_ID>"
}

npx -y sosoapi api post /identity-api/user/social-accounts/list < accounts.json

CLI: create one approved Threads text schedule

This is a request template, not a ready-to-run post. Save post.json using a file editor and replace every bracketed value with your own authorized values. Choose a future ISO timestamp with an explicit UTC offset, or Z for UTC. display_timezone is an IANA timezone for display; it does not make an ambiguous local timestamp complete.

Generate a unique idempotency_key, such as a UUID, and retain it with the exact request body. Retry an identical request with the same key; a delayed response is not a reason to generate another key. A changed post is a different request: check the original result before choosing a new identity.

After confirming content, account, time, permissions and current quota, run the create command. This schedules a real post. On acceptance, retain body.post.id and read body.post.status, body.post.scheduled_at and body.post.destination. body.deduped tells you whether an existing request was reused. Acceptance is not provider-confirmed publication.

{
  "workspace_id": "<YOUR_WORKSPACE_ID>",
  "social_account_id": "<YOUR_THREADS_ACCOUNT_ID>",
  "caption": "<YOUR_APPROVED_POST_TEXT>",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<FUTURE_ISO_8601_TIME_WITH_OFFSET>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<NEW_STABLE_REQUEST_KEY>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/create < post.json

CLI: read the saved post and its outcome

Save post-status.json with the returned ID. Read body.post, body.delivery, body.actions and body.outcomes. Confirm a published outcome before reporting success. If the create response was lost, recover the original request using its saved identity; do not create another schedule with a new key.

{
  "id": "<RETURNED_POST_ID>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/get < post-status.json

CLI: cancel only when the current result permits it

If the latest read allows cancellation and you intend to cancel, save cancel.json with the returned ID and current numeric body.post.version. The example 1 is illustrative: replace it with the version you just read. Then run the command and confirm the result.

If the version changed or cancellation is unavailable, read the same post again and use its actual available actions. Do not bypass a version conflict or confuse cancellation with deleting an already-published post.

{
  "id": "<RETURNED_POST_ID>",
  "expected_version": 1
}

npx -y sosoapi api post /studio-api/scheduled-posts/cancel < cancel.json

HTTP: call from your own backend

For a server-side integration, create an API key under Connection → API and store the secret in your server’s secret configuration. The current screen asks for a name; it does not offer Workspace or capability selectors. A user-created key defaults to operate, publish and engage across the Workspaces that user can access. Check whether that authority fits your integration. The API contract supports explicitly limited capabilities and workspace_ids for a scoped key.

Normal agent setup uses OAuth and does not need this API-key step. In the example, SOSOAPI_ACCESS_TOKEN is your server-side example variable containing the key; it is not a SosoAPI CLI setting. The CLI’s optional personal access token variable is VICKY_API_KEY.

Use the workspaces.json file above. Direct HTTP returns the endpoint body without the CLI’s http_status/body envelope; read the actual HTTP status and JSON. Keep credentials on the backend and out of browser code, prompts, screenshots and shared request files.

Embedding social connection into a product for your own customers is a separate integration task. This single-account walkthrough does not prove that customer onboarding flow is ready.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${SOSOAPI_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @workspaces.json \
  'https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/workspace/list'

• Manage API keys: Connection → API
• API reference
• API-key creation and explicit authority
• Authentication and permissions
• CLI reference

10. Troubleshooting

Use the actual error and the connection you are diagnosing. Broadening permissions or repeating a submission does not repair every failure.

Update, revoke access or ask for help

The first command below checks the latest package help without starting the MCP server. If the client pins a version in its saved command, deliberately update that command. Updating a separate global installation does not update the client’s pinned copy.

To revoke a local device, use Connection → Agent or the auth logout command below. Revoke the matching hosted authorization under Connection → Agent for a hosted connector. API keys are managed separately under Connection → API. Revoking agent access does not cancel already-accepted schedules; manage those posts separately.

For help, provide the client and package version, failed step, displayed error and time/timezone. Share relevant request or post IDs privately with support when needed. Do not send credentials, authorization links or raw logs that may contain tokens.

npx -y sosoapi@latest --help

npx -y sosoapi auth logout

• Manage agent clients: Connection → Agent
• Manage API keys: Connection → API
• Troubleshooting reference
• Contact SosoAPI support

Setup completion checklist

You can complete connection setup without submitting a post. If you publish, use the separate outcome check to confirm that first publishing workflow.

• My client can use SosoAPI tools, or my CLI/API can make an authorized request.
• I signed in with the intended account and selected the correct Workspace.
• My social account appears with the capabilities needed for the task.
• I understand whether my agent can prepare work or also schedule and publish.
• I can prepare a draft and review the exact destination, content and time.
• If I submitted a post, I retained its ID and can distinguish acceptance from confirmed publication.
• I know how to inspect a failure, manage a pending schedule and revoke access.