REST API reference

The token’s workspace, its plan limits, current usage and account counts.

The cheapest call to verify a token works. No endpoint takes a workspace id — the token carries exactly one, so a token can never reach another tenant’s data whatever the caller sends. The month in `usage` starts on the day the plan renews (the 1st on Free); `renewsAt` is when it starts over. X is counted in credits — a post without a link is 1, one with a link about 13.3, each picture or video 1 more — and `xCreditsExtra` are credits bought on the website, spent once the month’s run out. `monthlyXPosts` and `xPostsThisMonth`, the names from before credits, still carry the same two numbers; read the credit names in new code.

{
  "workspaceId": "wsp_...",
  "plan": { "id": "growth", "name": "Growth",
            "limits": { "socialAccounts": 15, "seats": 3, "monthlyPosts": -1,
                        "monthlyXCredits": 350, "aiCredits": 1000 } },
  "usage": { "accounts": 6, "postsThisMonth": 84, "xCreditsThisMonth": 57.33,
             "xCreditsCarried": 0, "xCreditsExtra": 200,
             "aiCreditsThisMonth": 212.4, "periodStart": "2026-11-13T09:21:00.000Z",
             "renewsAt": "2026-12-13T09:21:00.000Z" },
  "stats": { "accounts": 6, "scheduled": 12 }
}

Connected social accounts — id, platform, username, status.

Access tokens are never returned by any endpoint.

[
  { "id": "acc_...", "platform": "INSTAGRAM", "username": "ravenpost",
    "status": "ACTIVE", "connection": "FACEBOOK_LOGIN" }
]

The boards on a connected Pinterest account.

The only per-platform route here, and Pinterest earns it: every pin has to name a board, there is no default, and a board id appears nowhere else a caller can read it — not even in the board’s own URL, which uses a slug. Pass the ids to `pinterestBoards` on a post.

{
  "boards": [
    { "id": "1234567890", "name": "Product shots", "privacy": "PUBLIC" }
  ]
}

List posts, newest first.

Without `page` this returns a plain array, matching the dashboard’s contract; with `page` it returns a paginated envelope. Automations should always pass `page` — a workspace with thousands of posts otherwise returns all of them in one response.

Create a post and publish, schedule, queue or save it as a draft.

One post, many destinations: each account in `accountIds` becomes a target with its own status, permalink and error. Caption length is validated against the tightest selected platform.

{
  "type": "IMAGE",
  "caption": "Shipping today.",
  "captionOverrides": { "TWITTER": "Shipping today 🚀" },
  "mediaIds": ["med_..."],
  "accountIds": ["acc_...", "acc_..."],
  "action": "schedule",
  "scheduledAt": "2026-08-04T09:00:00.000Z"
}

Create many posts from a CSV.

Returns a per-line report so a caller can retry only the rows that failed, rather than guessing which half of the batch landed.

One post with every target’s status, permalink and error.

Edit a draft or scheduled post.

Editing resets the post to draft — pass `action` in the same call to re-schedule or publish it. A published post cannot be edited.

Delete the Ravenpost copy and cancel any pending publish.

This does not take down anything already published. Removing the post on the platform is a separate, opt-in action in the dashboard, and it is not available on Instagram, Threads and TikTok, which expose no delete endpoint, or on YouTube, whose delete endpoint needs a broader permission than Ravenpost holds.

Move a post to a new time.

Publish a post immediately, whatever it was scheduled for.

Re-enqueue only the failed targets.

Targets that already published are left alone, so a retry can’t double-post.

The workspace media library.

Step 1 of an upload: get a presigned PUT URL.

The client sends the bytes straight to object storage, so a large video never travels through the API — and never has to be base64-encoded into a request.

{ "uploadUrl": "https://...", "storageKey": "...", "url": "https://cdn..." }

Step 2 of an upload: register the uploaded object as an asset.

Returns the asset `id` to put in `mediaIds`.

Reshape one image into several platform canvases in a single call.

Cropping is saliency-based by default — an off-centre subject survives a 4:5 → 9:16 cut, where a centre crop would keep the wall behind them. Pass `crop: "centre"` for posters, screenshots and flat graphics composed around their middle. Two formats with the same dimensions produce one file, not two, and each variant inherits the source’s alt text and folder. Images only.

{
  "formats": ["feed_portrait", "story", "landscape"],
  "crop": "smart"
}

