Archive API docs
esc
    Jump to
    Getting started Token, first query, response Explorer Run queries in the browser items The connection most integrations start with Changelog Additions and deprecations

    Narrow by kind with a prefix — q: queries, m: mutations, t: types, g: guides, f: fields and arguments.

    Agent conventions

    These rules apply to every tool. Each tool’s advertised description also states the rules relevant to it, so an agent sees them at call time, but this page collects them in one place.

    userErrors means the write did not happen

    A non-empty userErrors array is a successful tool result (isError absent or false) reporting a domain rejection, not a crash. Read each entry’s field (an array of path segments, for example ["input","name"]) and message, correct the input, then retry or ask the person.

    A rejected write — still a success result 
    {
"collection": null,
"userErrors": [
  { "field": ["input", "name"], "message": "has already been taken" }
]
}

    isError: true is reserved for authentication challenges, workspace-authorization misses, argument-schema validation failures, rate-limit throttles, unknown tools, and redacted unexpected server errors ("Tool execution failed").

    Retry discipline

    On a timeout or transport error where you can’t tell whether the write landed, read first with the tool that verifies it, before retrying. Every write tool’s description names that read tool; a delete is confirmed when the read returns null.

    Tools annotated idempotentHint: true can be retried directly: a duplicate apply converges on the same state.

    Destructive tools

    The delete* tools set annotations.destructiveHint: true. Their descriptions state what is destroyed, what survives, and that the delete is irreversible. Confirm with the person, echoing the entity ID back to them, before calling one.

    Deleting a saved view or Collection never deletes content: the items survive and lose only that one tag or grouping. No other tool spends money or destroys creator data.

    Async ingest

    uploadItemFromUrl and refetchEngagementBulk are asynchronous. A success payload means the work was enqueued, not that it finished. Poll the verify tool named in the description for the eventual result, and don’t expect fresh data in the write response.

    Concise responses

    Every list read tool accepts responseFormat, either "detailed" (the default) or "concise". Concise trims each item node to the fields an agent needs for listing, filtering, and ranking: ID, originalUrl, provider, type, takenAt, caption, a minimal socialProfile, and currentEngagement. On searchItems it also keeps creator { id }, the join key for creator-level diffs such as differencing a campaign roster against that campaign’s posters; matching on accountName is unsafe there because a workspace can hold two creator records sharing a handle.

    Prefer concise while you are narrowing a result set, and switch to detailed only when you need the fuller shape. Concise is materially cheaper in context, and the trimmed fields are a strict subset: nothing changes shape between the two modes.

    Enum values

    Every enum value is UPPERCASE. Item types encode the platform and the format together, which is a common cause of empty result sets — and the value an item reads back as is not always a value you can filter by. Core concepts explains why the two enums differ.

    View filters: clone, don’t compose

    For content view, Social Profile view, and Creator View create and update, filters is an opaque JSON blob that is not validated on write. Prefer cloning an existing view’s filters (fetch it with the matching get* tool) over composing one from scratch.

    Auditing

    Every write emits exactly one structured audit event, whatever the outcome, carrying the principal identity, the auth strategy, the MCP client name, the result, and any userErrors.