Threads

Create a Thread

Threads are arrays of 2-25 posts published in order as connected replies. Each post in the thread replies to the previous one. Threads work on X, Bluesky, Threads, Mastodon, and Telegram (native reply threading). On LinkedIn, Instagram, and Facebook, each post in the thread is published as a standalone post (these platforms do not support native threading). More platforms are coming soon.

A thread is all or nothing

If any part of a thread fails to publish, every part that had already published is deleted from the platform and the whole thread's quota is refunded. That holds on every path a thread publishes by: immediately, through the scheduler, when a draft is promoted, and for each account of a multi-account publish. Where a thread degrades to standalone posts, the same rule covers the standalone posts made so far, on LinkedIn and Facebook. Instagram depends on how the account was connected: an account connected via Facebook rolls back like any other, and an account connected through Instagram cannot, so a failed thread there leaves every part it had already published live, and names them.

The error says what it removed, in error.thread_rollback, and the code tells you whether a retry is safe:

• 502 upstream_error: still_live is empty. Nothing of the thread is on the platform, so repeating the same request is safe.
• 502 thread_rollback_incomplete: Chirpie could not remove everything. The posts in still_live are really still up, with their ids and public URLs. Repeating the request would publish them a second time, so remove them first, or post only the remaining parts.

rollback_supported: false means Chirpie cannot delete a published post for that account, so nothing could be removed. On Instagram that is the case for an account connected through Instagram: such a thread leaves every part it had already published live, and says which. An Instagram account connected via Facebook rolls back. See the delete table.

A scheduled thread that fails is retried three times before Chirpie gives up. The one exception is a rollback that left posts live: that thread fails at once, because a retry would publish them twice, and the reason names them.

The full response shape, with examples: A thread that failed part-way.

POST /api/v1/threads
Authorization: Bearer chirpie_sk_YOUR_KEY
Idempotency-Key: 8f1c0e0c-6d51-4d73-9f4e-6b2a0a2d3f11
Content-Type: application/json

Headers

A thread is the request most worth sending a key with: it is the longest-running call in the API, so it is the one most likely to time out on your side after Chirpie has already started publishing.

Request Body

First comment on a thread

first_comment on a thread is one comment for the whole thread, published under the last part, and reported on that part's first_comment. It is the same field, and the same rules, as a first comment on a post: X, Threads, Instagram and Facebook only, refused with 400 first_comment_unsupported anywhere else, and counted as one post against your monthly quota.

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "posts": [
      { "text": "We rebuilt scheduling this week." },
      { "text": "Queued posts now publish within five minutes of their time." }
    ],
    "first_comment": "Full write-up: https://example.com/blog/scheduling"
  }'

Every other part comes back with first_comment: null. A failed first comment never fails its thread: the thread publishes, the last part carries first_comment.status: "failed" with a reason, and POST /api/v1/posts/:id/first-comment on that part sends it again.

Publishing options on a thread

configuration works on a thread exactly as it does on a post, with one extra rule: a thread publishes to the feed. An Instagram story or reel, and a Facebook Page story, are each a single post, so a thread naming either placement is refused with 400 configuration_unsupported telling you to send it with POST /api/v1/posts instead. Everything else a block carries (an Instagram collaborator, a user tag, a Facebook link) applies to every part alike.

Publishing to several accounts

Name account_ids instead of account_id and one request publishes the thread to up to 25 accounts. An account configuration takes posts, which replaces the whole array for that account:

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ids": ["ACCOUNT_A", "ACCOUNT_B"],
    "posts": [{ "text": "one" }, { "text": "two" }],
    "account_configurations": {
      "ACCOUNT_B": { "posts": [{ "text": "a" }, { "text": "b" }, { "text": "c" }] }
    }
  }'

The response is a group_id plus one result per account, in the order the accounts were named, 201 when every account succeeded and 207 Multi-Status when at least one did not. Each result entry carries thread_id and thread where a post fan-out carries post_id and post, and platform_post_url is the first part's permalink.

