Publish a post
Put a post on a connected LinkedIn, X, Instagram, TikTok, YouTube, Facebook, Threads, Bluesky, Telegram, Discord, Pinterest or Mastodon account (Reddit once Reddit approves our app): now, at a time, or in the account's next free queue slot.
The body carries the text, media keys, a title where the platform needs one, per-platform settings and an optional first comment. The rail checks the platform's rules before anything goes out and answers 422 with the rule it refused on, or 402 with the reset time when a Free plan's UTC day is full. What comes back is the post's id, its state and, once live, the URL on the platform.
Ask in plain words
- "post this to LinkedIn for me"
- "schedule an Instagram post for tomorrow at 9am"
- "add these three posts to the X queue"
- "social media posting API for my agent"
From an agent host (MCP)
Server: https://shapelessai.com/mcp (add it to your host).
posts_create: PUBLISHES CONTENT: puts a post you wrote on the rail for one connected account (connections_list), at a time, in the account's next free queue slot, or now. Read platforms_list first for the platform's limits and settings schema. Free plan: 10 posts a day and 60 a month, and X only once a day without links, because X bills per post (402 free_daily_cap / free_monthly_cap / free_x_daily_cap / free_x_link carry the reset time and what to do instead). Needs the publish scope.
From code (REST)
Bearer API key with the scope each call names (auth, OpenAPI).
POST /api/posts(publish scope): Queue a post: at a time, in the next free queue slot, or now. Send an Idempotency-Key so a retry never makes a second post.GET /api/posts/cap(read scope): The Free plan's day: how many posts already go out on the UTC day ?at= falls on, and the cap. Paid plans answer { cap: null }.
The body
POST /api/posts:
connectionIdstring, required: The target account (GET /api/connections).postTextstring, requiredmediaKeysarray: Keys from an upload route; the account's own media only.documentTitlestring: Required on YouTube (the video title).scheduledAtstring: When it goes out. Omitted or past = publish now.queueboolean (true): Instead of scheduledAt: the next free slot of the account's queue.settingsobject: Per-platform knobs; the schema is GET /api/platforms[].settingsSchema.firstCommentstring: Posted as the post's own first reply the moment it is live. LinkedIn (1250), X (280), Bluesky (300).audioobjectinspirationobject
From a terminal (CLI)
shapeless posts create
Example
Refusals
| Status | Meaning |
|---|---|
| 400 | A malformed body: no or oversized text, bad settings or firstComment, a mediaKey outside this account, an unconnected connectionId, or scheduledAt and queue together. The message names the field. |
| 402 | A plan limit: Free's day is full, or X's allowance is (PlanLimit). The body names the plan that lifts it. |
| 409 | audio given on an Instagram account connected through Instagram Login: {needsConnection: 'instagram', connect: {platform, url, expiresAt}} - connect.url opens the Facebook Login connect. Or every queue slot for the next two months is taken. Or code idempotency_in_flight: the first request with this Idempotency-Key is still running (Retry-After). |
| 422 | A platform rule refused the post, or a mediaKey names nothing storage holds (use the keys a tool returned, or GET /api/brain/assets). The message names the rule or the keys. |
| 400 | at is not an ISO 8601 timestamp. |
Where else
More in Publishing
Attach a sound to an Instagram Reel · Review the queue · Set the posting schedule · Answer comments and work the inbox
