Posts

Create a Post

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

Headers

Request Body

Publishing to several accounts

Name account_ids instead of account_id and one request publishes to up to 25 accounts, each with optional per-account text and media in account_configurations. The response is a group_id plus one result per account, 201 when every account succeeded and 207 Multi-Status when at least one did not.

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ids": ["ACCOUNT_A", "ACCOUNT_B"],
    "text": "Shipping new features today!",
    "account_configurations": {
      "ACCOUNT_B": { "text": "Shipping new features today. Write-up on the blog." }
    }
  }'

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

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

First comment

first_comment publishes one comment under the post the moment the post goes out: the "link in the first comment" pattern. The comment is posted by the same account as a reply to the post, is recorded as one of your own comments, and appears in the post's comment thread with own: true.

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

Which platforms take one

Sending first_comment to any other platform is refused with 400 first_comment_unsupported, naming the platform that refused and the four that take one. It is never silently dropped.

Length, and what it costs

The character limit is the account's own post limit: 280 on standard X, 25,000 on X Premium, 500 on Threads, 2,200 on Instagram, 63,206 on Facebook.

A first comment is a post on the platform, so it counts as one post against your monthly quota, exactly as a comment reply does. On X, a first comment whose text contains a link carries the same link-post charge a link post does: $0.25 on paid plans, and on the Free plan the request is rejected with 402 x_link_posts_require_paid_plan before the post is published, so nothing goes out. X accounts connected with your own X API credentials are exempt.

Where else it can be sent

• POST /api/v1/threads: one comment for the whole thread, published under the last part and reported on that part.
• Fan-out requests: a top-level first_comment applies to every account. An entry in account_configurations may replace it with its own, or set it to "" so that account publishes with no first comment, which is how one request reaches an account whose platform has none. See Post to several accounts at once.
• Drafts: stored with the draft and carried into the post when the draft is promoted. See warnings.
• PATCH /api/v1/posts/:id: replaces the first comment, and the empty string "" removes it.
• Scheduled posts: the first comment stays pending until the post publishes. Both go out at the scheduled time, the post first.

What comes back

Every post payload carries first_comment: null when none was asked for, and otherwise an object.

{
  "first_comment": {
    "text": "Full write-up: https://example.com",
    "status": "posted",
    "comment_id": "6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "error": null
  }
}

Publishing options

configuration says how a platform should publish this post, keyed by platform slug. One post can mean different things on different platforms: an Instagram account takes the same picture as a feed post, a story or a reel, and a Facebook Page takes it as a feed post or a story. Every other platform publishes one way and takes no configuration block.

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Behind the scenes of this week.",
  "media_urls": ["https://example.com/clip.mp4"],
  "configuration": {
    "instagram": { "placement": "reel", "share_to_feed": true }
  }
}

Each platform's placements, the options each one carries, the media rules per placement and what can and cannot be deleted: Instagram publishing options and Facebook publishing options.

Four rules apply to every block:

• Nothing is dropped quietly. A block keyed on a platform that takes no options, on a platform no account in the request uses, or a field the chosen placement does not carry, is refused with 400 configuration_unsupported naming the platform and the field. Nothing is published.
• One block per platform, not per account. A top-level configuration applies to every account of that platform in the request. An entry in account_configurations replaces the whole block for one account, rather than merging into it.
• A story or a reel is a single post. A thread asking for either placement is refused; send it with POST /api/v1/posts.
• A story carries no caption and no first comment. Send the post with empty text, and leave first_comment out.

The placement decides the media rules too, so a story is held to a story's limits rather than the feed's. On a PATCH, configuration: {} puts a post back to a plain feed post.

Media Support

Pass public URLs in media_urls, or upload the files first and name them in media. Chirpie downloads, validates, and uploads them to the target platform automatically. Use one of media, media_ids and media_urls, not several: sending two is refused with 400 bad_request. Full detail, including alt text and the upload endpoint: Media.

More platforms coming soon.

Example

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Shipping new features today!",
    "media_urls": ["https://example.com/screenshot.png"],
    "schedule_at": "2026-04-01T14:00:00Z"
  }'

Response 201 Created

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform": "x",
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Shipping new features today!",
    "media_urls": null,
    "first_comment": null,
    "platform_post_id": null,
    "platform_post_url": null,
    "status": "scheduled",
    "scheduled_at": "2026-04-01T14:00:00.000Z",
    "published_at": null,
    "thread_id": null,
    "thread_order": null,
    "group_id": null,
    "error_message": null,
    "retry_count": 0,
    "created_at": "2026-03-23T10:00:00.000Z"
  }
}