{
  "data": {
    "group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "results": [
      {
        "account_id": "ACCOUNT_A",
        "platform": "x",
        "success": true,
        "thread_id": "thread-uuid-here",
        "platform_post_url": "https://x.com/chirpie_ai/status/1234567890",
        "status": "published",
        "thread": { "id": "thread-uuid-here" },
        "error": null
      },
      {
        "account_id": "ACCOUNT_B",
        "platform": "bluesky",
        "success": false,
        "thread_id": null,
        "platform_post_url": null,
        "status": null,
        "thread": null,
        "error": { "code": "upstream_error", "message": "Bluesky API error: ..." }
      }
    ]
  }
}

Full detail, including what is refused whole versus per account and how quota is reserved and refunded: Post to several accounts at once.

Example

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "posts": [
      { "text": "I just shipped a feature using Chirpie. Here'\''s how it went 🧵" },
      { "text": "First, I connected my X account via OAuth. Took about 30 seconds." },
      { "text": "Then I created an API key and made my first POST request. Done." },
      { "text": "The whole thing took under 2 minutes. Try it: chirpie.ai" }
    ]
  }'

Response 201 Created

{
  "data": {
    "id": "thread-uuid-here",
    "platform": "x",
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "posts": [
      {
        "id": "post-1-uuid",
        "text": "I just shipped a feature using Chirpie...",
        "platform_post_id": "1234567890",
        "platform_post_url": "https://x.com/chirpie_ai/status/1234567890",
        "status": "published",
        "thread_order": 0,
        "created_at": "2026-03-23T10:00:00.000Z"
      },
      {
        "id": "post-2-uuid",
        "text": "First, I connected my X account...",
        "platform_post_id": "1234567891",
        "platform_post_url": "https://x.com/chirpie_ai/status/1234567891",
        "status": "published",
        "thread_order": 1,
        "created_at": "2026-03-23T10:00:00.000Z"
      }
    ],
    "status": "published",
    "scheduled_at": null,
    "group_id": null,
    "created_at": "2026-03-23T10:00:00.000Z"
  }
}

group_id is the fan-out this thread belongs to when it was created by naming account_ids, and null when it was created with a single account_id. Pass it to GET /api/v1/posts?group_id=... to read every post of the fan-out back.

Each post in the response carries platform_post_url, its own public link on the platform, every part of the thread included. See platform_post_url for the link each platform gives and the few cases where it is null.

Billing

A thread counts as N posts where N is the number of posts in the thread. Both post and scheduled limits are checked against the thread size.

A draft thread counts as zero. Nothing is charged while it sits saved, and the whole thread's quota is taken at the moment it is scheduled or published.

A first comment is a post on the platform too, so a thread that carries one counts as N + 1.

Error Responses

Scheduled Threads

When schedule_at is provided, all posts in the thread are stored with status: "scheduled". The entire thread is published atomically by the scheduler, so if any post fails, the whole thread is rescheduled for retry.

Draft threads

Send draft: true and the thread is saved without going anywhere. Every part is stored with status: "draft", nothing reaches the platform, and nothing counts against your quota until the thread is promoted.

A draft thread is held to far less than a real one: it may be a single part long while you are still writing it, and a part may have no text yet. The response carries a warnings array saying, per account, what would stop it publishing as it stands, including whether the platform will publish the parts as standalone posts rather than a reply chain.

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "posts": [{ "text": "Opening line, rest to come" }],
    "draft": true
  }'

Promote it with PATCH /api/v1/posts/:id on any of its parts: schedule_at queues the whole thread, publish: true sends all of it now, and the response names every part it promoted in promoted_from_draft_ids. Promotion runs every rule a create runs, the two-post minimum included. Deleting any part of a draft thread deletes the whole thread, and the response lists the ids in deleted_ids, and a draft thread saved to several accounts goes in one call too. Full detail: Drafts.

Cancelling a Scheduled Thread

A scheduled thread is cancelled as a unit, exactly as it is published as one. Cancelling one post in a scheduled thread cancels the thread. DELETE /api/v1/posts/:id on any post of the thread cancels every post in it, and returns their ids:

curl -X DELETE https://chirpie.ai/api/v1/posts/b2c3d4e5-... \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

{
  "data": {
    "id": "b2c3d4e5-...",
    "deleted": true,
    "cancelled_ids": ["a1b2c3d4-...", "b2c3d4e5-...", "c3d4e5f6-..."]
  }
}

Nothing is billed for a thread that never published, and the whole thread's monthly quota is returned. To change one post of a scheduled thread, cancel the thread and schedule a new one.