Post to every network from code

Both surfaces authenticate with the same personal access token, created in dashboard Settings → API tokens. A token belongs to one user and one workspace: no endpoint takes a workspace id, so a leaked token cannot be pointed at a workspace it was not minted for. We store a SHA-256 hash and a short prefix for display — the token itself is shown once, at creation, and can be revoked at any time.

curl https://api.ravenpo.st/v1/me \
  -H "Authorization: Bearer rvp_your_token_here"

Three calls: find the accounts to publish to, put the media somewhere the platforms can fetch it, then create the post. Media upload is two steps on purpose — the bytes go straight to object storage with a presigned URL, so a 200 MB video never travels through the API.

curl https://api.ravenpo.st/v1/accounts -H "Authorization: Bearer $RVP_TOKEN"

# [{ "id": "acc_a1", "platform": "INSTAGRAM", "username": "ravenpost", ... }]

# a) ask for a presigned PUT
curl -X POST https://api.ravenpo.st/v1/media/uploads \
  -H "Authorization: Bearer $RVP_TOKEN" -H "Content-Type: application/json" \
  -d '{"filename":"launch.jpg","contentType":"image/jpeg"}'

# b) send the bytes straight to storage
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @launch.jpg

# c) register it, and keep the returned id
curl -X POST https://api.ravenpo.st/v1/media \
  -H "Authorization: Bearer $RVP_TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"IMAGE","storageKey":"'"$STORAGE_KEY"'","url":"'"$URL"'","mimeType":"image/jpeg"}'

curl -X POST https://api.ravenpo.st/v1/posts \
  -H "Authorization: Bearer $RVP_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "IMAGE",
    "caption": "We shipped it.",
    "captionOverrides": { "TWITTER": "We shipped it 🚀" },
    "mediaIds": ["med_b2"],
    "accountIds": ["acc_a1", "acc_c3"],
    "action": "schedule",
    "scheduledAt": "2026-08-04T09:00:00.000Z"
  }'

The response holds one target per account, each with its own status, permalink and error — a fan-out can partly succeed, and the API reports that rather than flattening it to a single result.

• Read /v1/platforms instead of hardcoding caption budgets, media counts or thread caps. It is generated from the same registry the publisher enforces, so it changes when a platform does.
• 120 requests/minute per IP on /v1; bulk creation and presigned uploads are lower. Over the limit returns 429.
• Errors are standard HTTP with a JSON body: 400 validation, 401 bad or revoked token, 403 plan or role, 404 not in this workspace.
• Absent is not zero. A missing analytics metric means it was never collected, not that it is 0 — the API omits it rather than inventing a number.

The full surface is published as an OpenAPI document generated from the same source as this site, so it cannot describe a different API than the one above: /docs/openapi.json. There is also an llms.txt for assistants reading the site itself.

Is the API included in every plan?

Yes. The REST API, the MCP server and outgoing webhooks are on every plan including the free one — they are not an add-on. Your plan's limits (connected accounts, posts per month) apply the same way whether a post comes from the dashboard, a script or an agent.

How do I authenticate?

With a personal access token from dashboard Settings → API tokens, sent as a bearer token. A token is tied to one user and one workspace, so no endpoint takes a workspace id and a token can never reach another workspace. We store only a SHA-256 hash and a short display prefix; the token itself is shown once, at creation.

Can an AI assistant post on my behalf?

Yes — that is what the MCP server is for. Connect it to Claude Code, Claude Desktop or any MCP client with the same token and it can draft, schedule and publish through the same services and validation as the dashboard. It cannot generate images or video: the media tools only ingest files you provide.

What are the rate limits?

120 requests per minute per IP on /v1, with tighter budgets on the expensive routes (bulk creation, presigned uploads). The limit is deliberately below the dashboard's: the expected failure mode for an API is an automation looping without backoff, not a person clicking.