API reference

Getting started

Create an API key in your dashboard, under API keys, and send it as a bearer token. All requests and responses are JSON, except image uploads.

curl https://postcove.net/v1/accounts \
  -H "Authorization: Bearer pc_..."

Publish to two accounts now, with a different text for the second:

curl https://postcove.net/v1/posts \
  -H "Authorization: Bearer pc_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e" \
  -d '{"text": "Olá!", "account_ids": [1, 2], "overrides": {"2": "Hello!"}}'

Schedule it instead with "scheduled_at": "2026-10-09T09:30", "timezone": "Europe/Lisbon". With images, upload them first and pass their ids:

curl https://postcove.net/v1/media \
  -H "Authorization: Bearer pc_..." \
  -F [email protected] -F alt_text="The harbour at dawn"
# → {"id": 7, ...}, then "media_ids": [7] in the post

Errors and limits

Errors have a stable code and a readable message:

{"error": {"code": "invalid_post", "message": "Not valid for some accounts.",
           "accounts": {"2": "Bluesky allows 300 characters; this has 342."}}}

Each key may make 120 requests a minute; past that, requests get 429 rate_limited. Text is checked against every account's limits when you create the post, so a post that is accepted fits everywhere.

Exactly once

Send an Idempotency-Key header with POST /v1/posts: retrying a request with the same key returns the first post instead of creating a second one.

Publishing is exactly-once too. If a platform times out or our server restarts mid-publish, the retry finds the post already there instead of publishing it twice. Temporary errors are retried for about an hour; a post the platform rejects fails at once, with the platform's reason in error.

Languages

Every account posts in one language, so its posts are tagged correctly on the platform. A workspace has a list of languages (GET /v1/workspace); the first is the default for new accounts. To post in several languages, connect one account per language and send each one its text in overrides.

Connecting accounts

Let your users connect their own accounts without you ever handling a password: create a connect link and send them to it.

curl https://postcove.net/v1/connect-links \
  -H "Authorization: Bearer pc_..." -H "Content-Type: application/json" \
  -d '{"platform": "mastodon", "redirect_url": "https://example.com/connected"}'
# → {"url": "https://postcove.net/connect/…", "expires_at": "…"}

They sign in on the platform, and come back to redirect_url?status=connected&account_id=12 (or status=cancelled). A link works once, for an hour.

Webhooks

Add an https URL with POST /v1/webhooks (or in the dashboard) to hear about post.published and post.failed, one per account, and account.needs_reconnect. Each event is a POST:

{"id": "evt_3b1f…", "type": "post.published", "created_at": "2026-10-09T08:30:02+00:00",
 "data": {"post_id": 41,
          "variant": {"id": 88, "account_id": 2, "status": "published",
                      "url": "https://bsky.app/profile/…/post/…", "error": null},
          "account": {"id": 2, "platform": "bluesky", "handle": "ana.bsky.social"}}}

Answer with any 2xx within 10 seconds. Otherwise we retry after 1 and 5 minutes, then 30 minutes, 2 and 6 hours. The same event can arrive twice: use its id to ignore repeats.

Verifying the signature

Every request carries Postcove-Signature: t=<unix time>,v1=<hex>: the HMAC-SHA256 of <t>.<raw body> with your webhook's secret (whsec_…, shown once when you add it). Check it, and reject old timestamps:

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    signed = f"{parts['t']}.".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) <= tolerance
    return fresh and hmac.compare_digest(expected, parts["v1"])