Write tools
50 tools that change something. Each wraps exactly one public GraphQL mutation and executes it verbatim — the same input validation, the same { entity, userErrors } payload, and the same side effects a /api/v2 partner gets.
Who can call them
Read access alone never grants writes, and there is no feature flag on the write surface. Two things compose: a write-capable credential, and a workspace the credential can resolve to write into.
| Credential | Write capability |
|---|---|
| Bearer | Any valid API token is write-capable — parity with /api/v2, where any valid bearer may call every public mutation. |
| OAuth | Only if the token carries the optional write scope, granted by the person at consent time. |
A credential without write capability does not see these tools at all: tools/list omits them rather than advertising calls that would fail.
Before writing anything, read Agent conventions. A non-empty userErrors array is a successful result that can accompany partial success. Inspect the payload and verify current state before retrying failed parts.
The surface
- addItemToCollections
- Save an archived post into one or more Collections for curation, review, or reuse.
- removeItemFromCollections destructive
- Remove an item from one or more Collections in the current workspace. A Collection is a workspace-scoped tag set applied to items; removing an item from a Collection strips that tag from the item. This NEVER deletes the item and NEVER deletes the Collection — it only detaches the tag. Removing an item that is not in the Collection is a no-op.
- uploadItemFromUrl external call
- Enqueue a single public social-media post URL (Instagram, TikTok, or YouTube) for import into the current workspace. Once ingested, the post becomes a normal Archive item.
- refetchEngagementBulk destructive irreversible
- Queue an engagement-metrics refresh (likes, comments, shares, views) for up to 1000 items in the current workspace. SPENDS CREDITS: 5 credits per PROCESSABLE item. The upper bound is itemIds.length x 5, but Instagram stories and items already refreshed in the last 24h are SKIPPED and NOT charged, so the ACTUAL spend is processedCount x 5. Credits are reserved when the batch is queued and settled when the operation finishes: credits for items that fail to refresh are released, and the spend on every item that refreshes successfully is IRREVERSIBLE.
- importCreators
- Import creators into the current workspace by their social handles — up to 250 creators per call, each identified by 1-5 handles on INSTAGRAM, TIKTOK or YOUTUBE, with optional labels and custom attribute values applied to each creator. The import runs in the background: this call only accepts the batch and returns the operationId to follow it with.
- createCampaign
- Set up a creator-monitoring, content-capture, brand-monitoring, or vetting campaign in the current workspace.
- updateCampaign destructive
- Edit an existing campaign's name, end date, creator-monitoring tag rules, creator roster, or captured posts.
- deleteCampaign destructive irreversible
- Delete a campaign from the current workspace, exactly as deleting it in the app does. This is a HARD, IRREVERSIBLE delete. Only campaigns with a non-null campaignType can be deleted.
- createCollection
- Create a named Collection for a curated shortlist of workspace posts.
- updateCollection destructive
- Rename a Collection (a saved tag set) in the current workspace. Rename is the ONLY thing this changes — a Collection's tagged items are untouched.
- deleteCollection destructive irreversible
- Delete a Collection (a saved tag set) from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createContentView
- Save a reusable content search as a Content View for recurring reporting, monitoring, or review. A Content View stores filters; read its matching items later with searchItems(presetId:). COMPOSE WITH `filter` / `sorting` (typed, as in searchItems). To copy a view, send its getContentView `filters`, `sort`, and `customAttributeConditions` verbatim.
- updateContentView destructive
- Refine a saved Content View's filters, sorting, name, or display settings in the current workspace. Only the fields you supply are changed; omitted fields are left untouched. COMPOSE WITH `filter` / `sorting` (typed, as in searchItems); send a get* `filters` verbatim only to copy another view — see WHOLESALE REPLACE below.
- deleteContentView destructive irreversible
- Delete a saved Content View from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createSocialProfileView
- Save a reusable social-account segment as a Social Profile View in the current workspace. Read its profiles later with getSocialProfiles(presetId:). Stored customAttributeConditions and sort drive the results; the filters blob controls the app's display and is not applied on read.
- updateSocialProfileView destructive
- Refine a saved Social Profile View's conditions, sorting, name, or display settings. Only the fields you supply are changed; omitted fields are left untouched. CLONE FIRST when changing `filters`: fetch the view (getSocialProfileView(id:)) or a similar one, copy its `filters`, adapt it, and send the WHOLE desired blob — see WHOLESALE REPLACE below.
- deleteSocialProfileView destructive irreversible
- Delete a saved Social Profile view from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createCreatorView
- Save a reusable creator segment as a Creator View in the current workspace. A Creator View saves a reusable narrowing (customAttributeConditions + sort) once; read its creators later with searchCreators(presetId:). NOTE: the `filters` blob is stored and echoed back but NOT applied on read — searchCreators(presetId:) narrows ONLY by customAttributeConditions + sort (see VIEW FILTERS below). Use customAttributeConditions to narrow results.
- updateCreatorView destructive
- Refine a saved creator segment's conditions, sorting, name, or display settings. Only the fields you supply are changed; omitted fields are left untouched. CLONE FIRST when changing `filters`: fetch the view (getCreatorView(id:)) or a similar one, copy its `filters`, adapt it, and send the WHOLE desired blob — see WHOLESALE REPLACE below.
- deleteCreatorView destructive irreversible
- Delete a saved Creator View from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createViewGroup
- Create a folder to organize saved views and Collections in the workspace sidebar. A view group is a workspace-scoped sidebar bucket that Content Views, Social Profile Views, workspace Creator Views, and Collections can be moved into (with moveContentViewToGroup / moveSocialProfileViewToGroup / moveCreatorViewToGroup / moveCollectionToGroup). CAMPAIGN Creator Views are NEVER group members — they are campaign-scoped, not workspace-scoped.
- updateViewGroup destructive
- Rename a view group in the current workspace. Rename is the ONLY thing this changes — the group's member Content Views / Social Profile Views / Creator Views / Collections and their order are untouched. To change membership use moveContentViewToGroup / moveSocialProfileViewToGroup / moveCreatorViewToGroup / moveCollectionToGroup; to reorder use reorderViewsInGroup.
- deleteViewGroup destructive irreversible
- Delete a view group from the current workspace. This is a HARD, IRREVERSIBLE delete.
- moveContentViewToGroup destructive
- Move a Content View (a saved item filter) into a view group, or remove it from whatever group it is in. Use this tool for CONTENT VIEWS ONLY — views whose ids come from getContentViews / getContentView. To move a Social Profile View (ids from getSocialProfileViews) use moveSocialProfileViewToGroup instead.
- moveSocialProfileViewToGroup destructive
- Move a Social Profile View (a saved social-profiles view) into a view group, or remove it from whatever group it is in. Use this tool for SOCIAL PROFILE VIEWS ONLY — views whose ids come from getSocialProfileViews / getSocialProfileView. To move a Content View (ids from getContentViews) use moveContentViewToGroup instead.
- moveCreatorViewToGroup destructive
- Move a Creator View (a saved crm_creators view) into a view group, or remove it from whatever group it is in. Use this tool for CREATOR VIEWS ONLY — views whose ids come from getCreatorViews / getCreatorView. To move a Content View (ids from getContentViews) use moveContentViewToGroup instead; to move a Social Profile View use moveSocialProfileViewToGroup.
- moveCollectionToGroup destructive
- Move a Collection (a saved tag set) into a view group, or remove it from whatever group it is in. Use this tool for COLLECTIONS ONLY — entities whose ids come from getCollections / getCollection. To move a Content View (ids from getContentViews) use moveContentViewToGroup; to move a Creator View use moveCreatorViewToGroup; to move a Social Profile View use moveSocialProfileViewToGroup.
- reorderViewsInGroup destructive
- Reorder the members (Content Views + Social Profile Views + Creator Views + Collections) inside a view group. The first id in `viewIds` becomes position 1, the second position 2, and so on.
- createWebhookSubscription
- Send signed webhook notifications to an HTTPS endpoint when content enters subscribed Content Views or operations complete.
- updateWebhookSubscription destructive
- Change a webhook endpoint, subscribed events or views, metadata, or manual pause state in the current workspace. Only the fields you supply are changed; omitted fields are left untouched. Pause or resume the subscription via `status`.
- deleteWebhookSubscription destructive irreversible
- Delete a webhook subscription from the current workspace. This is a HARD, IRREVERSIBLE delete.
- rotateWebhookSubscriptionSecret destructive irreversible
- Rotate a webhook subscription's signing secret in the current workspace. Deliveries are signed with the new secret AND with every secret retired in the last 24h, each until its own 24h expiry, so the receiver can cut over losslessly even after back-to-back rotations. A superseded secret is destroyed once its 24h overlap ends and can never be recovered — rotation is IRREVERSIBLE.
- sendWebhookTestEvent destructive external call
- Send a signed synthetic ping to a webhook subscription's endpoint and return the SETTLED delivery, so you can confirm the endpoint is reachable and verifies signatures. The ping payload is built SERVER-SIDE — it is never caller-supplied.
- redeliverWebhookDelivery destructive external call
- Manually replay a terminal FAILED webhook delivery in the current workspace — a dead-letter retry. Grants exactly ONE more attempt (CAS-guarded so concurrent replays can't double-enqueue); keeps the lifetime attemptCount / backoff index, and the settlement recorder re-terminates a re-failure. A replay past the retry ceiling is a one-shot, never an automatic retry storm.
- enableWebhookSubscription destructive external call
- Re-enable a webhook subscription in the current workspace that was AUTO-DISABLED by repeated delivery failures (status DISABLED_BY_FAILURES). Clears the failure counters and, by default, replays the last 24h of terminal FAILED deliveries (nextAttemptAt null) one-shot per row (one more attempt each, lifetime attemptCount preserved, no backoff-ladder reset) — a bounded catch-up, never a retry storm. A FAILED delivery still awaiting its scheduled retry (nextAttemptAt set) is left to the automatic retry, and `subscription.ping` deliveries are never replayed. A replayed delivery keeps its lastError / lastResponseStatus until the replay settles.
- addLabelsToCreators
- Tag selected creators to organize shortlists, segments, or workflow categories in the current workspace. Labels are set membership keyed by name: assigning a label a creator already carries is a success no-op, so repeating the call is safe.
- removeLabelsFromCreators
- Untag selected creators without deleting their labels from the workspace. Labels are set membership keyed by NAME: removing a label a creator does not carry is a success no-op, so repeating the call is safe. NOT A LABEL DELETE: the label itself survives in getLabels.
- createLabels
- Create reusable creator tags in the workspace's label taxonomy. Names already present (ignoring case and surrounding whitespace) are returned unchanged — creating an existing label is a no-op, not an error. Repeating the call is safe. Creating a label does not assign it to anyone; use addLabelsToCreators for that. Labels have no id; the name is the identity.
- deleteLabel destructive irreversible
- Permanently deletes the label from the whole workspace and removes it from every creator that carries it; the creators themselves are kept. This is irreversible and completes in the background — confirm with the user, echoing the label name, before calling. IRREVERSIBLE, workspace-wide.
- renameLabel
- Renames one label across the whole workspace; every creator carrying it follows the new spelling. Nothing is deleted. The rename completes in the background.
- mergeLabels destructive irreversible
- Folds one label into another across the whole workspace: every creator carrying labelName ends up carrying intoLabelName, and labelName is deleted. This is irreversible: the two labels' memberships cannot be separated afterwards. The merge completes in the background.
- createCustomAttributeSchema
- Add a new CRM custom field for creators, such as a status, tier, or contact detail to track.
- addCustomAttributeOptions
- Add choices to an existing creator select field (SINGLE_SELECT_V3 or MULTIPLE_SELECT_V2) in the CRM.
- bulkAddLabelsToCreators
- Tag a large creator selection with labels through a background operation in the current workspace. Labels are set membership keyed by name: a creator already carrying a label is left as is, so repeating the call is safe.
- bulkRemoveLabelsFromCreators
- Remove tags from a large creator selection through a background operation, keeping the labels themselves. Labels are set membership keyed by NAME: removing a label a creator does not carry is a no-op, so repeating the call is safe. NOT A LABEL DELETE: the label itself survives in getLabels.
- setCreatorCustomAttributes destructive
- Update one CRM custom field on selected creators, replacing its stored value. Repeating the call is safe.
- clearCreatorCustomAttribute destructive
- Clear one CRM custom field on selected creators, leaving the creators and field schema in place. Repeating the call is safe.
- requestUsageRights
- Queue requests to reuse creators' posts in brand content or run them as paid ads, as the Manage Rights page does. Each item joins the workspace's UGC Repurpose campaign as a manual request with status IN_QUEUE.
- createDeepResearchReport destructive irreversible
- Start a Deep Research report in the current workspace. It SPENDS CREDITS, which are never refunded — IRREVERSIBLE. Returns as soon as the report exists; it then runs for minutes.
- submitFeedback
- Report a problem with Archive's API or tools to the Archive team.