Change sets
Write tools (mutate state). Draft, fill and submit a change set for human review. Nothing is applied to any ad platform by these tools.
Write tool — mutates state
New tokens are read-only by default: the console defaults a new endpoint to the read-only tools, so a fresh token cannot call these until someone deliberately grants a write tool. See Tool scoping and Write tools are human-in-the-loop.
| Tool | Purpose |
|---|---|
changes_draft | Draft a change set |
changes_add_item | Add an item to a change set |
changes_submit | Submit a change set for review |
changes_draft
Draft a change set
Open a DRAFT change set for this organization — the container a human later reviews and approves. Nothing is applied to any ad platform by this call, or by anything else you can do: after changes_add_item and changes_submit the set sits in PENDING review until a person approves it in the Bellaso app. The draft is owned by this API endpoint, so only this endpoint can add items to it or submit it.
Posture: mutates state · Module gate: none (needs only the agent entitlement) · REST: POST /api/v1/tools/changes_draft
| Argument | Type | Required | Notes |
|---|---|---|---|
management_connection_id | string | yes | Which ad-platform connection these changes will be applied through. Get valid ids from list_management_connections. (pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$) |
title | string | yes | Short human-readable title for the change set — the reviewer sees this first. Say what changes and why, e.g. "Cut spend on non-converting search campaigns". (length 1–200) |
requires_finance | boolean | no | Route the set through finance approval before admin approval. Use it for budget increases. |
changes_add_item
Add an item to a change set
Append one proposed operation (a budget change, a status change, …) to a DRAFT change set you drafted. Items can only be added while the set is a DRAFT — once submitted, its contents are frozen so a reviewer approves exactly what they read. Re-adding an identical operation is refused as a duplicate rather than queued twice.
Posture: mutates state · Module gate: none (needs only the agent entitlement) · REST: POST /api/v1/tools/changes_add_item
| Argument | Type | Required | Notes |
|---|---|---|---|
change_set_id | string | yes | The DRAFT change set to append to (from changes_draft). (pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$) |
operation_type | string | yes | The operation this item performs, e.g. "google.campaign_budget_micros" or "meta.adset_daily_budget". (length 1–120) |
payload | object | yes | The operation's arguments, matching the operation type — e.g. { customerId, campaignId, budgetMicros } for google.campaign_budget_micros. |
schema_version | integer | no | Payload schema version (defaults to 1). Leave unset unless you know the operation has a newer shape. (1–100) |
changes_submit
Submit a change set for review
Hand a DRAFT change set you drafted to its human reviewers: it moves to PENDING_ADMIN, or PENDING_FINANCE when the set was flagged as requiring finance. This does NOT apply anything — approval is a person's decision in the Bellaso app, and this surface cannot approve. A set that is not a DRAFT is refused.
Posture: mutates state · Module gate: none (needs only the agent entitlement) · REST: POST /api/v1/tools/changes_submit
| Argument | Type | Required | Notes |
|---|---|---|---|
change_set_id | string | yes | The DRAFT change set to submit for human review. (pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$) |