group_id on a returned post

Every post object carries group_id: the fan-out it belongs to when it was created by naming account_ids, and null when it was created with a single account_id. Pass it to List Posts to read every post of the same fan-out back. Thread objects carry it too.

account_id on a returned post

Every post object carries account_id, the account it went out through. It is null when that account has since been disconnected: disconnecting removes the connection but keeps everything the account published, so an old post outlives the account it belongs to. platform still says where the post went.

On a request body account_id is always required; only a returned post can carry null.

platform_post_url

Every post object (create, get, and list) carries platform_post_url: the public link to the post on the platform. It is null until the post is published.

Most platforms' links are built from platform_post_id. Threads and Instagram answer a publish with an internal media id that no public link can be built from, so Chirpie asks the platform for the post's own link the moment it publishes and keeps it. That covers every part of a thread, carousels, and reels.

Two cases can still leave it null on Threads or Instagram:

• The platform gave no link. Instagram may return none for a story, and omits it for media it has flagged for copyrighted material. A story is only visible for 24 hours in any case.
• The link could not be read when the post went out. The post is published all the same, since a missing link never fails a post. The next GET /api/v1/posts/{id} asks the platform once more and keeps the answer, so from then on every listing carries it too. Listings never ask the platform themselves.

A Telegram message in a private chat or a group with no public @name has no public link, and stays null.

error_message and retry_count

Every post object carries both, so a post that is not where you expected it can say why without a second request.

The last three come with status: "deleted": Chirpie cancelled the post rather than you deleting it, and the monthly quota it had reserved was returned. The account's inactive_reason says the same thing from the other side. See When a connection dies.

retry_count is how many publish attempts have been made. Chirpie retries a failing scheduled post three times before giving up, so a post still scheduled with a non-zero retry_count has already missed at least one attempt and is waiting to try again.

Comments on a post

Once a post is published, the comments it receives are available through the Comments API, keyed on the post's id: GET /api/v1/posts/:id/comments. From there you can reply to a comment, hide it, or delete it, on the platforms that allow each. A reply counts as one post against your monthly quota.

A first comment is one of those comments: it is listed with the rest, carries own: true, and its comment_id is the id you hide or delete it by.

Error Responses

Drafts

Send draft: true on a create call and Chirpie saves the post and does nothing else. Nothing reaches the platform, nothing is queued, and nothing is charged: a draft counts against neither your monthly post quota nor your scheduled post quota until you promote it.

Because a draft is work in progress, the usual checks are relaxed. text may be empty or left out, media may be missing even on a platform that normally requires it, a draft thread may be a single part where a real thread needs at least two, and schedule_at is only the time you have in mind: it is remembered, it is not a promise to publish, and it may already have passed.

What is still refused outright, with the same codes as always: an account id that is not yours or is not active (404 not_found), a media id you do not hold (404 media_not_found), an unknown top-level field, text over 25,000 characters, more than 25 ids in account_ids, a duplicate id, and two media spellings in one request (the rest are 400 bad_request).

Save a draft

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Half an idea. Finish it later.",
    "draft": true
  }'

The post comes back with status: "draft". account_ids works the same way, and the answer is then the fan-out shape, a group_id plus one result per account, with success: true and status: "draft" on every entry. POST /api/v1/threads takes draft too.

warnings

Every draft response carries a warnings array, and an empty array is the useful answer "nothing would go wrong". Each entry says, for one account, what would happen if the draft were sent as it stands, so you find out while you are still writing rather than at publish time.

{
  "data": {
    "id": "a1b2c3d4-...",
    "platform": "bluesky",
    "account_id": "550e8400-...",
    "text": "A long first attempt...",
    "status": "draft",
    "scheduled_at": null,
    "published_at": null,
    "warnings": [
      {
        "account_id": "550e8400-...",
        "platform": "bluesky",
        "code": "bad_request",
        "message": "Text must be 300 characters or less (Bluesky account). Got 400."
      }
    ]
  }
}

Anything that would really be refused carries the same code and the same sentence the API would answer the send with, so there is one vocabulary to read rather than two: bad_request, unsupported_media, first_comment_unsupported, configuration_unsupported, x_link_posts_require_paid_plan. A draft carries its first_comment and its configuration too, into the post it becomes when it is promoted, and a draft whose account cannot take one comes back with a first_comment_unsupported warning rather than an error. Three codes describe a change rather than a refusal:

