Antwork

Validate a signed-PUT upload and register it in the workspace media library. Second half of the LLM-on-CLI upload flow. Call this AFTER a successful curl PUT against the URL from `request_upload_url`. Verifies the GCS object exists, matches the declared mime + size, attaches a download token, and writes the workspace media record. When `attach_to_post_id` is set, also adds the uploaded media to that post, after whatever it already has. Nothing attached is removed (unlike `attach_media`, which sets the whole list). The attachment is best-effort: if it fails (e.g. wrong workspace), the response returns `attached: false` with `attachError`, but the media record still lands so you can retry `attach_media` cleanly. Args: gcs_path: The path returned by request_upload_url (under workspaces/{wid}/media/). Refused if it points outside this workspace's prefix. mime_type: Same value passed to request_upload_url. Checked against the object's stored Content-Type. byte_size: Same value passed to request_upload_url. Checked against the object's actual byte length. workspace_id: Workspace ID or name. Optional if user has only one workspace. attach_to_post_id: If set, add the new media URL to this post's existing media after registering.

register_uploaded_media

Get historical per-day engagement, as a tabular result. Returns a BigQuery-style payload in *long format* — one row per (date, platform) tuple, plus an "all" platform aggregate row per date. The host LLM can chart this directly (line per platform, stacked bars, pie of platform share, etc.) without a prebuilt visualization. Schema: - date (DATE), platform (STRING), likes, comments, shares, impressions (INTEGER), reachBasis (STRING), degraded (STRING) - "platform" values: each connected platform (e.g. "linkedin", "x") plus "all" for the daily total across platforms. A NULL is not a zero. A null in likes/comments/shares/impressions means that day was not measured for that platform — no rollup, or the platform does not report the field — and it must be drawn as a GAP, never as a point at zero. A 0 means the platform reported 0. `reachBasis` says what `impressions` counts on that row: "impressions", "views", "reach" or "reach_30d". Do not add impressions across rows with different bases, and do not compare them; they are different quantities. On the "all" row `impressions` is NULL whenever the day spanned more than one basis, because no such total exists. `degraded` lists fields whose 0 on that row is an artefact rather than a measurement — carried forward from a failed read, or rebased because the counter changed meaning that day. Exclude them from trend claims. Also returned at the top level: - `platforms`: list of platforms that appeared in the window - `platformTotals`: per-platform range totals - `rangeTotals`: workspace-wide range totals - `startDate` / `endDate`: window bounds This is the *real* day-by-day engagement earned during the window, not lifetime totals on posts published in the window. Numbers come from diffing cumulative metrics_history snapshots. Use this for: "how am I doing this week", "compare last week vs this week", "show me engagement over the last 30 days", "which day peaked". For per-post lifetime totals, use get_performance. Pass `post_id` for ONE post's history instead. The rows then carry cumulativeLikes / Comments / Shares / Impressions (totals as of that day) and dailyLikes / Comments / Shares / Impressions (earned since the previous row; NULL when unknowable), plus `spanDays` (how many days a daily value covers; older posts are read every few days, so do not chart a multi-day value as one day's spike) and `unreadableFields`. With `post_id` and no `days`, the post's full history comes back. Args: days: Trailing window in days (1–365, default 30). Includes today. post_id: One post's history instead of the workspace's. workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_engagement_history

Get engagement per published post, per platform, as a tabular result. Returns a BigQuery-style payload: - `schema.fields`: column definitions (name, type, mode) - `rows`: one row per (post, platform) with that post's lifetime totals - `rowCount`: number of rows - `platformTotals`: totals PER PLATFORM — never summed across them NEVER ADD A COLUMN ACROSS PLATFORMS. `impressions` means something different on each: true impressions on linkedin (and x with elevated scope), views on threads/youtube/tiktok/instagram, reach on facebook pages, and a rolling 30-day window on pinterest that shrinks as a pin ages. Every row carries `reachBasis` saying which. Rows whose basis differs are not comparable and must not be added, averaged or ranked together. A blank cell means the platform does not report that metric — pinterest exposes no likes, youtube no shares, a linkedin personal profile no clicks. It does NOT mean zero. `degraded` lists counters carried forward from an earlier failed read rather than measured on this one. Args: limit: Max rows to return (default 30, max 50). days: Posts published in the last N days (default 30, max 365). platform: Restrict to one platform. workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_performance

