Write tools
31 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 — in particular that a non-empty userErrors array is a successful result reporting that the write did not happen.
The surface
- addItemToCollections
- Add an item to one or more Collections in the current workspace. A Collection is a workspace-scoped tag set (a saved multi-select tag) applied to items; adding an item to a Collection tags it, so the item then appears when that Collection is used as a filter.
- removeItemFromCollections
- 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
- 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
- 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.
- createCollection
- Create a Collection (a saved tag set) in the current workspace. A Collection is a workspace-scoped multi-select tag applied to items; once created you tag items into it with addItemToCollections and filter items by it.
- updateCollection
- 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
- Delete a Collection (a saved tag set) from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createContentView
- Create a saved content (media deck) view in the current workspace. A content view stores a filter set once; read its items later with searchItems(presetId:) instead of re-sending filters each call.
- updateContentView
- Partial-update a saved content (media deck) view in the current workspace. Only the fields you supply are changed; omitted fields are left untouched. CLONE FIRST when changing `filters`: fetch the view (getContentView(id:)) or a similar one, copy its `filters`, adapt it, and send the WHOLE desired blob — see WHOLESALE REPLACE below.
- deleteContentView destructive
- Delete a saved content (media deck) view from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createSocialProfileView
- Create a saved Social Profile view in the current workspace. A Social Profile view stores a filter set once; read its profiles later with getSocialProfiles(presetId:) instead of re-sending filters each call.
- updateSocialProfileView
- Partial-update a saved Social Profile view in the current workspace. 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
- Delete a saved Social Profile view from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createCreatorView
- Create a saved Creator View in the current workspace. A Creator View saves a reusable narrowing (customAttributeConditions + sort) once; read its creators later with creators(presetId:). NOTE: the `filters` blob is stored and echoed back but NOT applied on read — creators(presetId:) narrows ONLY by customAttributeConditions + sort (see VIEW FILTERS below). Use customAttributeConditions to actually narrow results.
- updateCreatorView
- Partial-update a saved Creator View in the current workspace. 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
- Delete a saved Creator View from the current workspace. This is a HARD, IRREVERSIBLE delete.
- createViewGroup
- Create a user-created view group in the current workspace. A view group is a workspace-scoped sidebar bucket that Content Views, Social Profile Views, and workspace Creator Views can be moved into (with moveContentViewToGroup / moveSocialProfileViewToGroup / moveCreatorViewToGroup). CAMPAIGN Creator Views are NEVER group members — they are campaign-scoped, not workspace-scoped.
- updateViewGroup
- 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 and their order are untouched. To change membership use moveContentViewToGroup / moveSocialProfileViewToGroup / moveCreatorViewToGroup; to reorder use reorderViewsInGroup.
- deleteViewGroup destructive
- Delete a view group from the current workspace. This is a HARD, IRREVERSIBLE delete.
- moveContentViewToGroup
- Move a Content View (a saved media-deck view) 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
- 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
- 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
- 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
- Reorder the member views (Content Views + Social Profile Views + Creator Views) inside a view group. The first id in `viewIds` becomes position 1, the second position 2, and so on.
- createWebhookSubscription
- Create an outbound-webhook subscription in the current workspace. New items landing in the subscribed content view(s) trigger a signed HTTPS POST to your endpoint.
- updateWebhookSubscription
- Partial-update a webhook subscription 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
- Delete a webhook subscription from the current workspace. This is a HARD, IRREVERSIBLE delete.
- rotateWebhookSubscriptionSecret
- Rotate a webhook subscription's signing secret in the current workspace. Deliveries enter a 24h dual-sign overlap during which they are signed with BOTH the new and previous secret, so the receiver can cut over losslessly.
- sendWebhookTestEvent 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 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 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 failed deliveries one-shot per row (one more attempt each, lifetime attemptCount preserved, no backoff-ladder reset) — a bounded catch-up, never a retry storm.