Endpoints

The /v1 surface area. Each endpoint with a request example and the shape of the response.

The current shape of the REST API. For the machine-readable schema, see OpenAPI. For runnable examples, see the curl snippets below — they cover the most common flows.

POST /v1/posts — Schedule a post

curl -X POST https://post-mate.com/v1/posts \
  -H "Authorization: Bearer pm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Hello from the API",
    "platforms": ["instagram", "linkedin"],
    "scheduled_at": "2026-06-01T09:00:00Z",
    "media": [{ "type": "image", "url": "https://your-cdn.com/img.jpg" }]
  }'

Required: caption, platforms. Optional: scheduled_at (omit to post immediately), media, per_platform overrides.

GET /v1/posts — List posts

curl "https://post-mate.com/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer pm_live_…"

Query params:

status — draft, scheduled, posted, failed, pending_approval
platform — filter to one network
since / until — ISO 8601 timestamps
limit — 1-100 (default 25)
cursor — opaque cursor from the previous response's next_cursor for pagination

Response: { data: [...], next_cursor: "..." | null }.

GET /v1/posts/:id

Fetch a single post by ID. Returns the same shape as one element of the list response, plus per-platform delivery status (which networks have published, which are pending, which failed).

PATCH /v1/posts/:id

Edit a scheduled post. Same body shape as POST; any omitted field is left unchanged.

You can only PATCH posts where status === "scheduled". Posts that are already firing or have already published are immutable.

Cancel a scheduled post. Same restriction — only works for scheduled posts. Already-published posts can be removed from the social platforms directly (we don't delete on platforms via the API, by design).

GET /v1/accounts

List the social accounts connected in this workspace.

curl https://post-mate.com/v1/accounts \
  -H "Authorization: Bearer pm_live_…"

Response items include platform, external_id, display_name, and connected_at. No secrets; the OAuth tokens stay on our side.

GET /v1/analytics

Read post-level analytics. Same query params as /v1/posts for filtering.

curl "https://post-mate.com/v1/analytics?since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer pm_live_…"

Per-post metrics include impressions, likes, comments, saves, clicks — the union of what the underlying platforms expose. Missing metrics are surfaced as null, not zero.

POST /v1/media

Upload media for a post you're about to schedule. Returns a URL you can pass in the media field of POST /v1/posts.

curl -X POST https://post-mate.com/v1/media \
  -H "Authorization: Bearer pm_live_…" \
  -F "file=@./photo.jpg"

Max 500 MB per upload. For files larger than 4.5 MB, the response includes a presigned URL for direct upload to our R2 storage — saves you from streaming the file through our Functions tier.