Chirpie

Activate a connected account so it can publish. Use for accounts listed with `is_active: false`, for example extra Facebook Pages imported beyond the plan's account limit. Fails with a plan-limit error if no slot is free; deactivating another account frees one.

Get analytics (likes, reposts, replies, etc.) for a published post on X, Bluesky, LinkedIn, Threads, Mastodon, Instagram or Facebook. Note: Telegram does not expose analytics. The numbers come from a stored snapshot that is at most an hour old, so calling this often costs nothing; set refresh to ask the platform now instead.

Connect a Bluesky account using an app password (create one at https://bsky.app/settings/app-passwords).

Start the OAuth flow for a Facebook Pages account. Returns an authorization_url the user must open in a browser to complete the connection. Coming soon.

Start the OAuth flow for an Instagram account. Returns an authorization_url the user must open in a browser to complete the connection. There are two routes and they differ in what the account can do afterwards: `instagram` signs in with Instagram and needs no Facebook Page, while `facebook` signs in with Facebook, connects the Instagram professional accounts linked to the Pages the user shares, and is the only route where chirpie_delete_post can remove a published Instagram post. One Facebook grant can connect several accounts at once; any beyond the plan's account limit are stored switched off rather than dropped. Coming soon.

Start the OAuth flow for a LinkedIn profile account. Returns an authorization_url the user must open in a browser to complete the connection.

Start the OAuth flow for a Mastodon account on a specific instance.

Connect a Telegram bot. Create a bot with @BotFather on Telegram, then pass the bot token and the chat ID (user, group, or channel).

Start the OAuth flow for a Threads account. Returns an authorization_url the user must open in a browser to complete the connection. Coming soon.

Start the OAuth flow for a X/Twitter account. Returns an authorization_url the user must open in a browser to complete the connection.

Create a new Chirpie API key. Returns the full key once: keys are prefixed `chirpie_sk_` and the API never shows one again. Named scopes give a key that can do less than the calling key: a key created without any can do everything the key that made it can, and a key can never grant a scope it does not itself hold.

Deactivate a connected account. It stops publishing and frees a slot against the plan's account limit, but stays connected so it can be activated again without reauthorizing. CANCELS the account's scheduled posts: a deactivated account cannot publish, so every post queued against it is cancelled and its monthly quota returned, and `canceled_posts` in the response says how many. Activating the account again does NOT restore them. `scheduled_posts` in chirpie_list_accounts says beforehand how many posts this would cancel.

Delete a comment on a post you published. It is deleted from the platform first and recorded as deleted in Chirpie only once that succeeded, so a comment is never reported gone while it is still public. On Facebook, Instagram, Threads and LinkedIn the platform deletes the replies under it too, and Chirpie records them deleted as well. Most platforms allow deleting only replies the account wrote; capabilities.delete_any from chirpie_list_comments says whether this one allows deleting somebody else's comment. A deleted comment cannot be restored.

Delete a post. If it was already published, the platform is told first, and the post is reported deleted only once the platform confirms it is gone; if the platform refuses or is unavailable the call fails with upstream_error and nothing changes, so the same request can simply be retried. If it has not gone out yet, nothing reaches a platform at all: a queued post is cancelled and its quota returned (cancelled_ids), while a draft is simply marked deleted (deleted_ids) and nothing is returned, because a draft never counted against any quota. Deleting a draft returns no quota. A published TikTok post, a Facebook Page story, and any published post on an Instagram account connected by signing in with Instagram rather than through a Facebook Page cannot be deleted through the platform's API, so each is refused with delete_unsupported rather than reported deleted and stays published; it can be deleted in the platform's own app, and chirpie_hide_post keeps it out of the Chirpie listings. THE POST IS NEVER REMOVED FROM CHIRPIE: it keeps its id and its history with status 'deleted', so chirpie_get_post still returns it. Deleting any post of a scheduled thread cancels the whole thread: a thread is published as a unit, so it is cancelled as one. Deleting a published post reaches the platform and cannot be undone; chirpie_hide_post is the reversible alternative, which changes only what Chirpie shows.

Disconnect a connected account. The connection is REMOVED: the account stops publishing straight away, frees a slot against the plan's account limit, disappears from chirpie_list_accounts, and calling this again with the same id answers 404. Reconnecting it means the user authorizing Chirpie on that platform again, whereas chirpie_deactivate_account keeps the connection so the account can come back later without reauthorizing. CANCELS the account's scheduled posts: every post queued against it is cancelled and its monthly quota returned, and `canceled_posts` in the response says how many. They are NOT restored. Posts the account already published keep their history, but stop reporting its handle and come back with `account_id: null`. `scheduled_posts` in chirpie_list_accounts says beforehand how many posts this would cancel. Cannot be undone.

Get a single post by ID. `platform_post_url` is its public link on the platform; a Threads or Instagram post published without one has it asked for again here. A post that did not go out explains itself in `error_message` and `retry_count`; when the reason is `connection_lost` the account needs reconnecting before anything else will publish, and chirpie_list_accounts says which one.

Check whether the user has registered their own X developer app. Returns configuration status and the callback URI to register on the X app, never the client secret.

Hide or unhide a comment on a post you published. Facebook, Instagram and Threads support hiding; everywhere else this reports comment_action_unsupported rather than reporting success for something that did not happen. A hidden comment stays in Chirpie's listing behind include_hidden, so the moderation history is kept.

Hide a post from the user's Chirpie listings. NOTHING REACHES THE PLATFORM: the post stays exactly as it is, keeps its analytics and its comments, and chirpie_unhide_post puts it back. Nothing is charged and no quota moves. Hiding changes only what Chirpie shows; chirpie_delete_post is what takes a post down from the platform. A hidden post is left out of chirpie_list_posts unless include_hidden is true, and is always readable by id with chirpie_get_post. HIDING A QUEUED POST DOES NOT STOP IT PUBLISHING: the scheduler pays no attention to it, and chirpie_delete_post is what stops a scheduled post going out. A thread, or a fan-out made in one request, is hidden as the one thing it was made as, so `hidden_ids` in the answer can name more posts than the id you passed.

List connected social accounts (X/Twitter, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook and Telegram), with `accounts_limit` (how many the plan allows to be active) and `accounts_active` (how many are) beside them, which say whether there is room to connect another. Accounts with `is_active: false` are connected but not publishing; `inactive_reason` says why: `"plan_limit"` means the account was connected while the plan's account limit was already full and can be switched on with chirpie_activate_account, while `"token_revoked"`, `"token_expired"` and `"reauth_required"` mean the platform stopped accepting the stored credential, so the account has to be connected again and anything it had scheduled was cancelled with its quota returned. Retrying a post does not bring an inactive account back: `inactive_reason` says whether chirpie_activate_account or a fresh connect does. An account switched off deliberately carries no reason at all, and chirpie_activate_account switches it back on. Reconnecting an account already held never needs a free slot. `scheduled_posts` is how many scheduled posts are queued against the account, all of which chirpie_deactivate_account would cancel. On LinkedIn, `account_type` says whether the account is the member's own profile (`"member"`) or a LinkedIn Page they administer (`"organization"`); both post the same way, with their own `id`.

List the comments on a post you published, newest first. Answers from Chirpie's stored snapshot, which is refreshed on a schedule, so the response carries a `sync` object saying how fresh it is (anything but status `ok` has a ready-worded sentence in `sync.reason`) and a `capabilities` object saying what this platform allows: `reply`, `hide`, `delete_own` and `delete_any`. `delete_any` says whether somebody else's comment can be deleted. Page with `next_cursor`. Listing costs nothing, but replying publishes a post and so uses one post from the monthly quota.

List the user's Chirpie API keys (prefix + metadata; the full key is only shown on creation).

List recent posts. Filter by status or account. Every post carries `error_message` and `retry_count`: on a failed post the platform's own refusal and how many attempts it took before Chirpie gave up, and on a deleted one the reason Chirpie cancelled it (`account_disconnected`, `account_deactivated`, or `connection_lost` when the platform stopped accepting the account's credential). `platform_post_url` is the public permalink once published. A post the user deleted stays in the listing with status 'deleted' and no cancel reason: Chirpie never removes a post's history. Posts the user hid with chirpie_hide_post are left out unless include_hidden is true, and `hidden` on each post says which those are.

