Call the REST API from a script

Every tool is also an HTTP endpoint: POST /api/agent/tools/<action> with a JSON body. Use this for scripts, cron jobs and integrations that are not MCP clients.

The examples read the host and token from the environment:

export PICKPOST_URL=https://your-pickpost-host
export PICKPOST_TOKEN=pp_…

List the actions

curl -s -H "Authorization: Bearer $PICKPOST_TOKEN" "$PICKPOST_URL/api/agent/tools"

The answer is a JSON array with each action’s name, description, policy and inputSchema. The tool reference is generated from the same catalog.

Create a draft

curl -s -X POST "$PICKPOST_URL/api/agent/tools/posts.create" \
  -H "Authorization: Bearer $PICKPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Hello from the Pickpost API"}'

{"id":"5dabd24187e84ff5","status":"Draft","accountIds":[],"versions":[{"content":[{"body":"Hello from the Pickpost API","media":[]}]}],"results":[],"updatedAt":"2026-09-25T01:34:14.107650Z"}

Pass accountIds (from accounts.list) to choose where it will go. Without them the draft has no accounts yet, and you can pick them in the app.

Schedule, publish, delete

These answer 403:

curl -s -X POST "$PICKPOST_URL/api/agent/tools/posts.schedule" \
  -H "Authorization: Bearer $PICKPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"5dabd24187e84ff5","at":"2030-01-01T09:00:00Z"}'

{"code":"ApprovalRequired","message":"'posts.schedule' needs a human to confirm it in the app.","issues":[]}

A person schedules the draft in the app. Unlike MCP, the REST API does not create an approval card; it only refuses. If you want the card, go through MCP. See Approvals.

Handle errors

Every error has the same shape, {"code", "message", "issues"}. Branch on code, not on the message:

HTTP	code	What to do
400	BadInput	The JSON does not match the input schema. message names the field.
400	Invalid	The post breaks a network limit. issues lists each problem.
401	Unauthorized	Missing, wrong or revoked token.
403	ApprovalRequired	Needs a human in the app. Do not retry.
404	NotFound, UnknownAction	Wrong id, or a typo in the action name.
409	Conflict	The post changed state, for example it is already published. Re-read it.
429	TooManyRequests	Wait and retry.
500	Internal	Our fault. Retry later; the response header x-request-id helps us find it.