A warning never stops the save. The draft is stored either way.

Finish and promote a draft

A draft is edited with PATCH /api/v1/posts/:id like any other post that has not gone out, and an edit of a draft is relaxed in the same way: the text may be cleared, and anything that would be refused comes back on warnings rather than as an error. An edit that leaves the post a draft answers with the draft and its warnings.

Two fields promote it, and promotion is always explicit:

# Queue it for a time
curl -X PATCH https://chirpie.ai/api/v1/posts/DRAFT_ID \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule_at": "2027-04-01T14:00:00Z"}'

# Send it now
curl -X PATCH https://chirpie.ai/api/v1/posts/DRAFT_ID \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"publish": true}'

publish: true and schedule_at are never valid together and answer 400 bad_request. To change the time a draft remembers without promoting it, send draft: true alongside schedule_at. draft: false is refused with a 400 saying to send schedule_at or publish: true instead.

Promotion runs every rule a create runs, the character limits, the media rules, the X link surcharge, the 5 minute spacing between scheduled posts and the two-post minimum for a thread, and spends the quota the draft never spent. If any of that refuses, the draft is left exactly where it was, unchanged.

The answer is the new post, carrying promoted_from_draft_id, or promoted_from_draft_ids on a draft thread, which names every part that was promoted. A promoted draft becomes a new post with a new id, and the draft itself is gone. A draft thread is promoted whole: promoting any part queues or publishes all of it.

On a post that is not a draft, publish and draft are both 400. A draft somebody else already promoted answers 409 post_not_editable, the same as a post that has already gone out.

List and delete drafts

curl "https://chirpie.ai/api/v1/posts?status=draft" \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Ask for them by name. A listing with neither status nor group_id is the record of what has been sent, queued or tried, so drafts are left out of it. ?status=draft is how you read them back, and ?group_id=… returns everything one request created, drafts included.

Drafts never enter the scheduler's queue and never publish on their own. DELETE /api/v1/posts/:id on a draft removes it and refunds nothing, because nothing was charged. A draft is deleted as the one thing you saved: every account it was addressed to and every part of it go together, and the response always lists the ids in deleted_ids, however many there were.

From the dashboard

The compose dialog has a Save draft button in both Post now and Schedule mode. Saved drafts live on the Drafts tab of the Schedule page, newest first, each card showing its accounts, its text, how many parts and how many media items it carries, and the time it remembers. Open puts it all back in the compose dialog, where you can save it again, schedule it, or post it.

List Posts

GET /api/v1/posts
Authorization: Bearer chirpie_sk_YOUR_KEY

Query Parameters

status=draft returns the posts you have saved but not sent. See Drafts.

status=deleted returns the posts you deleted. Deleting a post never removes it from Chirpie: the row keeps its id, its text and its history, and only its status changes. It stays in an unfiltered listing, where the dashboard shows it as "Deleted". To stop seeing a post without touching the platform, hide it.

Example

curl "https://chirpie.ai/api/v1/posts?status=published&limit=10" \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Response 200 OK

data is a plain array of post objects, newest first, in the same shape as a create response. There is no total count or cursor: page with limit and offset, and stop when a page comes back shorter than limit.

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "text": "Hello world!",
      "status": "published",
      "platform_post_id": "1234567890",
      "platform_post_url": "https://x.com/chirpie_ai/status/1234567890",
      "published_at": "2026-03-23T10:01:00.000Z"
    }
  ]
}

Get a Post

GET /api/v1/posts/:id
Authorization: Bearer chirpie_sk_YOUR_KEY

Response 200 OK

Returns a single post object (same shape as list items).

Update a Post

Edit a post that has not gone out yet: its text, its media, or the time it publishes. The same endpoint finishes a draft, and promotes it when you ask it to: schedule_at queues the draft, publish: true sends it now.

PATCH /api/v1/posts/:id
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json

Request Body

Every field is optional, and only what you send changes.

Only a post that has not published yet can be edited: a scheduled post or a draft. A post that is publishing, published, failed or deleted is refused with 409 post_not_editable, and so is a draft somebody else has already promoted.

Editing does not count against your quota.

Example

curl -X PATCH https://chirpie.ai/api/v1/posts/a1b2c3d4-... \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Now with the typo fixed"}'

Move it to a new time instead, changing nothing else:

curl -X PATCH https://chirpie.ai/api/v1/posts/a1b2c3d4-... \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule_at": "2027-04-02T09:00:00Z"}'

Response 200 OK

