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.

{
  "workspaceId": "wsp_...",
  "plan": { "id": "growth", "name": "Growth",
            "limits": { "socialAccounts": 15, "seats": 3, "monthlyPosts": -1 } },
  "usage": { "socialAccounts": 6, "postsThisMonth": 84 },
  "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" }
]

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 three platforms (Instagram, Threads, TikTok) expose no delete endpoint at all.

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 the platform reports none — LinkedIn, Threads and Discord expose no insights and TikTok’s need a scope that is not approved yet. 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 there is not enough history and `slots` is empty — that is “unknown”, not “no good time”; `observations` and `minObservations` say how far off it is.

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

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.