xpost

Workspace engagement roll-up over a window: post/delivery counts, metric totals, and a per-platform breakdown. Use this for 'how are we doing' questions and to compare platforms. Every answer carries `coverage`, and it is what tells an empty window apart from an unmeasurable one. `deliveries` is what actually went out, and the three counts under it add up to exactly that — `with_metrics` (what the totals are built from) + `unreportable` (no numbers, and none coming: deleted, expired, or never reported on) + `awaiting` (not in yet). `unsupported` is a SUBSET of `unreportable`, not a fourth bucket: deliveries nobody will ever report on — STORIES, which Instagram and Facebook report nothing about, ever. So `format: "story"` comes back with zero totals however many stories went out, and reporting that as "no stories were posted" is false: say the stories went out and their numbers are not something the platform gives anyone. `ever_delivered` ignores the window and separates "nothing in this window" from "nothing ever".

get_insights

Attach an image, video or PDF for a post. Ways to supply it: a public https `url`, a `ticket` from get_upload_ticket (the right one for a file the USER ATTACHED to this conversation — see that tool), or base64 `data` with `mime_type` for something small you generated yourself. Local file paths are not available over the hosted connector. Returns a media_id for create_post. Required for Instagram, TikTok, YouTube, Pinterest (no text-only posts). A PDF becomes a LinkedIn document post — one PDF, on its own, LinkedIn only, and the account must be one that supports documents (create_post says so if not). Accepted formats, size caps and the ticket flow: https://xpost.to/docs/api#media.

upload_media

The workspace's best posting slots (weekday × hour, UTC) ranked by average engagement from its OWN past results. Use when choosing scheduled_at. READ `signal` BEFORE THE ORDER. A ranking always comes back, and it is only advice when there is something to rank on. `"none"` means no engagement has been recorded at all — the order is arbitrary, so say there is no history yet and pick a time on other grounds rather than presenting a slot as best. `"thin"` means some slot rests on one or two posts: name the sample count when you quote it. `"ok"` means every slot has three or more.

get_best_times

Dry-run a caption against this workspace's brand guardrails (banned words/topics, link policy, posting cap) WITHOUT creating a post. Use this to fix a draft before create_post instead of burning a rejection. Returns { allowed, violations[], rules_checked[], rules_skipped[] }. READ `rules_checked` BEFORE REPORTING A PASS. An empty `rules_checked` means this project has NO guardrails configured, so `allowed: true` says nothing objected — not that the caption was checked and cleared. Saying "it passed the brand rules" about a project with an empty list is a claim nothing verified. `rules_skipped` lists rules that were asked and could not answer (the topic and tone classifiers fail OPEN by design); a clean verdict listing any of those is an incomplete check, not a pass.

check_guardrails