Get a single post by ID, including aggregated and per-platform metrics. Returns the post content, target platforms, status, and the latest LIFETIME engagement metrics: - `metrics`: aggregated totals across all platforms ({likes, comments, shares, impressions}) - `platformMetrics`: per-platform breakdown ({linkedin: {likes, comments, shares, impressions, ...}, x: {...}}) - `metricsUpdatedAt`: when these numbers were last refreshed - `hostSupportsUi`: True when the host renders MCP-App iframes — i.e. the response also renders an editable post-card. - `hostSupportsUiActions`: True when that card's buttons can call back into the server. ROUTE ON THIS ONE, not the flag above. Rendering a card and being able to press its Add media button are different capabilities, and ChatGPT has only the first: there the button paints and does nothing at all. Telling a ChatGPT user to "click Add media" is a dead end — and it is what this docstring used to say, because it routed on `hostSupportsUi`. See the media-attach routing in the server instructions for the per-host paths. For per-day historical engagement on this specific post (e.g. "what did this post earn each day for the last 14 days"), use get_engagement_history(post_id=...) instead. Args: post_id: The post ID. workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_post

One-stop drafting bundle: brand identity, voice, and recent posts. Call this BEFORE writing a post. It returns everything the model needs to produce on-brand, on-tone copy for a specific (workspace, platform, account) target in a single round-trip: - `workspace`: name, website, logoUrl, brandVersion - `account`: platform, accountId, accountName, accountHandle - `recentPosts`: up to 15 recent published posts on this account, each with its engagement metrics. These ARE the voice — read them and match how the account writes, weighting the ones that performed. They also tell you which themes not to repeat. Empty means no history to imitate: ask the user for samples instead of inventing. - `hostSupportsUi`: True when the host renders MCP-App iframes (claude.ai etc). Use for media-attach routing later in the flow: on UI hosts, `get_post`/`create_post` render an Add media button the user can drop a file on; on CLI hosts, use the signed-URL flow instead. Workspace identity (`name + website + logoUrl + brandVersion`) is safe to cache in host memory keyed by `antwork:ws:<workspaceId>:brand`. Re-fetch when `brandVersion` differs from the value in `get_workspace_settings`. Args: platform: Platform key ("linkedin", "x", "facebook", "instagram", "threads", "tiktok", "youtube", "pinterest"). Optional — if omitted, this returns a `connectedPlatforms` error that lists the workspace's connected platforms and active accounts, so you can retry with one of them in a single hop. account_ids: SEVERAL accounts at once, for drafting a campaign. Pass every account you are about to write for and the response carries an `accounts` list, each entry with that account's own recent posts. One call instead of one per account, which matters because each of those hits the platform's API. Fewer posts are returned per account when you ask for several, so the bundle stays a readable size — enough to hear each voice, and it is still per-account. Overrides `platform` / `account_id` when given. account_id: Specific social account ID. Optional — if omitted and the platform has exactly one active account, it's used. If the platform has MORE THAN ONE active account (e.g. a LinkedIn org page + a personal profile), this returns `error: "account_ambiguous"` with the candidates in `ambiguousAccounts` instead of guessing — ask the user which one, then retry with account_id. workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_post_context

Open the connections panel to connect, disconnect, or re-auth accounts. This renders the interactive connections-panel iframe (connect grid + per-account reauth / disconnect controls) and returns OAuth connect URLs per platform. Call this whenever the user wants to MANAGE connections — connect a new account, reconnect a stale one, or see the connect options. For just reading what's already connected, use the lighter `list_social_accounts` (no iframe). On hosts without UI, present the returned URLs as clickable links. Args: workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_connection_urls

