Skip to main content
Every route is nested under an identity. {identity} accepts an idn_… id or the identity’s name.

​
Activate

POST /v1/identities/{identity}/social/activate — scope billing:write Creates the identity’s social workspace. The operation is idempotent: a later call returns the existing workspace.

​
Read status

GET /v1/identities/{identity}/social — scope agents:read Returns activated and the provider’s current connected accounts. Before activation it returns activated: false and an empty account list.

​
Open the account portal

POST /v1/identities/{identity}/social/portal — scope billing:write
Both fields are optional: redirect_url defaults to the persona’s own studio screen on deployments that configure one. The response contains a hosted url the account owner visits to authorize one or more networks. The URL is short-lived provider state; do not store it as an account.

​
List accounts

GET /v1/identities/{identity}/social/accounts — scope agents:read Returns a paginated list. This is a live reconciliation read, not a mirror of an OAuth token or cached account table.

​
Upload media

POST /v1/identities/{identity}/social/uploads — scope sessions:write Pass { "url": "https://…" }. The provider fetches the public image, video, or document and returns a social_upload. Naive Managed Agents stores neither the source bytes nor a second upload record.

​
Create or schedule a post

POST /v1/identities/{identity}/social/posts — scope sessions:write
Omit scheduled_at to queue the post immediately. title is optional and defaults to the first 100 characters. media_urls accepts up to ten public URLs, and file_ids up to ten stored fil_ ids — each resolves to a short-lived signed URL fetched once, so a stored file posts without ever needing a public address. Which targets are legal depends on whether the post carries media. bluesky, facebook, linkedin, mastodon, threads, and x take a post either way. instagram, tiktok, and youtube publish media, not text, so naming one requires at least one media_urls or file_ids entry — a text-only post to them is refused validation_failed on platforms, and the message says which platform and what is missing. pinterest and reddit are connectable but not yet postable: each needs a per-post destination (a board, a subreddit) this body has no field for, and a post naming one is refused with that reason rather than accepted and ignored. visibility is optional and says who may see the published post: public, unlisted, or private. Only mastodon and youtube accept it — they are the two networks whose contract carries all three — and naming any other platform alongside a visibility is refused validation_failed on visibility, with the network named. Omit the field and nothing is sent upstream: the post publishes at the connected account’s own default, which on a video channel is normally public. Managed Agents chooses no default of its own, so no existing integration changes behaviour.

​
AI-generated posts

Set ai_generated: true when the post’s media was made with AI. The post then carries the network’s own AI-content label where the network has one — TikTok, YouTube, Instagram, X and Pinterest — and its caption ends with an #AIgenerated line on every network, kept inside the network’s length limit (a caption that already carries the #AIgenerated tag is left as written; a phrase such as “AI-generated” in the text does not count). A post that attaches a file rendered as a character is labelled whatever the body says, and so is every post from an agent whose social.post config sets "ai_generated": true — the AI Influencer template sets it.
One non-X post costs 13,000 µUSD. A post including X costs 32,500 µUSD, or 273,000 µUSD when its text contains an HTTP(S) link. One multi-network post pays the base once. The balance is checked before publishing and the debit appears under the social component.

​
Read a post

GET /v1/identities/{identity}/social/posts/{post} — scope agents:read The response reports scheduled, processing, posted, failed, or deleted state. A post id owned by another identity returns not_found.

​
Analytics, comments, and deletion

  • GET /v1/identities/{identity}/social/accounts/{account}/analytics
  • GET /v1/identities/{identity}/social/posts/{post}/analytics
  • GET /v1/identities/{identity}/social/posts/{post}/comments
  • DELETE /v1/identities/{identity}/social/posts/{post}
All four verify the remote resource belongs to the identity’s workspace before returning data or mutating it. Analytics payloads remain provider-shaped under data; comments use Managed Agents’ ordinary pagination envelope.

​
List the company’s posts

GET /v1/posts — scope sessions:read Every post the company files, across personas and sessions, in one list. A post an agent filed is held for a person to allow before it goes out; it is listed here as pending until someone decides. scheduled lists the soonest first; everything else lists newest first. Before a list that can show sent posts, up to five posts that are due and not yet confirmed are checked with the network first, each at most once every five minutes.
  • A pending post has no network id yet: its id is the session and the approval it waits on. Allow or deny it with POST /v1/sessions/{session_id}/tool_confirmations and its tool_call_id. What an agent filed is exactly what goes out — to change it, deny with a reason and the agent files it again.
  • posted carries the permalink in url and, once an agent has read them, the latest numbers in metrics (views, likes, comments, …) with the time they were read in measured_at. Numbers are read at most once a day per post.
  • failed carries the network’s reason in error. A post that reached some networks before it failed keeps its link and its network ids for those. If the network later sends it after all, it reads posted.
  • duplicate_of is set on a pending post that would publish a stored file the persona already has on the same network, or that an earlier approval is waiting to publish, in this session or another: { id, status, platform, at, agent_id, session_id }. An agent’s post of a file that is already out, scheduled or being sent on that network is refused rather than published twice — even when two approvals land at the same moment. Another persona posting the same file is not a repeat.