The post as it now stands, in the same shape as every other post object. When a schedule_at was given, rescheduled_post_ids names every post that moved.

{
  "data": {
    "id": "a1b2c3d4-...",
    "platform": "x",
    "account_id": "e5f6g7h8-...",
    "text": "Now with the typo fixed",
    "media_urls": null,
    "status": "scheduled",
    "scheduled_at": "2027-04-01T14:00:00.000Z",
    "published_at": null,
    "created_at": "2027-03-30T10:00:00.000Z"
  }
}

Errors

Retry a First Comment

Post a first comment that failed, again. The request has no body: it re-sends the text the post already carries.

The text cannot be changed once the post is out. PATCH /api/v1/posts/:id refuses a published post with 409 post_not_editable, so write or change a first comment while the post is still a draft or still queued. If the platform keeps refusing the comment, post it yourself.

POST /api/v1/posts/:id/first-comment
Authorization: Bearer chirpie_sk_YOUR_KEY
Idempotency-Key: retry-first-comment-a1b2c3d4

An optional Idempotency-Key makes a retry of this call safe: the same key on the same post replays the original answer for 24 hours rather than sending a second comment. See Idempotency.

curl -X POST "https://chirpie.ai/api/v1/posts/a1b2c3d4-.../first-comment" \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Response 200 OK

The post, in the same shape as every other post object, with first_comment.status now posted.

{
  "data": {
    "id": "a1b2c3d4-...",
    "platform": "x",
    "status": "published",
    "first_comment": {
      "text": "Full write-up: https://example.com",
      "status": "posted",
      "comment_id": "6f1c2d3e-...",
      "error": null
    }
  }
}

A retry that works costs one post from your monthly quota, exactly as the first attempt would have.

Errors

A retry runs every check the first attempt ran, so it can also answer with any of those refusals: 429 usage_limit_exceeded when the month's posts are spent, 429 first_comment_rate_limited when the platform is throttling posts from the account, 402 x_link_posts_require_paid_plan for a link on the Free plan, 409 comment_permission_required when the account needs reconnecting, and 501 platform_coming_soon for a platform that is not open yet. The post stays published in every case.

Delete a Post

DELETE /api/v1/posts/:id
Authorization: Bearer chirpie_sk_YOUR_KEY

On a published post, delete means delete on the platform. Chirpie tells the platform first, and reports the post deleted only once the platform confirms it is gone. A post the platform says it has never heard of, or has already removed, counts as gone.

On a post that has not gone out, there is nothing to tell a platform. A queued post is cancelled and its quota returned, and the answer names every row that went with it in cancelled_ids. A draft is simply marked deleted and the answer names its rows in deleted_ids: nothing is returned, because a draft never counted against anything in the first place.

The post is never removed from Chirpie. It keeps its id, its text and its history, with status: "deleted". GET /api/v1/posts/:id still returns it, ?status=deleted lists it, and the dashboard shows it as "Deleted". Nothing a delete does is ever a hole in your record.

Which platforms Chirpie can delete from

Response 200 OK

{
  "data": {
    "id": "a1b2c3d4-...",
    "deleted": true
  }
}

Cancelling a post that belongs to a scheduled thread returns every id it cancelled:

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

Errors

Hide a Post

POST /api/v1/posts/:id/hide
POST /api/v1/posts/:id/unhide
Authorization: Bearer chirpie_sk_YOUR_KEY

Hiding takes a post out of your Chirpie listings. Nothing reaches the platform. The post stays exactly as it is, keeps its analytics and its comments, and unhide puts it back. Nothing is charged and no quota moves.

This is the answer to "I do not want to see this any more". DELETE is the answer to "take it down", and the two are never the same request. Hiding is also the only thing on offer for a post Chirpie cannot delete, such as a published TikTok post.

A hidden post is left out of GET /api/v1/posts unless you pass include_hidden=true, on every filter. It is always readable by id with GET /api/v1/posts/:id, and every post payload carries hidden.

A thread, or a fan-out made in one request, is hidden as the one thing it was made as, so hidden_ids can name more posts than the one you passed. Unhiding a post that was never hidden succeeds and changes nothing.

curl -X POST "https://chirpie.ai/api/v1/posts/a1b2c3d4-.../hide" \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Response 200 OK

{
  "data": {
    "id": "a1b2c3d4-...",
    "hidden": true,
    "hidden_ids": ["a1b2c3d4-...", "b2c3d4e5-...", "c3d4e5f6-..."]
  }
}

Errors