API reference · Posts
Validate a post (dry run)
POST /v1/posts/validate
Runs the exact validation a publish would run, covering account resolution, media resolution and capability-registry rules, without touching any platform. Returns per-target errors (blocking) and warnings (advisory). Free to call before POST /v1/posts.
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/validate \
-H "Authorization: Bearer $POSTLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"…","campaign":"…","assetMetadata":{},"profile":"…"}'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. |
accounts | array of string | No | Connected account ids (acc_…). An alternative (or addition) to `profile`. |
media | array of string | No | |
scheduledAt | string | No | |
timezone | string | No | IANA timezone (e.g. Europe/London). Interprets a naive scheduledAt as wall time in that zone. Stored fire time is always UTC. |
platformOptions | object | No |
Response
Validation result (200).
| Field | Type | Required | What it is |
|---|---|---|---|
ok | boolean | Yes | |
targets | array of object | Yes |
Example
{
"ok": false,
"targets": [
{
"account": "…",
"platform": "…",
"ok": "…",
"errors": "…",
"warnings": "…",
"issues": "…"
}
]
}What it costs
Nothing. Validation is free and creates no post, which is the point of it: an agent can check a draft against a network's real rules before spending anything, and get back the same codes and fixes a real publish would return.
Calling this from an agent
Agents do not call REST. They call tools. Over the hosted MCP server this operation is validate_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 validate_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.