Skip to content
ShapelessAI← Back
Publishing

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.

View as Markdown

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:

  • connectionId string, required: The target account (GET /api/connections).
  • postText string, required
  • mediaKeys array: Keys from an upload route; the account's own media only.
  • documentTitle string: Required on YouTube (the video title).
  • scheduledAt string: When it goes out. Omitted or past = publish now.
  • queue boolean (true): Instead of scheduledAt: the next free slot of the account's queue.
  • settings object: Per-platform knobs; the schema is GET /api/platforms[].settingsSchema.
  • firstComment string: Posted as the post's own first reply the moment it is live. LinkedIn (1250), X (280), Bluesky (300).
  • audio object
  • inspiration object

From a terminal (CLI)

  • shapeless posts create

Example

curl -s https://shapelessai.com/api/posts -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"connectionId":"<id>","postText":"Shipped the thing.","queue":true}'
// MCP tool call
{ "tool": "posts_create", "arguments": { "connectionId": "<id>", "text": "Shipped the thing.", "queue": true } }
shapeless posts create --to <connectionId> --text "Shipped the thing." --queue

Refusals

StatusMeaning
400A 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.
402A plan limit: Free's day is full, or X's allowance is (PlanLimit). The body names the plan that lifts it.
409audio 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).
422A 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.
400at 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

Every capability · Docs · /llms.txt