The API that actually posts.

Overview

The PostDodo REST API lets you wire confirmed multi-platform posting into your own product, dashboard, or automation. It speaks JSON over HTTPS, uses predictable resource URLs, and returns standard HTTP status codes.

• Base URL: https://api.postdodo.com/v1
• Format: JSON request and response bodies, UTF-8.
• Posting engine: the same auto-retry and confirmation layer the app uses, so the API never reports a post as published unless the platform confirmed it.

Authentication

Authenticate every request with your secret API key as a bearer token. Keys are issued per workspace and carry the same account access you have in the app. Keep them server-side; never ship a key in client code.

curl https://api.postdodo.com/v1/accounts \
  -H "Authorization: Bearer pd_live_YOUR_API_KEY"

A missing or invalid key returns 401 Unauthorized. Rotate a key any time from the dashboard; the old one stops working immediately.

Core endpoints

The resources you will use most:

Creating and scheduling a post

Send a caption, the target account_ids, and an optional scheduled_at (ISO 8601, UTC). Omit scheduled_at to publish immediately. Attach media by URL.

curl https://api.postdodo.com/v1/posts \
  -H "Authorization: Bearer pd_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Spring launch is live. Link in bio.",
    "account_ids": ["acct_x9f2", "acct_b3kp"],
    "scheduled_at": "2026-07-01T14:00:00Z",
    "media": [
      { "type": "image", "url": "https://cdn.example.com/launch.jpg" }
    ]
  }'

Response

You get back the post with a status of scheduled (or publishing if immediate) and a per-platform breakdown under targets.

{
  "id": "post_7Hq2Lp",
  "status": "scheduled",
  "scheduled_at": "2026-07-01T14:00:00Z",
  "caption": "Spring launch is live. Link in bio.",
  "targets": [
    { "account_id": "acct_x9f2", "platform": "instagram", "status": "scheduled" },
    { "account_id": "acct_b3kp", "platform": "bluesky",   "status": "scheduled" }
  ],
  "created_at": "2026-06-19T09:14:00Z"
}

Checking status later

Poll a post any time to see whether each target reached confirmed, is still retrying, or failed. A confirmed target includes the platform’s own permalink.

curl https://api.postdodo.com/v1/posts/post_7Hq2Lp \
  -H "Authorization: Bearer pd_live_YOUR_API_KEY"

Webhooks for delivery status

Rather than poll, register a webhook and PostDodo will push an event the moment a post’s status changes. This is how you get real-time confirmation that something actually went out.

Events

• post.published — a target was confirmed live; payload carries the permalink.
• post.retrying — a transient platform error; PostDodo is retrying automatically.
• post.failed — a target could not be published after retries, with a reason.
• account.expiring — a connected account’s token is about to expire.

Example payload

{
  "event": "post.published",
  "created_at": "2026-07-01T14:00:03Z",
  "data": {
    "post_id": "post_7Hq2Lp",
    "account_id": "acct_x9f2",
    "platform": "instagram",
    "status": "confirmed",
    "permalink": "https://www.instagram.com/p/Cabc123/"
  }
}

Each delivery is signed with an X-PostDodo-Signature header so you can verify it came from us. Respond with 2xx to acknowledge; we retry failed deliveries with backoff.

Errors and rate limits

PostDodo uses conventional HTTP status codes: 2xx for success, 4xx for a problem with your request (a bad parameter, an expired account, an unauthorized key), and 5xx for a rare error on our side. Error bodies include a machine-readable code and a human message. Rate limits are returned in response headers; if you exceed them you get 429 Too Many Requests.

Get a key

Start a free trial, pick a plan, then generate an API key from Settings → API. Have a question on the API? Email support@postdodo.com and a real engineer answers.