Publish a post now
post_to_socialPublishes a post immediately and publicly to the listed platforms through the social accounts connected to the user's PostWire account. A published post cannot be withdrawn from PostWire. Accepts one text for all platforms or a separate per_platform draft for each. YouTube requires video_url; TikTok requires video_url or photos (photo_url or media); Instagram requires a photo or video, and two or more media items make a carousel. Every platform must already be connected; otherwise nothing is published and the error names the missing ones. The same payload sent twice within 2 minutes is refused as a duplicate unless idempotency_key differs. When a platform is connected in more than one brand and brand_id is omitted, nothing is published and the error lists the brands. Returns { posted, published_to, results: [{ platform, ok, id?, url?, account?, error? }] }, where account and published_to name the handle and brand each post went to. After the account's first post through this connection, next_step proposes a week of posts on the same topic for the text networks it went to (its topic and platforms); nothing is queued until the person asks for it. The plan sets how many networks one post goes out to (Free: 2): only the first platforms in the list are published and each of the others comes back with ok: false, held: true and code networks_per_post (its version was written and not sent), listed in held_networks with a one-sentence held_message, and message_for_user says it in plain words for the person; every network can still be connected and written for. TikTok and Instagram videos may still be processing when this returns (status processing, no url yet). When the networks-per-post or the monthly post limit stops a platform, the result also names the plan that lifts it, its price and a checkout link, and, for a free account that has not had one, a link to Pro with the first month 50% off (trial_offer: paid today, then the regular monthly price, cancel anytime). Such an account also gets the trial link once after its first post from an assistant, with a one-sentence trial_message. 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 used for every platform that has no per_platform draft. | |
| 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. | |
| 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 | Which brand's accounts to use. Omit to use the default brand. | |
| photo_url | No | Public https URL of an image. | |
| platforms | Yes | Platforms to publish to, all in one call, e.g. ["linkedin","bluesky"]. | |
| video_url | No | Public https URL of a video. Required for YouTube; TikTok takes a video or photos. | |
| per_platform | No | Per-platform drafts: { "<platform>": { "text": "…", "title": "…", "tags": ["…"] } }. X, Bluesky and Mastodon also take "thread" (the posts after text, in order, each a reply to the one before; media stays on the first post). LinkedIn, X, Bluesky and Mastodon take "first_comment" (posted by the author right under the post, or under the last post of a thread: the place for the link). X also calls it "reply". Pass the thread and first_comment that generate_posts returned as they are. | |
| idempotency_key | No | Optional unique key; a repeat with the same key within 24 h is refused instead of posted twice. |