{
  "sourceId": "med_b2",
  "variants": [
    { "id": "med_c1", "url": "https://cdn...", "format": "feed_portrait", "width": 1080, "height": 1350 },
    { "id": "med_c2", "url": "https://cdn...", "format": "story", "width": 1080, "height": 1920 }
  ]
}

Followers per account, a 30-day daily series, and engagement on recent posts.

A `followers` of `null` means we hold none for the platform — LinkedIn, Threads and Discord expose no insights, TikTok’s need a scope that is not approved yet, and X’s are not read because X charges for every API read. Null means unknown, never zero; an absent post metric was not collected rather than being 0.

Recommended posting hours, measured from this workspace’s own posts.

Overall and per platform, in the workspace timezone. `score` is a multiple of a typical post for that account, so 1.8 means “roughly 80% better than normal”. When `insufficient` is true `slots` is empty — that is “unknown”, not “no good time”. `reason` says which wall it hit: `few_posts` / `few_samples` (more publishing fixes it — `observations` vs `minObservations` says how far off), `low_engagement` (posts earn too few interactions for any hour to stand out), `not_collected` (the platform reports no per-post engagement at all).

{
  "overall": {
    "timezone": "Europe/Istanbul",
    "observations": 46,
    "insufficient": false,
    "minObservations": 12,
    "reason": "ok",
    "slots": [
      { "weekday": 2, "minutes": 1140, "score": 1.84, "samples": 5 }
    ],
    "grid": [[null, null, 0.9, "..."]]
  },
  "byPlatform": [{ "platform": "INSTAGRAM", "report": { "...": "..." } }]
}

Send one transactional email — a template turned on in Email → Transactional, to one address, filled with your values.

Queued, not sent in the request: the answer (202) is the email with `status: "QUEUED"`, and `GET /v1/emails/:id` says what became of it. A template turned off in Email → Transactional is answered 409 `template_disabled` and nothing is sent — the request is kept as a skipped email, so keep calling: once it is turned on again, the same request sends. Every tag the template writes without a fallback has to be in `data`, or the request is refused (400, `missing_data`) — a hole in a sentence is never sent. An `info` template carries an unsubscribe link and is not sent to anybody who unsubscribed from the workspace’s emails; a `transactional` one (receipts, resets) has none and is; neither goes to an address that bounced or marked the workspace’s mail as spam. Pass an `idempotencyKey` and a retried request gets the first one’s email back (`duplicate: true`) instead of a second email. Needs Email with transactional emails on the workspace’s plan; through Ravenpost’s own sending it counts against the month’s emails (429 `email_month_spent` when they are used up).

{
  "template": "welcome",
  "to": "ada@example.com",
  "data": { "first_name": "Ada" },
  "idempotencyKey": "welcome-user-123"
}

{
  "id": "em_k3",
  "templateId": "tpl_w1",
  "template": "welcome",
  "kind": "info",
  "to": "ada@example.com",
  "status": "QUEUED",
  "source": "api",
  "error": null,
  "createdAt": "2026-11-02T12:00:00.000Z",
  "duplicate": false
}

What became of one transactional email: queued, sent, delivered, opened, clicked, bounced — or why it did not go.

`status` is QUEUED, SENDING, SENT, DELIVERED, BOUNCED, COMPLAINED, FAILED or SKIPPED; `error` says why one failed or was skipped (the address unsubscribed, bounced before, a domain that takes no mail). Opens and clicks are timestamps beside the status. Kept for 90 days.

{
  "id": "em_k3",
  "template": "welcome",
  "to": "ada@example.com",
  "status": "DELIVERED",
  "sentAt": "2026-11-02T12:00:02.000Z",
  "deliveredAt": "2026-11-02T12:00:04.000Z",
  "openedAt": null,
  "error": null
}

The transactional templates that are turned on, each with the values it takes and the ones it cannot go out without.

`requiredData` lists the keys `data` must carry; every other tag has a fallback written in the template.

{
  "templates": [
    {
      "key": "trial-started",
      "name": "Trial started",
      "kind": "transactional",
      "tags": [{ "key": "plan_name", "fallback": null, "required": true }],
      "requiredData": ["plan_name", "trial_end"]
    }
  ]
}

The weekly posting schedule that `action: "queue"` publishes into.

Workspace-wide and shared by every connected account, in the workspace timezone. weekday 0 = Sunday.

Per-platform caption budgets, media rules, formats, thread caps and recommended specs.

Read this instead of hardcoding limits: they change when a platform changes, and this endpoint is generated from the same registry the publisher enforces.