Reference

The technical details behind the agent layer. For the full machine-readable REST spec, see the OpenAPI / Swagger link under Endpoints.

Tools & permissions

Every tool a connected agent can call, and the permission the token must include:

Tool	What it does	Scope	Example prompt
`list_accounts`	List your connected social accounts	`accounts:read`	“Which social accounts do I have connected?”
`schedule_post`	Write a post and schedule it for a date/time (or save a draft)	`posts:write`	“Draft a LinkedIn post about our new feature and schedule it for Tuesday 9am.”
`update_post`	Reschedule, re-target or edit a draft/scheduled post	`posts:write`	“Move my Tuesday post to Thursday and add Instagram to it.”
`cancel_post`	Cancel a scheduled post or delete a draft	`posts:write`	“Cancel the post scheduled for tomorrow morning.”
`retry_post`	Retry a post that failed on one or more accounts	`posts:write`	“The LinkedIn post failed — try sending it again.”
`list_queue`	See what's in your scheduled queue	`posts:read`	“What's scheduled to go out this week?”
`check_post_status`	Check a post's per-account status	`posts:read`	“Did my morning post actually publish everywhere?”
`explain_failure`	Explain why a post failed (the real reason)	`posts:read`	“Why did yesterday's Instagram post fail?”
`connect_account`	Get the link to connect a new social account	`accounts:read`	“I want to add my TikTok account.”

Scopes

Scopes use a resource:action vocabulary. You pick them when creating a token (or approve them on the consent screen). Grant the least that does the job.

Scope	Grants
`posts:read`	See your posts, drafts, and scheduled queue, and why a post failed.
`posts:write`	Create, reschedule, edit, cancel, and retry posts and drafts.
`accounts:read`	See your connected social accounts and get the link to connect a new one.
`media:read`	List media you've uploaded.
`media:write`	Upload new media for use in posts.
`analytics:read`	Read post performance analytics.

Authentication

Two ways for an agent to authenticate, both tied to your account and your chosen scopes:

Personal Access Token — a psk_live_… string you create in Settings → AI agents and paste into your app. Sent as Authorization: Bearer psk_live_…. Shown once; store it safely.
OAuth 2.1 (one-click Connect) — no pasted secret. The client registers itself, you approve scopes on a consent screen, and it receives a short-lived pso_mcp_… access token plus a refresh token it rotates automatically. Revoke from Connected agents in Settings → AI agents.

Either way, every request is re-checked: valid token, active subscription (or whitelist), and the specific scope the tool needs.

Endpoints

Endpoint	What it is
`POST https://mcp.poststreamai.com/mcp`	The MCP endpoint (JSON-RPC 2.0, Streamable-HTTP). This is what a URL-only client connects to.
`GET https://mcp.poststreamai.com/.well-known/oauth-protected-resource`	Tells a client which authorization server to use for the one-click Connect flow.
`https://api.poststreamai.com`	REST backend base URL. The connector calls these endpoints on your behalf; you normally don't call them directly.

Developers who want the full REST surface: the live spec is at https://api.poststreamai.com/swagger-ui.html ↗ (interactive) and /v3/api-docs ↗ (OpenAPI JSON).

Errors

Status	Meaning	Fix
`401`	Token is missing, invalid, revoked, or the subscription lapsed.	Re-copy the token; check it isn't revoked; confirm the plan is active. For OAuth, refresh or reconnect.
`402 TIER_UPGRADE_REQUIRED`	No active subscription (and email not whitelisted).	Subscribe, or ask an admin to whitelist the email.
`403 INSUFFICIENT_SCOPE`	The token lacks the scope this tool needs.	Create a new token with the right scope (e.g. posts:write), or re-consent with more scopes.
`429`	Rate limit exceeded.	Back off and retry after a short pause.

Rate limits

Agent requests are rate-limited per token. Normal interactive use won't hit the limit; a script that loops hard might. On a 429, pause and retry.

Troubleshooting

Symptom	Likely cause & fix
Agent doesn't list any PostStream tools	The app didn't fully restart, or the config JSON is invalid (often a trailing comma). Restart the app; validate the JSON.
"token is invalid, revoked, or the subscription has lapsed"	Wrong or revoked token, lapsed plan, or the client is pointed at the MCP server URL instead of the API URL. Re-copy the token; check Settings → AI agents.
Worked yesterday, 401 today	OAuth access token expired (client should refresh), you hit Disconnect, or the subscription lapsed.
"command not found: npx"	Node.js isn't installed or isn't on PATH. Install Node 20+ and restart the app.
Behind a corporate proxy	npx must reach the npm registry once. If blocked, use the URL-only method instead.