Posta API and Webhooks

Authentication

Generate an API token in Settings → API Tokens. Tokens are prefixed with posta_ and can be revoked at any time. Send the token on every request as a Bearer header:

Authorization: Bearer posta_xxxxxxxxxxxxxxxx

Tokens are bound to your user account and inherit your plan's rate limits and feature access. Treat them like passwords — never commit one to a public repository.

Top endpoints

These five endpoints cover the most common automation flows. The full surface (analytics, social accounts, media uploads, OAuth state, etc.) is documented in the Swagger UI.

curl -X POST https://api.getposta.app/v1/posts \
  -H "Authorization: Bearer posta_..." \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Shipping today!",
    "socialAccountIds": [42, 99],
    "mediaIds": ["b3c5..."]
  }'

curl -X POST https://api.getposta.app/v1/posts/POST_ID/schedule \
  -H "Authorization: Bearer posta_..." \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-06-01T09:00:00Z" }'

curl -X POST https://api.getposta.app/v1/posts/POST_ID/publish \
  -H "Authorization: Bearer posta_..."

curl https://api.getposta.app/v1/posts/POST_ID/comments \
  -H "Authorization: Bearer posta_..."

curl -X POST https://api.getposta.app/v1/webhook-endpoints \
  -H "Authorization: Bearer posta_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/posta-webhook",
    "events": ["post.published", "post.failed"]
  }'

Outbound webhooks

Register a webhook endpoint to receive HMAC-signed event callbacks when posts move through their lifecycle. Posta retries failed deliveries up to 5 times with exponential backoff (30s, 60s, 120s, 240s, 480s).

Event types:

• post.scheduled — A post was scheduled for a future time.
• post.processing — The publisher worker picked up a scheduled post.
• post.published — A post completed successfully across all platforms.
• post.partially_published — A post succeeded on some platforms and failed on others.
• post.failed — A post failed on every platform.
• post.result.success — One per-platform result completed successfully.
• post.result.failed — One per-platform result failed.

Example webhook payload:

POST https://your-app.example.com/posta-webhook
Content-Type: application/json
User-Agent: Posta-Webhooks/1.0
X-Posta-Event: post.result.success
X-Posta-Delivery: 9f1a2b...
X-Posta-Timestamp: 2026-05-27T10:00:00Z
X-Posta-Signature: <HMAC SHA-256 of "timestamp.body" (hex)>

{
  "post": { "id": "7a8b..." },
  "result": {
    "platform": "linkedin",
    "status": "success",
    "platform_post_id": "urn:li:share:71...",
    "platform_post_url": "https://www.linkedin.com/feed/update/...",
    "published_at": "2026-05-27T10:00:00Z"
  }
}

Verify the signature by computing HMAC-SHA256(secret, timestamp + "." + body) as a hex digest and comparing it to the X-Posta-Signature header. The timestamp is the value of the X-Posta-Timestamp header (an ISO 8601 datetime string) and body is the raw, byte-for-byte request body — don't re-serialize the JSON before hashing. Reject deliveries whose timestamp is older than your tolerance window (we recommend 5 minutes).

OpenAPI specification

The full machine-readable OpenAPI 3.0 spec lives at https://getposta.app/openapi.yaml (mirror) and https://api.getposta.app/docs/openapi.yaml (canonical). Feed it into openapi-generator, Postman, Insomnia, or any tool that consumes OpenAPI to scaffold a client in your language of choice.

Browse the interactive documentation at api.getposta.app/docs — every endpoint has request/response schemas, examples, and an in-browser "Try it out" form.

Rate limits

Auth endpoints: 5 requests per minute per IP. General endpoints: 100 requests per minute per API token. Exceeding either returns 429 Too Many Requests with a Retry-After header. We'll raise per-token limits on request if you have a legitimate volume need.