Create a post on X/Twitter, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, or Telegram with optional media. Posts immediately or at a scheduled time. Publish to several accounts at once by naming account_ids instead of account_id, and give one of them its own text or media with account_configurations. Note: Instagram REQUIRES media. X posts whose text contains a link are billed at $0.25 each on paid plans and are rejected on the Free plan (x_link_posts_require_paid_plan); X accounts connected with your own X API keys are exempt. A spent monthly post or scheduled-post quota answers 429 usage_limit_exceeded, which waiting does not clear; the separate per-minute burst limit on the API key answers 429 rate_limited and does clear. Set draft: true to save the post without sending it: nothing reaches the platform, nothing counts against the monthly quota, the text may even be empty, and the answer carries a `warnings` array saying per account what would go wrong if it were sent as it stands. chirpie_update_post edits a draft and promotes it with schedule_at or publish: true.

Remove the user's own X developer app. X accounts connected through it stop refreshing until the keys are re-added or the accounts are reconnected through Chirpie's app.

Reply to a comment on a post you published. The reply is published to the platform like any other post, so it counts as one post against the monthly quota, and an X reply whose text contains a link is billed at $0.25 on paid plans and rejected on the Free plan. The same per-platform character limits as a post apply.

Post a first comment that failed, again. A first comment never fails its post, so a published post can be carrying first_comment with status "failed" and a reason; this re-sends the text the post already holds. That text cannot be changed once the post is out, because chirpie_update_post refuses a published post with 409 post_not_editable, so set it while the post is still a draft or still queued. A first comment is a post on the platform, so a retry that works costs one post from the monthly quota, exactly as the first attempt would have. Refusals: 404 first_comment_not_found when the post has none, 409 first_comment_not_retryable when it is already posted or the post has not published, and the platform's own refusal when the retry failed too.

