Publish or schedule a post
chirpie_postCreate 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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Post text, and what an account with no override of its own publishes (max 280 chars for standard X, 25,000 for X Premium, 300 for Bluesky, 3,000 for LinkedIn, 500 for Threads, 500 for Mastodon, 2,200 for Instagram, 63,206 for Facebook, 4,096 for Telegram, or 1,024 for Telegram when media_urls is set) | |
| draft | No | Save the post without sending it. It is stored with status draft, nothing reaches the platform, and it costs no quota. The answer carries a `warnings` array naming, per account, anything that would stop it publishing as it stands. | |
| media | No | Uploaded files and public links, each with optional alt text. An entry takes either `id`, from chirpie_upload_media, or `url`, a public link Chirpie fetches. `alt` describes the item for people using a screen reader and is carried to X, Bluesky, LinkedIn, Mastodon, Instagram and Facebook. Use this or media_urls, not both. Images per post: X 4, Bluesky 4 (977 KB each), LinkedIn 4 (JPEG, PNG, GIF up to 8 MB), Threads 1, Mastodon 4, Instagram 10 (carousel), Facebook 10, Telegram 10. Video: X, Mastodon and Telegram only, one per post and never alongside images. Instagram REQUIRES at least 1 image. Anything a platform cannot take is refused with 400 unsupported_media, never dropped. | |
| timezone | No | The IANA timezone a schedule_at with no offset is read in, such as 'America/New_York'. Daylight saving is worked out for the date named, which is what makes '09:30 on 1 November' come out right. Ignored when schedule_at already carries an offset. Leave it out to use the timezone saved on the account. | |
| media_ids | No | Ids from chirpie_upload_media, for a post that needs no alt text. Same per-platform rules as `media`. Use one of media, media_ids or media_urls, not several. | |
| account_id | No | Account ID to post from (X, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, or Telegram). Use this or account_ids, not both. | |
| media_urls | No | Public image or video URLs, for a post that needs no alt text. Same per-platform rules as `media`. | |
| account_ids | No | Account IDs to publish the same post to, 1 to 25 of them, each named once. Naming this instead of account_id answers with a group_id and one result per account, in the order given, each with its own `success`: an account whose platform refused is reported there while the others stay published. Anything that fails the request as a whole (a character limit, a media rule, a spent quota) publishes nothing. | |
| schedule_at | No | ISO 8601 datetime to schedule the post. Either an absolute instant carrying a timezone, such as '2026-04-01T14:00:00Z' or '2026-04-01T16:00:00+02:00', or a local time with no offset, such as '2026-11-01T09:30:00', which is read in the timezone parameter or the one saved on the account and is refused when there is neither. Scheduled posts publish within ~5 minutes of this time. On a draft it is only the time you have in mind: the post is not queued for it. | |
| configuration | No | Per-platform publishing options, keyed by platform. Instagram takes a feed post, a story or a reel, and a Facebook Page takes a feed post or a story; leave it out and everything publishes to the feed. Nothing is dropped quietly: a block keyed on a platform that takes no options, on a platform no account in the call uses, or a field the chosen placement does not carry, is refused with 400 configuration_unsupported naming the platform and the field. One block serves every account of that platform; give one account its own with an account_configurations entry. | |
| first_comment | No | A comment to publish under the post the moment it goes out, the "link in the first comment" pattern. Available on X, Threads, Instagram and Facebook only: sending it to any other platform is refused with 400 first_comment_unsupported rather than dropped, and on a fan-out that refuses the whole request; an account_configurations entry whose first_comment is an empty string opts one account out. It counts as one post against the monthly quota, like a reply, and on X a first comment containing a link carries the same $0.25 surcharge a link post does and is rejected on the Free plan. It never fails the post: if it cannot be posted the post is still published and the answer carries first_comment with status "failed" and a reason, which chirpie_retry_first_comment sends again. | |
| idempotency_key | No | A key of your own making that makes retrying this call safe. The same key with the same request replays the first answer for 24 hours instead of sending it again; the same key with a different request is refused with 422 idempotency_key_reused, and a retry that arrives while the first is still running is refused with 409 idempotency_in_progress; a retry after the first has finished collects the replay. | |
| account_configurations | No | Per-account overrides, keyed by account ID. Every key must also be in account_ids. An account with no entry publishes the shared text and media. Media never merges: an account naming any media field replaces the shared media outright. Use one media spelling at a time. |