# 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.

:::warning{title="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](/tool-scoping) and [Write tools are human-in-the-loop](/tools/overview#write-tools-are-human-in-the-loop).

:::

| Tool | Purpose |
|---|---|
| [`changes_draft`](#changes_draft) | Draft a change set |
| [`changes_add_item`](#changes_add_item) | Add an item to a change set |
| [`changes_submit`](#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}$`) |