Schedule a post
schedule_postQueue posts to multiple social platforms at a future time or the next free slot, and get back the scheduled item with chosen time, platform handles, and brand it will publish to.
Instructions
Queues a post to be published at a future time (run_at, ISO 8601 with timezone, up to 365 days ahead), or in the brand's next free queue slot (run_at "next_slot": the earliest weekly slot all its platforms share that no other waiting post of the brand uses; the result gives the time chosen) through the connected accounts. Takes the same content fields as publishing now. Every platform must already be connected and media must suit each platform, or it is refused now instead of failing later. When a platform is connected in more than one brand and brand_id is omitted, nothing is queued and the error lists the brands. Returns the queued item with its id and, for each platform, the handle and brand it will publish to. The plan sets how many posts can wait in the queue at once (Free: 3): past that the post is not refused but saved as held (code queue_limit, status held) — kept, never published on the current plan, and scheduled automatically when the plan is upgraded; the result then also gives that plan, its price and a checkout link. On a plan with a networks-per-post limit (Free: 2) only the first platforms are published when it runs; the result names the others in held_networks. A queued or held post can be canceled before it runs. X (Twitter) is a pay-per-use add-on on paid plans: each X post uses X credits (1 for a plain post, 10 for a post with a link, +1 per image or video) from the plan's monthly X credits, then from top-up credits; a post without enough credits is not sent to X and its result says how to get more. An X thread: per_platform.x.thread is the list of posts after per_platform.x.text (up to 25, each at most 280 characters as X counts them, a link counts 23); per_platform.x.reply is one more post under the last one, the usual place for a link. Each post of a thread or reply is an X post: it uses credits by the same rule and counts toward the daily X limit, and the whole chain is reserved before anything is sent. Write a thread only when the user asks for one. The X result then has thread.tweets (every post's id), thread_url, and thread.status: complete, or pending when X refused a later post (the first post stays published and PostWire retries the rest on its own). If the brand's approval rules or a limit on this API key or connected app hold the post, nothing is published: the result has status "pending_approval", the post's id and approval_id, who was notified and a review link, and the post goes out once a person approves it from the emailed link or the PostWire dashboard — an AI assistant or an API key cannot approve it. A limit on this key or app can also refuse a post with code key_network_not_allowed, key_brand_not_allowed or key_monthly_cap_reached.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Post text for platforms without a per_platform draft. | |
| label | No | Optional short label shown in the PostWire queue. | |
| media | No | Several images (or images and videos) in one post, in order: an Instagram carousel (up to 10), TikTok photo post (up to 35 images; PNG is converted to JPEG automatically for Instagram and TikTok), Bluesky (up to 4 images), Mastodon (up to 4), LinkedIn (up to 20 images, or one PDF document). Networks that take one item get the first. Each item: { url, type: image|video|document, alt? }. | |
| title | No | Title, used by YouTube. | |
| run_at | Yes | When to publish: ISO 8601 with offset, e.g. "2026-10-01T09:00:00-05:00", or "next_slot" for the brand's next free queue slot. | |
| privacy | No | Who can see the TikTok and YouTube posts: public (everyone), unlisted (YouTube), friends (TikTok mutual followers) or private (only the account owner). TikTok asks that the account owner choose this for each TikTok post. Without it a TikTok post goes out private and YouTube uses the channel default. | |
| brand_id | No | Brand whose accounts to use; omit for the default brand. | |
| timezone | No | With run_at next_slot: the IANA timezone to read the slots in when the brand has none saved, e.g. "America/Lima". | |
| photo_url | No | Public https URL of an image. | |
| platforms | Yes | Platforms to publish to. | |
| video_url | No | Public https URL of a video (YouTube needs one; TikTok takes a video or photos). | |
| per_platform | No | Per-platform drafts: { "<platform>": { "text": "…" } }. X, Bluesky and Mastodon also take "thread": ["…"] (the posts after text; X max 25, Bluesky and Mastodon max 9 more, each within the network's limit). LinkedIn, X, Bluesky and Mastodon take "first_comment": "…" (posted by the author under the post, or under the last post of a thread: the place for the link; on X it is an X post and uses credits). X also calls it "reply". | |
| upload_method | No | TikTok only, videos only: the "upload method" editors use so TikTok leaves the file as exported. PostWire rewrites the MP4 header on the way to TikTok (nothing is re-encoded, no size limit beyond the usual 1 GB). max is the usual choice; safe changes the header only. Off unless given. |