HTTP API

The 0.2.0-rc.1 candidate is one Bearer-authenticated HTTP API. It accepts immediate or scheduled posts, returns stored status, and reports per-platform outcomes. There is no dashboard in this candidate.

Base URL and headers

Every path below is relative to your deployed Worker URL, for example https://your-worker.your-subdomain.workers.dev. When you run locally the base URL is http://localhost:8787.

Authentication

The Worker compares the supplied Bearer token against SYNDROO_API_KEY using a constant-time digest comparison. A missing or incorrect token returns HTTP 401 with code UNAUTHORIZED.

Create a post

POST /v1/posts
Authorization: Bearer $SYNDROO_API_KEY
Content-Type: application/json
Idempotency-Key: example-post-001

Syndroo accepts the request before the Queue finishes publishing, so a new post returns HTTP 202 with status set to queued or scheduled. queued means accepted for processing, not yet confirmed by any platform.

Request body fields

Example request

curl -X POST "$SYNDROO_URL/v1/posts" \
  -H "Authorization: Bearer $SYNDROO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-post-001" \
  --data '{
    "content": "Hello from Syndroo on Threads",
    "platforms": ["threads", "bluesky"],
    "overrides": {
      "bluesky": { "content": "Hello from Syndroo on Bluesky" }
    }
  }'

This command publishes a real post once those platform credentials are configured.

Create responses

Immediate post, HTTP 202:

{
  "id": "post_...",
  "status": "queued"
}

Scheduled post, HTTP 202:

{
  "id": "post_...",
  "status": "scheduled",
  "scheduledAt": "2030-01-02T03:04:05.000Z"
}

Idempotent replay of an identical request, HTTP 200:

{
  "id": "post_...",
  "status": "queued",
  "replayed": true
}

Idempotency-Key

Idempotency-Key is optional but recommended for deployment automation. Use a stable key for one logical post.

• Repeating the same request with the same key returns the original post with replayed: true and HTTP 200.
• Reusing the key with different content returns HTTP 409 and code IDEMPOTENCY_CONFLICT.
• A malformed key, such as one containing spaces or more than 128 characters, returns HTTP 400 and code INVALID_REQUEST.
• While maintenance mode is enabled, an authenticated POST is rejected before the key is read, so nothing is recorded.

Read Idempotency for the delivery reasoning behind this header.

Check a post

curl \
  -H "Authorization: Bearer $SYNDROO_API_KEY" \
  "$SYNDROO_URL/v1/posts/post_..."

A found post returns HTTP 200. An unknown id returns HTTP 404 with code POST_NOT_FOUND.

{
  "id": "post_...",
  "content": "Hello from Syndroo",
  "platforms": ["bluesky"],
  "status": "published",
  "createdAt": "2030-01-02T03:04:05.000Z",
  "publications": [
    {
      "id": "pub_...",
      "postId": "post_...",
      "platform": "bluesky",
      "provider": "bluesky-native",
      "content": "Hello from Syndroo",
      "status": "published",
      "attempts": 1,
      "externalId": "bafyre...",
      "externalUrl": "https://bsky.app/profile/.../post/...",
      "errorAmbiguous": false,
      "createdAt": "2030-01-02T03:04:05.000Z",
      "publishedAt": "2030-01-02T03:04:06.000Z"
    }
  ]
}

If the post is still queued or publishing, wait briefly and request the same URL again. If it is failed, inspect errorCode, errorMessage, and errorAmbiguous in the publication entry.

Post object

Publication object

The internal retry_at deadline is not part of the public post response.

List recent posts

curl \
  -H "Authorization: Bearer $SYNDROO_API_KEY" \
  "$SYNDROO_URL/v1/posts?limit=50"

limit is optional, defaults to 50, and must be an integer from 1 to 100. Anything else returns HTTP 400 with code INVALID_REQUEST.

{
  "items": [
    {
      "id": "post_...",
      "content": "Hello from Syndroo",
      "platforms": ["bluesky"],
      "status": "published",
      "createdAt": "2030-01-02T03:04:05.000Z"
    }
  ]
}

Status values

An ambiguous outcome is represented as publication status: "failed" with errorAmbiguous: true, not as a separate status. See Ambiguous outcomes.

Errors

Errors use one JSON shape:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "platforms must be a non-empty array"
  }
}

Limits

Scheduling

Send scheduledAt as an ISO date-time with an explicit timezone. UTC with Z avoids ambiguity between machines.

{
  "content": "Shared fallback",
  "platforms": ["bluesky"],
  "overrides": {
    "bluesky": { "content": "Scheduled Bluesky post" }
  },
  "scheduledAt": "2030-01-02T03:04:05.000Z"
}

The accepted response returns status scheduled. Scheduling stays inside Syndroo; the platform's own queue is not used. An authenticated GET on the returned id shows the same post before and after it is due.

Maintenance mode

SYNDROO_MAINTENANCE is an optional, non-secret Worker variable. Only the exact string true enables it; false or an unset variable keeps normal operation.

• An authenticated POST /v1/posts returns HTTP 503 with code SERVICE_UNAVAILABLE.
• The rejection happens after Bearer authentication and before the request body, the idempotency key, or the database is read, so maintenance never creates a post and never records a key.
• GET /health and the authenticated GET /v1/posts and GET /v1/posts/<id> queries keep working.
• Requests without a valid Bearer token still return 401.
• Maintenance is admission control only. It does not pause Queue consumers or the Cron Trigger, so accepted work, scheduled work, and stale-job recovery continue to run.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Syndroo is in maintenance mode and is not accepting new posts; retry later with the same Idempotency-Key and request body"
  }
}