Edit a post
update_postDestructive
Change a post that has not gone out — caption, media, time, per-platform options; anything left out is kept. The reply is a NEW post with a new id and a new link; replaced names the old one, which is gone. add_media_ids and files append to what the post holds; media_ids replaces it. A picture the person added in the approval card is already on the post. Editing an approved or rejected post puts it back in the approval queue, and message says which of the two happened. A post already tried is not editable: retry_delivery handles the delivery that failed. Send a draft with is_draft: false — creating it again instead posts the words twice.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Files the user attached to this conversation, appended after what the post holds. | |
| caption | No | The new text. It must still fit every target's own limit — X is 280 as X counts it — or the edit is refused and the post keeps its old words. | |
| post_id | Yes | The post to change — an id list_posts returned, never one built from memory. Every edit gives the post a NEW id (the answer's `id`); use that one next time. An id an edit retired is refused with `error_code: replaced` and `replaced_by`, the current id. An id this project does not hold is refused with `error_code: not_found`; read the list again rather than trying another id. | |
| is_draft | No | `false` sends a draft: it leaves the drawer and goes out at its time, or now, or to the approval queue — whichever the project does. This is how a draft is finished; creating the post again instead leaves the draft behind and publishes the words twice. `true` puts a post that has not gone out back into the drawer. Omit to keep it as it is. | |
| media_ids | No | Replaces the attachments; omit to keep them. | |
| scheduled_at | No | New time (Z or an offset); "next_slot" hands it to the project's queue; null clears it, and it goes out now — or once approved, on a project that holds agent posts. | |
| add_media_ids | No | Appended after what the post already holds. | |
| platform_configurations | No | Replaces the per-platform options; omit to keep them. |
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. |