Get the workspace's configuration: name, default posting schedule, timezone, and connected platforms. Use this to discover the workspace's preferred posting times and timezone before suggesting schedule slots, or to confirm which platforms the user has selected as their primary publishing targets. Args: workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_workspace_settings

List the social media accounts currently connected to the workspace. USUALLY UNNECESSARY for picking an `account_id`. Every workspace-scoped tool result already carries `workspaceAccounts` — `{id, platform, accountName, isActive}` for each connected account. Read that from the newest result you have. Call this when you need a field it omits (handles, token health, avatars), or when nothing recent carries the list. Text-only and fast — this does NOT render the connections panel iframe. Use it to answer account questions and to confirm target platforms are connected before drafting / scheduling / publishing. When the user wants to actually connect, disconnect, or re-authenticate an account, call `get_connection_urls` instead — that one renders the interactive connections panel (connect grid + per-account reauth / disconnect). Returns one entry per active connection with platform, account name, handle, account ID, token health, and a per-account `reauthUrl` the user can open to refresh the OAuth token. Call get_connection_urls if any expected platform is missing. Account state is mutable across turns — the user may connect or disconnect accounts in the connections panel without telling you. Other tools return a `connectionsModifiedAt` stamp; when it's newer than the one you got from your most recent list_social_accounts, the cached account list is stale and you should re-call this tool before answering. Args: workspace_id: Workspace ID or name. Optional if user has only one workspace.

list_social_accounts

List media files in the workspace media library. Returns uploaded images, videos, and PDF documents with URLs that can be attached to posts. Use this to find existing media before creating posts for visual platforms like Instagram, TikTok, or Pinterest, or for LinkedIn document posts. For libraries larger than `limit`, the response includes `nextCursor` — pass it back as `cursor` to fetch the next page. `nextCursor` is null when there are no more items. Args: media_type: Filter by type: "image", "video", "document" (PDFs), or None for all. limit: Max items per page (default 30, max 100). workspace_id: Workspace ID or name. Optional if user has only one workspace. cursor: Pagination cursor from a previous call's `nextCursor`. Omit for the first page.

list_media

List the workspace's posts, optionally filtered. Sorted scheduled (soonest first) → draft → published → failed, the rest newest-first. The posts-table iframe pages 8 rows at a time, so the default of 50 lets the user flip pages without another call. Args: status: "draft", "scheduled", "published", or "failed". query: Keyword matched against post text, case-insensitive. platform: e.g. "linkedin", "x". campaign_id: Only the posts of one campaign (from create_campaign). date_from: Scheduled on or after this date (ISO 8601, e.g. "2026-03-01"). date_to: Scheduled on or before this date (ISO 8601). limit: Max posts to return (default 50, max 50). workspace_id: Workspace ID or name. Optional if user has only one workspace.

list_posts

List all workspaces the authenticated user belongs to. USUALLY UNNECESSARY. Every workspace-scoped tool result already carries `workspaceHeader.workspaces` — the same list, with `id`, `name` and `isDefault`. Read that from the newest result you have instead of calling this. Reach for this tool only when you have no recent result to read, or when you need a field the piggybacked list omits (`logoUrl`, `website`). If the user has only one workspace, other tools auto-select it. Each entry is flagged with `isDefault: true` when it matches the user's persisted default workspace — that's the one any tool will auto-select when `workspace_id` is omitted.

list_workspaces

IFRAME-INTERNAL. DO NOT CALL FROM CHAT. Loads what the post card's settings panel needs that the post itself does not carry: a Pinterest account's boards, or a TikTok creator's current audience options. Both are live lookups against the platform, so they run when the user opens the panel rather than on every card render. Args: post_id: The post whose settings panel is open. workspace_id: Workspace ID or name. from_ui_bridge: Set ONLY by the iframe bridge. Never by the LLM.

get_post_settings

