API reference · Posts
Publish, schedule or draft a post
POST /v1/posts
Publish or schedule a post. Set `draft: true` to save it instead. A guarded agent's normal publish request is stored in `awaiting_approval` automatically and cannot be approved by that same agent. Neither state costs anything or contacts a network.
Request
Authenticate with a bearer API key. Agents calling over MCP authorise with OAuth instead and never handle the key.
curl -X POST https://api.postlake.dev/v1/posts \
-H "Authorization: Bearer $POSTLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Campaign update","accounts":["acc_123"],"campaign":"founder-drop-01"}'Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
Idempotency-Key | string | No | Idempotency Key |
Body
| Field | Type | Required | What it is |
|---|---|---|---|
text | string | Yes | Caption for feed posts and Reels. May be empty for an Instagram Story-only post; Instagram Stories do not display captions. |
campaign | string | No | Optional lowercase campaign slug, up to 80 characters. |
assetMetadata | object | No | Up to 16 short caller-defined fields, such as hook, track or source filename. |
profile | string | No | A profile name. Resolves to every account it owns. The simple way to address accounts; combine with `platforms` to narrow it. Provide `profile`, `accounts`, or both. |
platforms | array | No | Optional filter. Keeps only these networks from the resolved set (e.g. profile "my-brand" + platforms ["bluesky"]). |
accounts | array of string | No | Connected account ids (acc_…). An alternative (or addition) to `profile`. |
media | array of string | No | |
requireAllTargets | boolean | No | When true, refuse the whole request before contacting a network if any selected destination fails PostLake's deterministic capability preflight. Default false preserves partial fan-out. |
scheduledAt | string | No | UTC with a trailing Z, or a naive local time together with timezone. |
timezone | string | No | IANA timezone (e.g. Europe/London). Interprets a naive scheduledAt as wall time in that zone. |
draft | boolean | No | Save without sending. Returns `draft`, or `awaiting_approval` when this agent requires approval. Nothing is charged and no network is contacted. |
platformOptions | object | No | |
platformOptions.pinterest | object | No | |
platformOptions.tiktok | object | No | See GET /v1/platforms/tiktok for the full option set and valid values. |
platformOptions.instagram | object | No | Choose Story explicitly. The default is a feed photo or Reel. Stories support both Instagram Login and Facebook Login, subject to Meta account eligibility. Facebook Login requires an Instagram Business account linked to a Facebook Page. |
platformOptions.facebook | object | No | Facebook Page publishing options. Page mentions only resolve after Meta approves PostLake's Page Mentioning feature. |
Response
Created (201).
Example
"…"What it costs
One credit per network the post actually reaches. X uses dedicated rates: 8 credits for text and 90 for a post with a link. Nothing is charged for a target that fails, and a post refused by pre-flight never touches the ledger at all.
Publishing endpoints are limited to 60 requests a minute per account, inside a wider ceiling of 600 a minute across the whole API. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset.
Calling this from an agent
Agents do not call REST. They call tools. Over the hosted MCP server this operation is create_post, and the agent authorises with OAuth so your API key is never pasted into a chat or seen by the model. The reply comes back in the same normalised shape you see above, which is what lets an agent reason about it without a per-network branch.
You control what any one agent may do with it: which brands it may act for, which networks it may reach, how much it may do in a day, and whether it may spend credits you bought up front. See the MCP server.
Errors
Every failure uses one shape: a stable type, a granular code, the field at fault in param, and a plain-language fix. An agent can act on it without a person reading the message. See Errors and retries.
Idempotency-Key.Common questions
Can an AI agent do this without the REST API?
Yes. Over MCP the same job is the create_post tool. The agent authorises with OAuth, so no API key is pasted into a chat or seen by the model, and the answer comes back in the same normalised shape.
Is it safe to retry this call?
Do not automatically repeat a write after a timeout unless that endpoint explicitly documents idempotency. First read the resulting state; a second request could repeat the action.
What happens when it fails?
You get one error shape: a stable type, a granular code you can branch on, the offending field in param, and a fix written so an agent can correct itself rather than stop. Full list on Errors and retries.