Developer docs
Developer questions and answers
Direct answers about npm aliases, API and MCP choice, authentication, media, safe retries, rate limits and what published really means.
Read as MarkdownReviewed by SosoAPI team ·
Are the four npm packages different SDKs?
No. Install sosoapi or one of its aliases: @sosoapi/cli, sosoapi-cli or sosoapi-mcp. Each alias uses the same exact version of the CLI and MCP implementation. You only need one.
Should I use HTTP, CLI or MCP?
Use HTTP from your server, the CLI for shell automation and inspecting schemas, or MCP with a compatible agent. They use the same public API contracts. MCP also provides local file upload and an image-URL posting tool that handles media preparation for you. Keep server credentials out of browser code.
Does setup or OAuth consent publish a post?
No. Setup does not publish anything. OAuth consent grants continuing access within the scope you choose, without a new browser approval for every write. Tell your agent when to wait for review, and check the account, content and time before asking it to publish.
Does HTTP 200 or 202 mean published?
No. The request may be accepted, scheduled or still processing. Save the post ID and read the same Scheduled Post until its outcome confirms publication. Include the permalink when one is available, and report the result for each destination separately.
Can I retry after a timeout?
Check the existing operation first. Keep the Scheduled Post ID and reuse the same idempotency key for the same request. If you change the payload, it is a different request. To retry, update or cancel an existing post, use its current version and an action that SosoAPI offers for that state.
Why is a tool missing from my client?
Check the profile, connection type and whether your client has reloaded the server. Core hides administration tools; HTTP connections do not include local file upload. The tool reference lists availability. Changing the profile does not change account permissions or eligibility.
Can remote MCP upload a local file?
No. Use local MCP to upload a file from an allowed folder, or import a public media URL over HTTP. Check the import until it is ready, then use its registered asset ID and canonical URL together. An accepted import is still in progress.
What are the rate and plan limits?
Check each schema for field, list and pagination limits. studio-api allows 240 requests per minute per user for human sessions, with a separate 480-per-minute bucket for that user’s machine credentials. Follow 429 and Retry-After. Plan quotas, provider limits and account eligibility are separate; read current billing and capability information before a large run.
Where are Markdown and schemas?
Add .md to a guide, API operation or MCP tool URL for its Markdown version. The API index links the public JSON contract and OpenAPI 3.1 document. Start at llms.txt for a page index, or llms-full.txt for the full reference in both languages. These files contain public documentation, not account data or credentials.
Will these docs guarantee search or AI citations?
No. HTML pages, canonical URLs, structured metadata and Markdown help systems read the docs. Search engines and AI services still choose what to index, rank or cite. Check those results separately from whether the pages are available.