Publish every post in a campaign right now, in one call, and wait for the platforms to answer. Prefer this over calling publish_post once per post. Each publish_post waits out its own polling window, so four of them in a row can take four times as long as one and exceed the host's tool timeout. This dispatches all of them at once and polls the whole set together, so the wait is the same as for a single post. A post that cannot publish is reported on its own and the rest still go. Live URLs come back per post in `posts[].url`. Args: campaign_id: The campaign to publish. Returned by create_campaign. post_ids: Explicit posts instead of a whole campaign. workspace_id: Workspace ID or name. Optional if user has only one workspace.

publish_campaign

Publish a draft post immediately to its target account. Call this after create_post to publish right away instead of scheduling for later. Waits for the publish to complete on the target platform (up to about half a minute) and returns the live post URL in `url`. Publishing several posts? Call publish_campaign instead. Each publish_post waits out its own polling window, so running them back to back multiplies that wait; publish_campaign dispatches them together and waits once. Args: post_id: The post ID returned by create_post. workspace_id: Workspace ID or name. Optional if user has only one workspace.

publish_post

IFRAME-INTERNAL. DO NOT CALL FROM CHAT. Used by the MCP-App iframes to report their own failures. The iframes run under the host's `connect-src 'self'` CSP from an opaque origin, so they cannot reach PostHog, an error endpoint, or anything else directly — the postMessage bridge is their only egress, which is why this is a tool. The LLM must NEVER call this tool. It reports nothing when `from_ui_bridge` is unset, so a stray call cannot fabricate an issue. Args: message: The error message as the browser reported it. scope: Dotted call-site identifier, e.g. `post_card.attach_media`. This is the grouping key and the actionable field — the bundles are minified with no usable source maps. app: Which iframe reported, e.g. `post-card`. stack: Browser stack trace, if any. Carried as a property only. from_ui_bridge: Set ONLY by the iframe bridge. Never by the LLM.

report_ui_error

Mint a short-lived signed PUT URL for a direct upload to GCS. PREREQUISITE: do NOT call this until you have a tool response showing `hostSupportsUi: false` (typically from a prior `get_post(post_id)` or `get_post_context` call). This flow needs a shell to `curl` with, and no host that renders a panel gives the model one. On `hostSupportsUi: true` hosts, check `hostSupportsUiActions` to see what to do instead: - `true` (the Claude apps, web and desktop): use the post-card's Add media button — `get_post(post_id)` renders the card and its picker uploads + auto-attaches via `update_post` in one step. - `false` (ChatGPT): the card's buttons cannot call back either, so there is no picker AND no shell. Use `upload_media_inline` for a chat-attached file, `upload_media` for a public URL, or send the user to the web app's Media page and finish with `list_media` + `attach_media`. Skipping that check and firing this tool first is a common mistake that wastes a round-trip and confuses the user. LLM-on-CLI path (hostSupportsUi=false, shell available): call this, then run curl -X PUT --upload-file <local_path> \ -H 'Content-Type: <mime_type>' '<signedUrl>' On HTTP 200, call `register_uploaded_media(gcs_path, mime_type, byte_size, attach_to_post_id=…)` to finalize the upload, attach it to a post in the same step, and surface the media in the workspace library. Bytes go LLM→GCS direct, never entering the chat transcript. Supported mime types: - Images: image/png, image/jpeg, image/gif, image/webp, image/avif (≤ 10 MB) - Videos: video/mp4, video/quicktime, video/webm (≤ 100 MB) - Documents: application/pdf (≤ 100 MB) Args: mime_type: One of the supported mime types above. byte_size: Exact file size in bytes. Must match the actual file — `register_uploaded_media` verifies the uploaded blob is this size. workspace_id: Workspace ID or name. Optional if user has only one workspace.

request_upload_url

Retry a post that failed to publish. Args: post_id: The failed post ID to retry. workspace_id: Workspace ID or name. Optional if user has only one workspace.

retry_failed_post