Revoke a Chirpie API key by its ID. Revocation is permanent and immediate.

Register the user's OWN X developer app (from developer.x.com) so their X accounts connect through it and post against their X API credits instead of Chirpie's. Link posts from accounts connected this way are not surcharged. After setting keys, the user must add the returned redirect_uri as a callback URI on their X app and then reconnect each X account (chirpie_connect_x) to move it onto their app.

Create a thread (multiple posts) on X/Twitter, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, or Telegram. Publish to several accounts at once by naming account_ids instead of account_id, and give one of them a thread of its own with account_configurations. X, Bluesky, Threads, Mastodon, and Telegram support native reply threading. Others degrade gracefully to standalone posts. A THREAD IS ATOMIC: if any part fails, every part already published is deleted from the platform and the whole thread's quota is refunded, and the error's `thread_rollback` says what was rolled back. Two codes tell you whether a retry is safe: `upstream_error` means nothing of the thread is on the platform, so repeating the request is safe, while `thread_rollback_incomplete` means the posts named in `thread_rollback.still_live` are still up with their ids and URLs, and repeating the request would publish them twice. On an Instagram account connected by signing in with Instagram, where Chirpie cannot delete a published post, a failed thread always reports its published parts as still live. On X, each post in the thread whose text contains a link is billed at $0.25 on paid plans; on the Free plan such threads are rejected (x_link_posts_require_paid_plan). X accounts connected with your own X API keys are exempt. A thread that would cross the monthly post or scheduled-post quota answers 429 usage_limit_exceeded and publishes nothing; the per-minute burst limit on the API key answers 429 rate_limited. Set draft: true to save the thread without sending it: nothing reaches the platform, nothing counts against the quota, a draft thread may still be a single part long, and the answer carries a `warnings` array. chirpie_update_post on any of its parts promotes it, and the whole thread goes together.

Put a hidden post back in the user's Chirpie listings. The exact undo of chirpie_hide_post, and as with hide, nothing reaches the platform. Unhiding a post that was never hidden succeeds and changes nothing. chirpie_list_posts with include_hidden true lists the hidden posts.

Edit a post that has not published yet, or finish a draft. Only a post still waiting to publish can be edited; one that is publishing, published, failed or deleted is refused with 409 post_not_editable. Leaving schedule_at out keeps the time a queued post already has, so editing a queued post never publishes it and never turns it into an immediate one, and costs nothing, since it spent its quota when it was created. Rescheduling a post that belongs to a thread moves every part of that thread, and the response lists them in rescheduled_post_ids. A draft is different: it is held to far less, so an edit that leaves it too long or with no text at all is saved and answers with a `warnings` array instead of an error. Promoting a draft is the one thing this call does publish: schedule_at queues it, publish: true sends it now, both run every rule a create runs and spend the quota the draft never spent, and the answer carries the new post plus promoted_from_draft_id. draft: true alongside schedule_at changes only the time the draft remembers.

Upload an image or a video and get back the id a post can attach. Give it either a public `url` for Chirpie to fetch, or `data`, the file's bytes as base64. The file type is read from the file's own first bytes, never from its name or a declared type, so a mislabelled file is refused rather than published. The id is valid for 7 days; attach it with `media: [{ id, alt }]` on chirpie_post, chirpie_thread or chirpie_update_post. A post keeps its own copy of the bytes, so it is unaffected when the id expires. Uploads are limited to 3 MB of file when sent as `data`, which bounds the request rather than the post; attach a larger file with media_urls instead, which has no such limit.