Social media API for AI agents: what to look for

A script that posts runs the same way every time, and you read its code. An agent decides what to post, retries on its own, and sometimes gets things wrong in ways you only see afterwards. A posting API that is fine for a cron job can be a bad fit for an agent.

This is a checklist for choosing one, based on what goes wrong. Each item says what to look for and then how yeetpost handles it, so you can compare it with whatever else you are evaluating.

#1. It tells the agent where it stands

An agent starting a session knows nothing. It needs one call that answers: which account am I acting as, is this live or test, what plan, what is left of today's allowance, and is anything broken.

yeetpost's MCP server has get_context for this, and GET /me over REST. It returns the account, live or test mode, the profile the key is scoped to, the plan, today's and this month's usage against the caps, and an attention list. An expired login shows up in that list with the fix in its message. The server's own instructions tell the agent to call it first and report any attention items before doing anything else.

If an API makes the agent discover an expired login by failing a post, the user finds out from a failed post.

#2. Mistakes are cheap: drafts, dry runs and a sandbox

You want three levels of "not real" and they are different things.

• A dry run checks a request without doing anything. yeetpost's validateOnly: true runs every check a real call runs, including text limits, image rules and the schedule time, and then stops. It creates nothing, reserves nothing and charges nothing.
• A draft stores the post and publishes nothing, so a human can look before it goes. isDraft: true stores it against each connection, and publish_draft sends it. update_post edits it first.
• A sandbox is a fake connection that takes posts, stores them, returns the shapes a real platform does and fires the same webhooks, without publishing. A key starting with yp_test_ reaches only sandbox connections, so an agent holding one cannot post to a real account even if it tries.

Start every agent on a test key, and give it a live key only when you trust its drafts.

#3. Retries cannot double-post

Agents retry. A tool call times out, the model tries again, and now there are two posts. The API has to make the second call harmless.

yeetpost takes an Idempotency-Key on POST /posts, and idempotencyKey on the MCP create_post. The same key with the same body replays the stored response and posts nothing again. The same key with a different body is 409 idempotency_key_conflict. Keys last 24 hours.

One detail matters for agents: a few refusals release the key instead of storing it, such as payment_method_required and fair_use_reached. That way, a retry after you fix the cause actually posts, instead of replaying the refusal.

Tell the agent to use a stable key per logical post, for example derived from the content or the source item.

#4. Failures are specific and fixable

An error the agent cannot act on is a loop. Look for stable error codes, a message that says the fix, and a request id.

yeetpost's errors are JSON with a code and a message, such as:

{
  "error": "invalid_connection",
  "message": "Connection 'linkedn' not found. Available connections: linkedin, x"
}

The message names the typo and lists the valid slugs, so the agent corrects itself. Over MCP, a refused call sets isError and carries the code, the message and a reqId.

Two design points help agents in particular:

• Per-connection results. A post to three platforms returns one item per connection. If Bluesky refuses the text, LinkedIn and X still go out, and the Bluesky item is failed with a code. The call is not an error as a whole, so the agent does not retry the posts that worked. retry_post resends only the failed one.
• Limits are checked before sending. A post over the platform limit is refused whole with 400 text_too_long and a field naming the part: text, thread[1], firstComment. The agent can shorten that part and try again.

#5. The agent can see the brand, not just the text

An agent that writes on its own needs your voice, or it writes like every other agent. Look for a place to store the voice and the visual style where the agent reads it before writing.

In yeetpost, each connection can carry a voice (a tone description and up to 5 example posts) and a look (a description, up to 5 example cards and a logo), and the account has defaults. get_brand returns both for a connection, and the server's instructions tell the agent to call it before writing a post or a card. draft_look_from_url drafts a look from a brand's website and saves nothing until apply is set, so the agent shows you the draft first. How cards are drawn is in on-brand image cards from HTML.

#6. Scope and revocation

Handing an agent a key is handing it a capability. Check what you can narrow and what you can revoke.

• Scoped keys. A key can be limited to one profile (one end customer), so it sees that profile's connections and posts only.
• Test keys. Sandbox only, as above.
• OAuth for MCP. Clients that cannot hold a key, like claude.ai, log in through a consent screen where you choose whole account or one profile, and live or test. The grant behaves like a key with the same scopes. Revoke it on the MCP screen and its tokens die at their next request.
• Spend caps. If any platform costs money per post, you need a cap you set, not a bill you read afterwards. On yeetpost that is X, at 1.5 cents a post and 20 cents with a link, with a monthly cap in Settings. Past it, X posts fail with spend_cap_reached. A thread is checked against the cap whole before any of it is sent.
• A fair-use cap on free accounts. 100 posts a day, counted in UTC across all connections. It bounds a runaway loop on a free account. Paid accounts have no daily cap, so rely on the spend cap and your own limits there.

#7. It tells you what happened afterwards

An agent that posts at 3am needs an audit trail. Look for webhooks for outcomes, a log of what was refused, and a way to read a post back.

yeetpost sends post.sent and post.failed webhooks, with signed requests, delivery logs and replay. get_activity returns the account's log and the post requests that were refused in the last 30 days. get_post and get_post_metrics read a post and its numbers back.

#8. Tool surface that fits in context

Every tool definition an agent holds costs tokens on every turn. A server that exposes hundreds of tools makes the agent search for the right one. A smaller set, named for the jobs an agent does, stays in view. We argued this at length in why five MCP tools beat 496, and the server has grown since, so count what you need instead of what a vendor lists.

#9. The honest part: what the platform will not do

Agents are bad at noticing a missing capability. Make sure the API says no clearly. In yeetpost, a thread on a platform without threads is shape_unsupported for that item, a first comment on anything but LinkedIn is too, and images stay on the head post of a thread. Discord and Telegram report nothing back for metrics.

Only six platforms are live: LinkedIn, X, Bluesky, Discord, Telegram and Mastodon. An agent asked to post to anything else should be told that by the API, and by its instructions.

#A starting configuration

1. Create a test key and a sandbox connection.
2. Add the MCP server with that key: see how to post from Claude.
3. Have the agent write drafts only, with a stable idempotency key per post.
4. Register a post.failed webhook to your own alerting.
5. Move to a live key scoped to one profile when the drafts are good.

The MCP docs list every tool, and the docs cover the REST API underneath.