IFRAME-INTERNAL. DO NOT CALL FROM CHAT. Saves the TikTok settings a person chose on the post card. TikTok requires the creator to choose the audience themselves, per post, from the options it returns for their account, so this is the one write path for them and it refuses any call that did not come from the card. Args: post_id: The TikTok post. privacy_level: One of the creator's `privacyLevelOptions`. allow_comments: Whether viewers may comment. branded_content: The video promotes a third party. brand_organic: The video promotes the creator's own business. ai_generated: The video is AI-generated content. workspace_id: Workspace ID or name. from_ui_bridge: Set ONLY by the iframe bridge. Never by the LLM.

set_tiktok_post_options

Schedule every post in a campaign for the same time, in one call. Renders nothing, like schedule_post. A post that cannot be scheduled — over the character limit, missing required media, disconnected account — is reported on its own and the rest still go. Args: scheduled_for: ISO 8601 datetime, at most 30 days ahead. Applied to every post in the set. campaign_id: The campaign to schedule. Returned by create_campaign. post_ids: Explicit posts instead of a whole campaign. workspace_id: Workspace ID or name. Optional if user has only one workspace.

schedule_campaign

Schedule a draft post for automatic publishing at a specific time. Call this after create_post to actually schedule the post. The post must exist and be bound to a social account. Args: post_id: The post ID returned by create_post. scheduled_for: ISO 8601 datetime (e.g. "2026-04-01T10:00:00Z"). Must be in the future and at most 30 days ahead. workspace_id: Workspace ID or name. Optional if user has only one workspace.

schedule_post

