Create a post
create_postDestructive
Create a post to connected accounts — X/Twitter, Instagram, LinkedIn, Facebook, TikTok, YouTube, Threads, Bluesky, Pinterest. CREATING IT SENDS IT: no scheduled_at publishes now, one publishes then; a project may hold it instead (status says). The answer carries message and approval_link or preview_link. accounts takes each account's ref. Media is media_ids, files (attachments from this conversation) or media_pending: true, which holds the post until the picture arrives — the reply's upload_url takes a POST of the file (upload_curl), or the person adds it in the card; then it goes out on its own unless the project holds agent posts. "next_slot" takes the queue; is_draft saves without sending. Undo: update_post or delete_post before it goes out; take_down_post after, where networks allow.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Files the user attached to this conversation, as the host hands them over, in post order. They are attached after `media_ids`. | |
| caption | No | The post text. Optional only where no destination prints one: a story, or X/Instagram/LinkedIn publishing media alone. WRITE IT TO FIT EVERY TARGET: one destination over its own limit refuses the WHOLE post and nothing goes out anywhere — X is 280 as X counts it, and list_accounts gives each account its `caption_chars_available`. Words the person wrote are theirs: where they do not fit, say so and ask, never quietly shorten them. | |
| accounts | No | Where it posts: each account's `ref` from list_accounts ("x:someone"). LIST EVERY ACCOUNT THIS POST GOES TO — one post, many accounts; a platform that needs different words gets them in platform_configurations.<platform>.caption, never a post of its own. A person reads this request before approving it, and the ref is what they can check. A ref matching nothing refuses the whole post. | |
| is_draft | No | Save as a draft: visible in xpost, publishing nowhere until a person sends it. | |
| media_ids | No | Media ids from upload_media; first is the carousel lead. | |
| scheduled_at | No | ISO 8601 with Z or an offset, or "next_slot" for the project's own posting schedule (get_project shows `queue`). Omit to publish now — or, on a project that holds agent posts, as soon as it is approved. | |
| media_pending | No | The picture is still to come: the person adds it in the approval card. Lets a post for Instagram, TikTok, YouTube or Pinterest be created without media; it goes out once the media is on it (or, on a project that holds agent posts, can be approved then). | |
| idempotency_key | No | Your own id for THIS request, unique to it (not to the subject). A retry with the same key returns the post the first call made, as `repeated: true`, instead of a second post. | |
| social_account_ids | No | Deprecated name for `accounts`. | |
| platform_configurations | No | Per-platform options keyed by platform: `caption` is that platform's own text (so one post can say it differently on X and on Instagram), `placement` picks "reels"/"stories" where offered. Which keys each account takes is what get_posting_rules answers. Example: {"instagram": {"placement": "stories"}, "x": {"caption": "the short one"}} |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| ok | No | Present and false only on a refusal. | |
| error | No | What was refused, in a sentence, when `ok` is false. | |
| shown | No | Where this post is already on screen, and that a receipt call now would show it a second time. | |
| status | No | pending_approval | scheduled | processing | draft | |
| caption | No | ||
| message | No | About this post, written to be passed on: why it is held, or that a draft goes nowhere until someone sends it. | |
| missing | No | What the post still lacks before it can go out. | |
| repeated | No | This idempotency_key was already used — `id` is that earlier post, nothing new was written. | |
| replaced | No | update_post: the id of the post this one replaced. That post and its approval link are gone; this post's link stands in for them. | |
| timezone | No | ||
| plans_url | No | Public page explaining what the plans include. Sent with free_first_post, with publishing_needs_plan, and on a refusal with error_code needs_plan. | |
| publishes | No | What has to happen before it goes out. Null on a draft or a rejected post. | |
| retriable | No | False when asking again cannot change the answer. | |
| attach_now | No | This host cannot send the file: the person adds it in the card, which offers its drop zone straight away. | |
| created_at | No | ||
| error_code | No | Machine reason for a refusal. | |
| plans_link | No | The same page as a ready-made Markdown link. On a refusal with error_code needs_plan, include it in the reply as-is — it is where the person activates a plan. | |
| upload_url | No | On a held post: where a picture is POSTed as multipart form-data with a `file` field, no key needed. An environment that holds the file can run `upload_curl`; the person's card uses the same door. | |
| connect_url | No | Where an account is connected. On a refusal about an account that is not there. | |
| needs_media | No | A draft with no picture or video for a destination that needs one; `missing` names them. It cannot be sent as it stands — attach media with update_post, or the person adds it in xpost. | |
| release_url | No | After POSTing every file to upload_url, POST this once and the post goes out. In the card the person presses it instead. | |
| replaced_by | No | The id the post has now, when you asked with one an edit retired. An edit gives a post a new id: get_delivery_receipt and get_post_metrics answer for this current version (and `asked_for` is the id you sent); update_post and delete_post refuse with error_code `replaced`. Use this id from here on. | |
| upload_curl | No | The upload as one shell command, YOUR_FILE replaced by the path. | |
| preview_link | No | A post nobody has to approve, as a ready-made Markdown link to it — the post as each network will draw it, its slot if it has one, and the receipt per account once it has gone. A DRAFT gets one too: it has no slot and nothing is waiting, and the link is the only way the person can see what was written without going to look for it. Give it to the person. | |
| queued_posts | No | How many posts are scheduled, none of them going anywhere beyond the free first one. Sent with publishing_needs_plan on a scheduled post. | |
| scheduled_at | No | The slot it got. NULL when it waits on approval — never a stand-in time. | |
| approval_link | No | A ready-made Markdown link to the post as a page, with Approve and Reject on it. | |
| free_post_now | No | Refused only because it was scheduled. The same call with no scheduled_at publishes now, free. | |
| pace_warnings | No | Accounts getting more posts in one day than the network likes — it may treat that as spam. Nothing is held. Mention it to the person once and offer to spread the rest out; don't stop to ask on every post. | |
| awaiting_media | No | Created without its picture (media_pending). It cannot be approved until one is on it. | |
| drafts_waiting | No | How many drafts are now waiting, none of them on its way anywhere. Sent with publishing_needs_plan. | |
| free_post_ride | No | With free_first_post: this post reached another of their accounts as part of the same free first post, sent in the same reply. One free delivery per account, within a few minutes of the first. | |
| replaced_draft | No | This post FINISHED a draft that held the same words for the same accounts: that draft is gone and this post stands in for it. Say there is one copy. | |
| connect_message | No | ||
| free_first_post | No | This post is the user's one free post — no plan was needed for it. | |
| upload_max_bytes | No | The most `upload_url` takes in one request; bigger files go through the card. | |
| releases_on_media | No | Held for its picture only: it goes out on its own once every picture is on it. Nothing to approve. | |
| first_post_message | No | About that, written to be passed on; it carries the next step. | |
| x_trial_link_limit | No | X will not receive this post: the trial's posts with a link on X are used up. Every other account still gets it. Without the link, X gets it as usual. | |
| x_monthly_link_limit | No | X will not receive this post: this month's posts with a link on X are used up on their plan. Every other account still gets it. Without the link, X gets it as usual. | |
| publishing_needs_plan | No | Nothing here can publish beyond the one free post: sending needs an xpost subscription. Nothing REFUSES a draft or a scheduled post any more — a queue may be filled without one — so this is the only warning, and it is worth passing on as it is written rather than discovered one slot at a time. | |
| free_post_awaiting_approval | No | Refused because their free first post is already waiting for their approval; approval_link opens it. Nothing needs buying. |