xpost

Engagement over a window: totals, per platform, per format. `coverage` says how much of the window the totals rest on: `with_metrics` + `unreportable` + `awaiting` = `deliveries`. Stories are never reported on by Instagram or Facebook, so `format: "story"` totals are zero however many went out. `ever_delivered` separates an empty window from an empty history.

get_insights

Attach an image, video or PDF and get a `media_id` for create_post. Sources: `file` (an attachment from this conversation, as the host provides it), a public https `url`, base64 `data` with `mime_type`. Instagram, TikTok, YouTube and Pinterest need media; a PDF becomes a LinkedIn document post. When an attached file cannot be provided from here, create the post with `media_pending: true` instead and the person adds it in the approval card. Formats and caps: https://xpost.to/docs/api#media.

upload_media

Posting slots (weekday × hour, UTC) ranked by this workspace's own past engagement. `signal` says what the order is worth: `none` means no engagement is recorded and the order is arbitrary; `thin` means some slots rest on one or two posts (`samples`); `ok` means three or more each.

get_best_times

Dry-run a caption against the project's guardrails without creating anything. `allowed` with an empty `rules_checked` means the project has no rules, not that the text was cleared. `rules_skipped` lists rules that could not answer; a verdict listing any is incomplete.

check_guardrails

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 can hold agent posts instead, and `status` says which. The answer carries `message` and a link: `approval_link` when it waits, `preview_link` when not. `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.

create_post

Create up to 100 posts in one call. Each row runs the full single-post path — guardrails, allowance, approval — and reports on its own, so some rows can land while others refuse. A held row carries its own `approval_link`. An `idempotency_key` per row makes a resend after a timeout answer `repeated: true` instead of a second post.

bulk_post

Remove a post this key created that has not gone out. A draft, a post waiting for approval, a rejected or a failed one is deleted with its delivery records. A post already holding a time is taken off the schedule instead, and `unscheduled` with `message` says so. Posts a person approved are refused, and so is one that has gone out — removing THAT from the platform is `take_down_post`.

delete_post

Per-account delivery receipt for a post: `status`, the live URL, `plain_reason` on failure, and `note` where less was published than was attached. `approval_link` is the post as a page. Not needed straight after create_post or update_post: their card already follows the delivery live. Not needed before take_down_post either: it takes the post id and draws the post once it is down.

get_delivery_receipt

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 `approval_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.

update_post

Accounts that cannot publish right now — an expired token, a platform out of reach — each with what happened. The fix is the person reconnecting that account: `connect_url` is where they do it. An empty list means every account is healthy.

list_connection_issues