Pin (or clear) the user's default workspace for subsequent tool calls. Pass a workspace ID or name to PIN: every workspace-scoped tool called without an explicit `workspace_id` thereafter resolves to this workspace — instead of erroring out with "multiple workspaces". Use this the moment the user names which workspace they want to work in for the conversation; you won't need to thread `workspace_id` through every follow-up call. Pass `null` (or an empty string) to CLEAR the default. The next ambiguous tool call will again return "multiple workspaces" until a new default is set. Use this when the user says "stop defaulting to X" or wants to be prompted each time. The default persists across conversations and clients (it lives on the user's account). Calling this with a different ID overwrites the previous one — no clearing required first. An explicit `workspace_id` on any individual tool call always overrides the default for that one call without changing what's persisted. Args: workspace_id: Workspace ID or name to make the default. Pass null or an empty string to clear the persisted default.

set_default_workspace

Update an existing post. Posts are single-account. To switch the target account, pass `account_id` and we re-bind the post (the platform is re-derived from the new account). There is no per-platform text variant — if the user wants the same idea on a different account with different copy, call `create_post` for a new draft (optionally sharing `campaign_id` to link them). The post's card is already on screen from create_post / get_post, so this call renders a one-line "updated" note instead of a second card, and the card above refreshes to the new version where the client allows it. Batch your changes into one call rather than several small ones. Args: post_id: The post ID to update. text: New post text. account_id: Optional — switch the post's target social account (also re-derives `platform`). Must be a social_account doc ID in this workspace, from list_social_accounts. hashtags: Updated hashtags without # prefix. A list; a comma- or space-separated string is also accepted. goal: Updated goal. status: "draft" or "scheduled". scheduled_for: ISO 8601 datetime for scheduling. campaign_id: Optional grouping ID; reuse across related drafts. pinterest_board_id: Pinterest posts only. Set the board the pin publishes to, an id from `boards` in get_post_context. platform_options: Per-platform settings to change, merged into the post's existing ones (see create_post for the keys). Pass a setting as null to clear it back to the platform default. TikTok settings are not accepted — the user sets them on the card. workspace_id: Workspace ID or name. Optional if user has only one workspace.

update_post

Update the workspace's identity (name, website, logo) or its settings. Only the fields passed change; everything else is left as it is. Args: name: The workspace / brand name (50 characters max). website: Brand website URL. logo_url: URL to the brand logo image. timezone: IANA timezone for scheduling, e.g. "Europe/Madrid". preferred_times: Preferred posting times as HH:MM, e.g. ["09:00", "18:00"]. tag_outbound_links: Append UTM parameters to links on the workspace's own website when a post publishes, so clicks stop reading as "direct" traffic. Needs `website` set; no other site's links are touched. workspace_id: Workspace ID or name. Optional if user has only one workspace.

update_workspace

Upload file bytes directly. Prefer any other path that works. Primarily used by the post-card "Add media" picker, which sends bytes over the MCP RPC channel (postMessage → tools/call) without touching the LLM's transcript. Do NOT call this from chat when the host has a cheaper path, because a large base64 tool argument balloons the conversation context and is orders of magnitude slower: - `hostSupportsUiActions: true` → the post-card picker already does this for you; just tell the user to click Add media. - `hostSupportsUi: false` → you have a shell; use `request_upload_url` + `curl PUT` + `register_uploaded_media`, which streams bytes LLM→GCS direct. - ChatGPT (`hostSupportsUi: true`, `hostSupportsUiActions: false`) → for anything the user attached to the conversation, call `attach_chatgpt_file(file=..., attach_to_post_id=<id>)`. ChatGPT fills `file` in and Antwork downloads the bytes server-side, so they never enter the transcript and a 100 MB video costs the same context as a 10 KB one. That leaves one case for this tool from chat: bytes you already hold and cannot get any other way — a small image, on a host with no picker callback and no shell. Base64 in a tool argument is opaque to the host, so ChatGPT shows the user a "suspicious content: opaque payload" consent prompt before every call. That warning is correct: it cannot see what is in the string. Reaching for `attach_chatgpt_file` first is what keeps the user from having to answer it. For anything large, send the user to the web app's Media page and finish with `list_media` + `attach_media`. Args: image_base64: Base64-encoded file payload (no `data:` prefix). mime_type: MIME type (e.g. "image/png", "video/mp4"). workspace_id: Workspace ID or name. Optional if user has only one workspace. thumbnail_base64: Optional first-frame preview for video uploads (raw base64). Ignored for non-video uploads. from_ui_bridge: Set ONLY by the post-card iframe's Add media picker over the postMessage RPC bridge — never by the LLM. Marks the call as iframe-originated so it's accepted regardless of host name.

upload_media_inline

Add a file to the workspace media library from a public HTTPS URL. Antwork downloads the URL server-side and stores it. Use this for AI-generated content or anything else already reachable over HTTP. For LOCAL files (the user attached a screenshot, photo, video, etc.): NEVER read the file and pass it through here as base64 — that bloats the chat transcript and is extremely slow. Use the signed-URL flow instead: 1. `request_upload_url(mime_type, byte_size)` → returns `signedUrl` and `gcsPath`. 2. `curl -X PUT --upload-file <local_path> -H 'Content-Type: <mime_type>' '<signedUrl>'` 3. `register_uploaded_media(gcs_path, mime_type, byte_size)` — optionally with `attach_to_post_id` to attach to a draft in one step. Bytes go LLM→GCS direct via the signed URL — they never ride the transcript. Supported types: - Images: image/png, image/jpeg, image/gif, image/webp, image/avif - Videos: video/mp4, video/quicktime, video/webm - Documents: application/pdf (LinkedIn document posts only) Args: image_url: Public HTTPS URL of the file. Despite the name, accepts images, videos, and PDFs. mime_type: MIME type (e.g. "image/png", "application/pdf", "video/mp4"). workspace_id: Workspace ID or name. Optional if user has only one workspace.

upload_media

Get scheduled and published posts as an interactive calendar view. Returns posts grouped by date, useful for seeing what's coming up and finding gaps in the content schedule. On supported clients this renders an interactive calendar UI. Args: date_from: Start date (ISO 8601, e.g., "2026-03-24"). Defaults to today. date_to: End date (ISO 8601, e.g., "2026-03-31"). Defaults to 7 days from start. workspace_id: Workspace ID or name. Optional if user has only one workspace.

get_calendar

Get the current authenticated user's profile. Returns user ID, email, display name, subscription status, and the persisted default workspace (if set).

whoami