create_postdestructive | Create a social post on iHatePosting. action 'draft' saves it (the default when no date is given, and the safe choice); 'schedule' needs scheduledDate (YYYY-MM-DD) + scheduledTime (e.g. '9:00 AM' or '21:00'), the account owner's wall clock in their timezone — `ownerTimezone` from whoami, not yours or the user's device; 'now' publishes immediately to a real audience. A date with any action but 'schedule', or with no action, is refused rather than dropped. Every `scheduledAt` in the reply is UTC (it ends in Z); `scheduledLocal` beside it is the same moment as the owner's date, time and timezone — tell the user that one. Platforms with requirements — Pinterest a board, YouTube a title, TikTok and Instagram media — are set through `options` and `mediaIds`; call get_platform_rules for what each one needs, and validate_post to check before you commit. The reply lists every send it created, each naming its account (handle, displayName, nickname) AND carrying its own `postId` — tell the user what it says rather than what you asked for; they are not always the same. Its `warnings` name anything the post will not carry (images past a platform's cap, a signed-out account, a Pro-only option) — pass them on. A SCHEDULED (or 'now') multi-platform post is stored as one post per send, so that `postId` is what cancels or reschedules a single platform later without touching the others. A draft keeps every platform on ONE postId (every send in the reply shows the same one) until it is scheduled with update_post — deleting that draft deletes it for every platform. |
delete_postdestructive | Delete a post from iHatePosting. ONE SEND AT A TIME: a SCHEDULED post going to several accounts is stored as one post PER SEND, so deleting one cancels only that platform and leaves the rest scheduled — pass the `postId` that create_post returned on that particular send, or the id of the row list_posts shows for it. There is no need to cancel a whole multi-platform post to drop one platform from it. A DRAFT IS DIFFERENT: until it is scheduled, a draft is ONE post holding every platform it is aimed at (all its sends share one postId), so deleting it removes every platform — to drop one platform from a draft, use update_post with the remaining accountIds instead. The reply's `platformsRemoved` names every platform the delete took; for one send of a group, `stillScheduled` lists the sends still going out and `otherSends` the rest of the group (already published or failed), each with its status; their `scheduledAt` is UTC (it ends in Z) and `scheduledLocal` is the same moment in the account owner's timezone — report that one. THIS DOES NOT UNPUBLISH ANYTHING: a post that has already gone out stays live on the network, and deleting it here only removes iHatePosting's record of it. For that reason a published post is refused unless you pass force: true, and you should only do that after telling the user in words that the platform post will remain. A post that is publishing at this moment is never deletable, forced or not — the worker is mid-flight on it. Deleting a scheduled post stops it going out. |
get_analytics | How the posts actually performed: impressions, engagement and follower numbers per connected channel, plus the top posts. Use this to answer 'how did that do', 'which platform is working' or 'what should I post more of' — it reports what iHatePosting collected from each network, not an estimate. Some platforms report nothing (they are named in `unmeasuredPlatforms`), so a zero there means 'not measurable', not 'no reach'. If a plan ever gates a range, the answer says so in a sentence with `locked: true` rather than returning silently empty numbers. |
get_platform_rulesread-only | What each platform will and will not accept: character limit, whether media is required, how many images, video formats and length, and EVERY per-platform option it takes — `options` per platform, each with its exact key, type, allowed values, default when left out, and whether it is required (e.g. Pinterest needs boardId, YouTube needs ytTitle and ytMadeForKids; YouTube's privacy is ytPrivacy, Instagram's first comment is firstComment). Call this BEFORE writing a post — it is the difference between composing something that publishes and something the platform rejects. |
get_postread-only | Everything about ONE post: the shared text, each platform's own copy and options, the attached media, and per-send status with the live URL or the error. list_posts gives you the id; this explains what actually happened to it. Read it before update_post so you change what is there rather than overwriting it. Its `scheduledAt` is UTC (it ends in Z); `scheduledLocal` is the same moment as the owner's date, time and timezone — the values to send back as scheduledDate/scheduledTime to keep the time, and the ones to tell the user. |
get_upload_ticket | Internal: issues a short-lived ticket (10 minutes, reused by the upload box for its own requests) that the upload box uses to list, preview, upload and delete files. The upload box calls this itself. |
list_accountsread-only | List the connected social accounts (platform, handle, health) available for posting. The response also names the iHatePosting account this connection acts for — if the accounts listed are not the ones you expect, check that `account.email` is the right person before assuming anything is missing. `account.timezone` is the owner's timezone, the zone every scheduled time is read in. |
list_mediaread-only | The images and videos already in the user's iHatePosting library, newest first, with the `id` that create_post's `mediaIds` wants. Call this whenever a platform needs a file — Instagram, Pinterest, TikTok and YouTube all do — to see whether what you need is already uploaded. Returns ids and dimensions only; there is no downloadable link, by design. |
list_pinterest_boardsread-only | The Pinterest boards you can pin to, with the `id` that create_post's `options.pinterest.boardId` requires. Pinterest REFUSES a pin without a board, and a board id is an opaque number you cannot guess — call this before creating any Pinterest post. If several Pinterest accounts are connected, pass `accountId` from list_accounts, because boards belong to one account and pinning to another account's board fails. An empty list with no error means the account is connected and simply has no boards yet — make one in Pinterest first. |
list_postsread-only | List posts with per-platform status (draft/scheduled/published/failed) and live URLs. Rows sharing a `batchId` are ONE submission the person made to several accounts — report them as one post going to N places, not as N posts. ALWAYS CHECK `total` IN THE REPLY: it is the number of rows matching your filter, and `returned` is how many you got. If they differ you are holding one page, not the answer — page on with `cursor` until `hasMore` is false before you count anything or tell anyone a number. `total` counts ROWS: a scheduled post to several accounts is one row per platform (sharing a `batchId`), while a draft is one row however many platforms it has — so `total` is the number of sends, and the number of posts the person made is the rows with distinct `batchId`s (a row without one is a post on its own). A post you move LATER while paging can come round again on a later page — skip ids you have already handled; none are skipped. Use `status` and `from`/`to` to ask the real question instead of counting a page: for "how many are scheduled" pass status 'scheduled' and read `total` (sends); for a month or a date range pass from/to, which match the SCHEDULED time — a bare date is that whole day on the account owner's calendar, in the owner's timezone (the reply's `timezone`, `ownerTimezone` from whoami). Each post's `scheduledAt` is UTC (it ends in Z); `scheduledLocal` is the same moment as the owner's date and time — report that one, and send it back unchanged to reschedule_post or update_post. |
open_upload_widgetread-only | Show the person their iHatePosting media box: they can upload an image or video from their own device, browse what is already in their library with every file previewable, see how much storage their plan leaves them, pick a file to use, or delete one. THIS IS THE ANSWER WHENEVER SOMEONE NAMES A FILE ON THEIR OWN COMPUTER — a path like C:\clips\launch.mp4 or ~/Movies/clip.mov is not something any tool here can read, and explaining that is not an answer: open this instead, in the same reply, and they pick the file from a picker right in the conversation. Also use it for anything they pasted or attached here. Do NOT try to send those bytes yourself — they would travel as your own output and arrive cut short. If the file already has a public address, use upload_media with `url` instead. |
reschedule_postdestructive | Move a SCHEDULED post to a different date and time. ONE SEND AT A TIME: a scheduled post going to several accounts is stored as one post per send, so this moves just that platform and leaves the others where they are (an older row can still carry several platforms, and moves them together). A draft is refused: schedule a draft with update_post with action 'schedule', which checks each platform first and gives each its own post. Takes the post id from list_posts, plus scheduledDate (YYYY-MM-DD) and scheduledTime (e.g. '9:00 AM') read in the ACCOUNT OWNER'S timezone (`ownerTimezone` from whoami), not yours or the user's device. A post's `scheduledAt` is UTC (it ends in Z) — never copy its digits as a time; work from `scheduledLocal` (the owner's date and time) that list_posts and get_post give beside it, so 'an hour later' is an hour later. The reply's `scheduledLocal` is where the post now is. A post that has already published cannot be moved — its time is a record of what happened — and one that is publishing right now is refused until it finishes. A FAILED post is not rescheduled either: there is no upcoming slot to move, and moving it would not re-send it. Send it again with retry_post, which re-queues only the sends that failed; reschedule_post is for a post that is still scheduled. Check `status` from list_posts before calling this — on 2026-10-15 one agent called it on ten failed posts in a minute and was refused ten times. |
retry_postdestructive | Send a failed post again. ONE SEND AT A TIME, usually: a post to several accounts is stored as one post per send, so a post id normally names a single platform and retrying it touches only that one. (An older row, or a draft, can still carry several — without targetId every failed platform on that row is retried; with one, only that send.) Only a send that FAILED is retried — one that published is left alone. But a send marked failed can already be live (a timeout after the network took the post), so after a timeout check the platform before retrying. A send our own checks SKIPPED is not retried — the answer says why, and update_post is the fix. If the cause was the account rather than the post (a revoked or paused connection) the answer says so, and retrying will not help until the user reconnects. The reply's `retried` counts what went back on the queue and `skipped` names every send it left behind, with the reason. |
update_postdestructive | Rewrite a draft or scheduled post. THIS REPLACES THE WHOLE POST, so read it with get_post first and send back the complete set — anything you leave out is removed, including platforms and per-platform options. Note the shape differs from create_post: this one wants `accountIds` (the ids from list_accounts, NOT platform names) and it requires `action`. Two limits: a post that has already published cannot be rewritten at all, and a post that goes to several platforms and was saved as a group keeps the platforms it has — send back that row's own accountIds and everything else is editable, but adding or swapping an account is refused with a sentence saying so, because it would publish some platforms twice. To change which platforms a group posts to, delete it and create it again. A draft is not a group: to drop one platform from a draft, send it back without that account. SCHEDULING A DRAFT that goes to several platforms (action 'schedule' or 'now') turns it into one post per platform: the reply's `rows` lists every `postId` with its platforms, and the id you sent now names only its first platform — use the others' ids to move, cancel or retry them. A post that is being published right now cannot be edited; the answer says so — wait for it to finish. Like create_post, its reply's `warnings` name anything the post will not carry — pass them on. TIMES: scheduledDate/scheduledTime are the owner's wall clock (`ownerTimezone` from whoami); to keep a scheduled post's time, send back get_post's `scheduledLocal.date` and `scheduledLocal.time` — never the digits of its UTC `scheduledAt`. A date with an action other than 'schedule' is refused. The reply's `scheduledAt` (UTC) and `scheduledLocal` say when it now goes out. |
upload_media | Put an image or video into the library and get back an id for create_post. PREFER `url` — ALWAYS, including for a picture you just generated: we fetch it ourselves at full length, and it is the only thing that works for video or for anything more than a few kilobytes. We take whatever the link serves, so a CDN that will not name the type (application/octet-stream, as presigned S3, Drive and Dropbox links do) is fine. `base64` is a last resort for small files that exist at no address: it travels as your own output, a conversation truncates it, and the cut-off file is refused. Either way the API checks type, size and quota, then registers the file. |
validate_postread-only | Check a post against every platform you plan to send it to, WITHOUT creating anything. Runs the same checks create_post runs, so the answer is what will really happen: platform rules ('X counts this as 1200/280 characters', 'YouTube needs a title', 'TikTok slideshows take JPEG or WebP photos'), whether each account is connected and signed in, AND the account's own limits — trial expiry, whether the plan includes X, and the monthly posting allowances. Pass the same `action`/`scheduledDate`/`scheduledTime` you will pass to create_post: a cap counts the month the post is DUE, so checking without them answers a different question — and with no action it checks what create_post would make of no action, a draft, which no limit applies to. scheduledDate/scheduledTime are the account owner's wall clock in their timezone (`ownerTimezone` from whoami), and a date with an action other than 'schedule' is refused, as create_post refuses it. Anything not tied to one platform comes back under the key "account". It takes create_post's own `platforms` (platform names or account ids — an id checks that one account), `options`, `overrides` and `mediaIds`, so hand it exactly what you will hand create_post. `ok` is false only when something would stop the post; an issue with severity 'warn' (an image that will be cropped, images past a platform's cap) is worth telling the user but does not. Free to call as often as you like; use it before create_post rather than discovering a problem after the post is spent. |
whoamiread-only | Which iHatePosting login this connection acts for (email and account name), whether it connected by signing in or with an API key, and the account owner's timezone (`ownerTimezone`) — the zone every scheduledDate/scheduledTime you send is read in. Use this for any question about who the user is or which account is connected, and before working out a time like 'tomorrow at 9' or 'in two hours'. This is NOT a social media handle — the handles from list_accounts belong to the connected profiles, which may carry other people's names. |
protogrid