Create a social media post targeting one or more connected accounts. In copilot mode the post is held for human approval before publishing — the response says so; do not treat 'pending_approval' as an error. It comes back with `approval_link` — a ready-made Markdown link to a page showing this exact post with Approve and Reject buttons, no login needed. Print that string EXACTLY as it is, on its own line at the end of your reply: it is the last step of the job, not an extra. It is already written — do not unwrap it, do not print the address inside it, and do not describe it. Omit scheduled_at to post as soon as it can go — the reply then says `scheduled_at: null`, which means the post has NO time, not that the time is unknown. `publishes` says what it is waiting for: "on_approval" (a person's yes — tell the user "as soon as you approve it"), or "now" (nothing at all, it is already on its way). A post with a real slot answers "at_time" and the slot is in `scheduled_at`. Never invent a time to report. Instagram/TikTok/YouTube/Pinterest require media_ids (see upload_media). `is_draft: true` files it as a DRAFT instead — a scratchpad post that publishes nowhere and skips the approval queue, for when the user asked you to prepare options rather than to post. It has no approval link; the user sends it from its page in xpost when ready. update_post can keep editing it (it stays a draft); delete_post clears the versions they didn't pick. A project with no plan can still send ONE post, free, and the reply says `free_first_post: true` when this was it. Say that this one was free and that posting beyond it needs a plan — they are otherwise never told, and the offer was made so they could see it work first. `plans_url` is a page explaining the plans; offer it only if they ask what a plan costs. Never pitch an upgrade unprompted.

create_post

Create up to 100 posts in one call. Each row is independent and runs the full single-post path — guardrails, plan limits, and copilot approval routing all apply, so in copilot mode the batch lands in the human approval queue. accounts entries may be account ids, platform:username, or a bare username when unambiguous. Returns a per-row report; check it — some rows can fail while others succeed. A held row carries its own `approval_link`, already written as a Markdown link; print each one verbatim so every post can be approved with one click. Give every row an `idempotency_key` of its own: a call that times out may still have written some rows, and a resend with the same keys returns those as `repeated: true` instead of posting them twice.

bulk_post

Take a post you created off the board. Use it to clear up after yourself — a draft the user turned down, an extra version they didn't pick, a post they asked you to cancel — so nothing you wrote is left sitting in their approval queue for them to reject by hand. Works on your own posts only. A post waiting for approval, a draft, a rejected or failed one is deleted outright, permanently, along with its delivery records. A post that already has a time is taken OFF the schedule instead and handed back to the user, so it publishes nowhere; the reply says which happened, and you should repeat that to the user rather than reporting it as deleted. Anything already published, and anything a person approved that is no longer on the schedule, is theirs and is refused.

delete_post

Per-platform delivery receipt for a post: status, live post URL on success, error detail on failure. A successful row may also carry `note` — the post went out, but published less than was attached (X takes 4 images, Facebook won't let an app post photos and video together, a reel is one clip). Report it: a bare 'success' would overstate what was published. Check this after creating a post.

get_delivery_receipt

Change a post that has not gone out — its caption, its pictures, its time, its per-platform options. Use this for "make it shorter", "swap the photo", "move it to Friday": deleting and writing a new post loses its place in the queue and its approval link. Anything you leave out is kept as it was. Works on any post in the project that has not gone out — the person's own posts as well as yours — while it is a draft, pending approval, scheduled or rejected. A post that came back REJECTED is fixed the same way: read its `rejectionReason` in `list_posts` first, change what that reason actually named, and send it again through this tool — rather than guessing at the objection, or writing a second post and leaving the turned-down one behind. Editing a post a human already approved (or rejected) puts it back in the queue and the reply carries a fresh `approval_link`, so print that one and stop offering the old. Say plainly which of the two happened: the reply's `message` is written for the rejected case, and a person whose "no" has just been reopened deserves to be told so rather than reading "edited". The reply's timing fields work like `create_post`'s: a null `scheduled_at` means the post has no time, and `publishes` says whether it waits on a person ("on_approval") or on nothing ("now"). Leaving `scheduled_at` out of your call changes nothing about the timing — and a slot that has already PASSED is dropped rather than carried forward, because a dead time is not a plan. A post that has already been TRIED is not editable, and rewriting it would send a second copy to the accounts that worked: use `retry_delivery` on the delivery that failed.

update_post

Get an upload slot, for when a file has to reach xpost and you cannot send it — the usual case being a picture or video the user attached to this conversation. Call this whenever the user attaches media and asks for it to be posted. Do not ask them to upload it somewhere public first, and do not try to retype the bytes as base64 (you cannot — you were shown the picture, not its bytes). Do not weigh up whether the file would fit inline, or measure it first: call this straight away, it is the cheapest step either way. In an app that draws MCP Apps, the result IS a drop zone, and it already says what to do. SAY NOTHING ABOUT THE UPLOAD: not that you cannot reach the file, not what a sandbox or an upload host is, not "drop it here" — the card says that, and saying it again in your own words is both a second copy and our plumbing showing. Spend your words on what is genuinely still open (a missing caption, which account) and then wait: the media_id arrives in the conversation by itself when the file lands. Elsewhere, or when you can reach the internet: `url` and `fields` are a presigned S3 slot and `curl` is the whole upload as one command — run it with YOUR_FILE replaced by the real path, check it exits 0 with an empty body, then call upload_media with the `ticket`. That host may be blocked by your sandbox's network settings; if it is, the drop zone is the way, and telling the user to edit those settings is not. A slot lasts a few minutes and covers the files added while it is open. Get a fresh one if a step fails.

get_upload_ticket