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 can accompany partial success

    A non-empty userErrors array is a successful tool result (isError absent or false) reporting domain errors, not a crash. Some writes reject the whole request; others apply valid parts and report errors for the rest. Read the payload and each entry’s field (an array of path segments, for example ["input","name"]) and message. Verify current state, then correct only the failed parts. Replaying the entire request can repeat successful work.

    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"). The validation and server-error texts end with “If this looks like an Archive bug, report it with submitFeedback.”; submitFeedback’s own errors do not.

    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 within their documented guarantee. For createCampaign, retry the same schema-valid input and externalId, with matching campaignType and settings. Replay returns the original campaign without applying changed input or repairing side effects interrupted after persistence. Other create tools may create duplicates.

    updateCampaign is not idempotent: creator additions enqueue imports. A lagging creatorsCount does not prove a previous request failed. Check the roster and queued operation evidence before retrying, and do not repeat additions while their imports may still be running.

    Destructive tools

    annotations.destructiveHint: true means a call is not purely additive: it overwrites stored values, changes membership or ordering, or triggers a real delivery attempt against your endpoint. That covers every delete*, update*, move* and reorder* tool, removeItemFromCollections, refetchEngagementBulk, rotateWebhookSubscriptionSecret, and the three webhook-delivering tools. It is wider than “deletes”. Say what will change before calling one; a confirmation round-trip is not expected for a change you can re-apply with different values.

    Irreversible tools

    A smaller set is tagged irreversible: the call destroys durable state or consumes a metered resource inside Archive with no path back. That is every delete* tool, plus rotateWebhookSubscriptionSecret (the superseded signing secret is gone for good) and refetchEngagementBulk (credits spent on an item that refreshes are not refunded; a failed item’s credits are released when the operation settles). Their descriptions state what is destroyed, what survives, and that the effect is irreversible. Confirm with the person, echoing the entity ID back to them, before calling one of these.

    Deleting a saved view or Collection never deletes content: the items survive and lose only that one tag or grouping. refetchEngagementBulk is the only tool that spends money, and no tool 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.