Change sets
Plans of changes from the Agent and loops: propose, review, approve, send back and undo.
List change sets
Plans of changes to live budgets, delivery and bids, most recently changed first. Anyone who can read the workspace sees them (guests can't). Items, versions and the summary are in GET /change-sets/{id}.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Optional | open (pending, revising, approving), decided, or statuses separated by commas. |
loopId | string | Optional | Plans from this loop. |
runId | string | Optional | The plan of this loop run. |
chatId | string | Optional | Plans from this Agent chat. |
mine | string | Optional | true: only plans proposed for the acting person. |
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-200, default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].actsForitems[].actsFor.id- Person.
items[].actsFor.name- Name.
items[].canApprove- The caller may approve it now.
items[].canDecide- The caller may edit, send back, approve or reject it.
items[].canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). items[].canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). items[].cannotApproveReason- Why not, in words.
items[].cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.items[].cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. items[].capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. items[].createdAt- Proposed.
items[].decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. items[].expiresAt- 24 hours after it was proposed.
items[].id- Change set.
items[].itemCount- Changes in the current version.
items[].items- Detail: the changes.
items[].items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].items[].after- The value applying sets.
items[].items[].basedOnitems[].items[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].items[].basedOn.value- The value it was planned against.
items[].items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].items[].callitems[].items[].call.input- Its exact arguments.
items[].items[].call.tool- The catalog tool.
items[].items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].items[].editable- Its value can be edited now.
items[].items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].items[].objectitems[].items[].object.adAccountId- act_…
items[].items[].object.adAccountName- The ad account's name.
items[].items[].object.campaignId- Its campaign.
items[].items[].object.campaignName- Its campaign's name.
items[].items[].object.id- Meta ID.
items[].items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].items[].object.name- Name as synced.
items[].items[].percent- Signed change of a budget in percent (
20,-15.5). items[].items[].permission- The permission applying it needs.
items[].items[].reason- The agent's reason.
items[].items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].items[].summaryotherchanges: its effect in a sentence.items[].items[].titleotherchanges: what it does, as the approval card says it.items[].leftOut- Detail: proposals the limits left out.
items[].leftOut[].key- Key.
items[].leftOut[].reason- Why it's not in the plan.
items[].leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. items[].leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. items[].leftOut[].title- What it was.
items[].origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.items[].proposedByitems[].proposedBy.id- Person, API key or agent.
items[].proposedBy.kind- Actor kind.One of
person,api_key,agent,system items[].proposedBy.name- Name.
items[].revising- While revising:
{ since, feedback, by }. items[].revisionError- Why the last revision made no new version.
items[].revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. items[].revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. items[].shownVersion- Detail: the version
summaryanditemsare from. items[].status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed items[].summary- Detail: Markdown.
items[].supersededBy- The newer version that replaced it.
items[].supersedes- The plan it replaced.
items[].test- From a test run: review only.
items[].title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
items[].titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. items[].totals- Per ad account and currency.
items[].totals[].adAccountId- act_…
items[].totals[].adAccountName- Name.
items[].totals[].bids- Bid changes.
items[].totals[].currency- ISO 4217.
items[].totals[].decreases- Budgets lowered.
items[].totals[].increases- Budgets raised.
items[].totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. items[].totals[].others- Other changes (duplicates, comment actions).
items[].totals[].pauses- Paused.
items[].totals[].resumes- Turned on.
items[].updatedAt- Last change.
items[].version- The current version.
items[].versions- Detail: every version, oldest first.
items[].versions[].authoritems[].versions[].author.id- Person, API key or agent.
items[].versions[].author.kind- Actor kind.One of
person,api_key,agent,system items[].versions[].author.name- Name.
items[].versions[].createdAt- When.
items[].versions[].diffitems[].versions[].diff.added- Added.
items[].versions[].diff.changed- Changed.
items[].versions[].diff.removed- Removed.
items[].versions[].feedback- The feedback it answers.
items[].versions[].itemCount- Changes in it.
items[].versions[].source- What made it.One of
agent,feedback,edit items[].versions[].version- Number.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/change-sets" \
-H "Authorization: Bearer $PLUTO_KEY"Propose changes
Proposes changes to live Meta objects (set_budget, set_delivery_status, set_bid calls) as one plan for the acting person to review and approve in Pluto Ads; nothing changes before that. A call naming another platform's object is left out (leftOut): change it with its own call. Pluto builds each change from the call and the synced object (current value, new value, currency) and leaves out, with the reason in leftOut, anything that fails the per-change safety checks (a budget never goes to 0, and only in a known currency; how far one change moves it is the approving person's call) or that it can't show exactly; a plan with nothing left is a 422. With changeSetId (a plan you proposed, still open) it makes that plan's next version instead: answers 200, else 201. Needs write and a credential that acts for a person.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
changeSetId- Optional: make the next version of this plan.
expectedVersion- Optional, with changeSetId: the version you revised (a newer one is a 409).
items- 1 to 500 changes.
items[].input- Its arguments, exactly as the tool takes them.
items[].reason- Optional: why, for the person.
items[].tool- The change.One of
set_budget,set_delivery_status,set_bid summary- Markdown for the person: what the plan changes and why.
title- Optional: the title (default "<you> wants to make N changes").
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/change-sets" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 44c5d587-dd23-4479-a9de-5f0ebb887b9f" \
-H "Content-Type: application/json" \
-d '{
"changeSetId": "da17397c-759e-4179-916f-87cbbcd79e42",
"expectedVersion": 3,
"items": [
{
"input": {
"adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
"amount": "150.00"
},
"reason": "Spend is pacing ahead of plan; hold the budget until Friday.",
"tool": "set_budget"
}
],
"summary": "Spend is up 12% on the week; the UGC 9x16 ad leads on purchases.",
"title": "Shift budget to the UGC 9x16 ad"
}'Get a change set
The shown version's summary, items (with each one's result once applied), leftOut, and every version with what it changed. ?version=n shows an older version's summary and items; everything else is the plan as it is now. A plan past its deadline reads as expired.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The change set's ID. |
version | string | Optional | Optional: an older version to show. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/change-sets/da17397c-759e-4179-916f-87cbbcd79e42" \
-H "Authorization: Bearer $PLUTO_KEY"Approve and apply a version
Applies exactly the version you reviewed, change by change, as you. Only a person signed in to the app who is the one it was proposed for, or an organization owner or admin, can approve (API keys and agents get 403), and it needs each change's permission (publish). A newer version is a 409 whose current is the plan now; a plan already decided (or being applied by someone else) is a 409 "Someone already approved or rejected this."; a test plan, a plan with nothing left, a loop that was archived or whose run stopped, or a deleted chat is a 409. Each change is re-read first: a value that moved since the plan was made is conflict, a change a hard limit stops now is blocked, a change Meta refuses is failed; the rest are applied. The plan ends applied, partially_applied or failed. Retrying resumes where it stopped and never applies a change twice.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The change set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
version- The version you reviewed.
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/change-sets/da17397c-759e-4179-916f-87cbbcd79e42/approve" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0d785c07-fce3-46ff-b612-1f0a181e23f3" \
-H "Content-Type: application/json" \
-d '{
"version": 3
}'Edit a plan without AI
A new version with changes removed (remove: keys) or given a new value (set: a budget or bid as a decimal string), rebuilt by the server and checked against the per-change safety checks (a value outside them is a 422 naming set/<n>/after). version is the version you edited; a newer one is a 409. The one it was proposed for, or an organization owner or admin, with write.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The change set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
remove- Changes to take out.
set- New values.
set[].after- The new value, a decimal string.
set[].key- A change's key.
version- The version you edited.
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/change-sets/da17397c-759e-4179-916f-87cbbcd79e42/edit" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e4be257e-fd3c-4fff-a738-7a907ad5fa15" \
-H "Content-Type: application/json" \
-d '{
"remove": [
"Brevanne"
],
"set": [
{
"after": "150.00",
"key": "sk_Lzycg7UKJEdBcsRh8Mp7vUp6cj1QuKW8"
}
],
"version": 3
}'Send a plan back with feedback
The plan becomes revising and the agent that proposed it makes a new version from your feedback: a loop's step runs again on fresh data (AI usage of the person it's for), a chat's Agent answers in the chat, an API client revises with POST /change-sets and changeSetId. While it's revising, feedback, edits and approving are a 409 ("Agent is updating this plan."). A revision that makes no new version within 15 minutes returns the plan to pending with revisionError. The one it was proposed for, or an organization owner or admin, with write.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The change set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
retryConflicts- After applying (
partially_appliedorfailed): plan the changes that conflicted again from the current values, as a new version of just those. The plan is pending again for 24 hours; what was applied stays applied. text- The feedback, up to 4000 characters (optional with
retryConflicts). version- Optional: the version it's about; a newer one is a 409.
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/change-sets/da17397c-759e-4179-916f-87cbbcd79e42/feedback" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 779fd057-cefe-4a35-8d48-0da29bb2e045" \
-H "Content-Type: application/json" \
-d '{
"retryConflicts": true,
"text": "Can we try the 4x5 cut for Instagram feed before we publish?",
"version": 3
}'Undo an applied change
Puts one applied change back to the value it had before, in Meta, through the same per-change safety checks. The item's result.undo says how it went (applied, blocked or failed with the reason). The one it was proposed for, or an organization owner or admin, with publish. key is URL-encoded.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The change set's ID. |
key | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
object
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/change-sets/da17397c-759e-4179-916f-87cbbcd79e42/items/ad-1/undo" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0f73b69f-dcec-49fd-aa0a-d886d2b6f635" \
-H "Content-Type: application/json" \
-d '{}'Reject a plan
Nothing changes. The optional reason goes back to the loop, so its next run knows. Only a person signed in to the app (the one it was proposed for, or an organization owner or admin); API keys and agents get 403. A plan already decided is a 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The change set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
reason- Optional, up to 1000 characters.
Response
actsForactsFor.id- Person.
actsFor.name- Name.
canApprove- The caller may approve it now.
canDecide- The caller may edit, send back, approve or reject it.
canRetryConflicts- The caller may send the changes that conflicted back (
feedbackwithretryConflicts). canUndo- The caller may undo its applied changes (the person it was for, or an organization owner or admin, with
publish). cannotApproveReason- Why not, in words.
cannotApproveReasonCodecannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.cannotApproveReasonParams- The values
cannotApproveReasonCode's sentence names (an object), present exactly when it is. capabilities- What approving or rejecting it needs: each change's capability (
budgets:writefor budgets and bids,delivery:writefor pauses and resumes), each once. Someone without one decides it neither way, the person it was proposed for included. Absent when it has no changes left. createdAt- Proposed.
decision- Once decided:
{ status, by, at, reason, reasonCode?, reasonParams?, version }.reasonCodeandreasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason. expiresAt- 24 hours after it was proposed.
id- Change set.
itemCount- Changes in the current version.
items- Detail: the changes.
items[].action- What it changes;
otherhas no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described bytitleandsummary.One ofbudget,status,bid,other items[].after- The value applying sets.
items[].basedOnitems[].basedOn.syncedAt- When Meta last changed the object, as synced.
items[].basedOn.value- The value it was planned against.
items[].before- The value when the plan was made: a decimal string in
currency, orACTIVE/PAUSED; null when unknown. items[].callitems[].call.input- Its exact arguments.
items[].call.tool- The catalog tool.
items[].currency- ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudget- The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editable- Its value can be edited now.
items[].field- The field (
callforother).One ofdaily_budget,lifetime_budget,status,bid,call items[].key- Stable across versions:
<kind>:<meta id>:<budget|status|bid>. items[].objectitems[].object.adAccountId- act_…
items[].object.adAccountName- The ad account's name.
items[].object.campaignId- Its campaign.
items[].object.campaignName- Its campaign's name.
items[].object.id- Meta ID.
items[].object.kind- Kind (
commentandcallforotherchanges).One ofcampaign,ad_set,ad,comment,call items[].object.name- Name as synced.
items[].percent- Signed change of a budget in percent (
20,-15.5). items[].permission- The permission applying it needs.
items[].reason- The agent's reason.
items[].result- Once applied:
{ status: applied|conflict|blocked|failed|removed, message, messageCode?, messageParams?, at, undo: null | { status: applied|blocked|failed, message, at }, readback: null | { status: live|differs, value, at } }.readbackis what the next sync read back:livewhen Meta shows the applied value,differswith the value Meta shows.messageCodeandmessageParams: a registeredmessage's code, for an app to say in its language. items[].summaryotherchanges: its effect in a sentence.items[].titleotherchanges: what it does, as the approval card says it.leftOut- Detail: proposals the limits left out.
leftOut[].key- Key.
leftOut[].reason- Why it's not in the plan.
leftOut[].reasonCode- A registered
reason's code, for an app to say it in its language. leftOut[].reasonParams- The values
reasonCode's sentence names, present exactly when it is. leftOut[].title- What it was.
origin{ kind: loop, loopId, loopName, runId, stepId },{ kind: chat, chatId, chatTitle, messageId }or{ kind: api, actor }.proposedByproposedBy.id- Person, API key or agent.
proposedBy.kind- Actor kind.One of
person,api_key,agent,system proposedBy.name- Name.
revising- While revising:
{ since, feedback, by }. revisionError- Why the last revision made no new version.
revisionErrorCode- A registered
revisionError's code, for an app to say it in its language. revisionErrorParams- The values
revisionErrorCode's sentence names (an object), present exactly when it is. shownVersion- Detail: the version
summaryanditemsare from. status- Status.One of
pending,revising,approving,applied,partially_applied,rejected,expired,superseded,failed summary- Detail: Markdown.
supersededBy- The newer version that replaced it.
supersedes- The plan it replaced.
test- From a test run: review only.
title- Follows the state: "Daily optimizer wants to make 7 changes" while it waits for a decision; once decided, a single change's own words or "7 changes from Daily optimizer" (a title you gave stays).
titleCode- The title as a code, for an app to say in its language:
{ code, params }withcodechange_set.title.proposed("{who} wants to make {count} changes") orchange_set.title.from("{count} changes from {who}"),params{ proposer: agent | other, who, count }(agent: Pluto's Agent, "the Agent"). Absent when the title is words of its own. totals- Per ad account and currency.
totals[].adAccountId- act_…
totals[].adAccountName- Name.
totals[].bids- Bid changes.
totals[].currency- ISO 4217.
totals[].decreases- Budgets lowered.
totals[].increases- Budgets raised.
totals[].netDaily- Net change of daily spend, signed (
+120.00): daily budgets, and objects turned on or off with their daily budget. totals[].others- Other changes (duplicates, comment actions).
totals[].pauses- Paused.
totals[].resumes- Turned on.
updatedAt- Last change.
version- The current version.
versions- Detail: every version, oldest first.
versions[].authorversions[].author.id- Person, API key or agent.
versions[].author.kind- Actor kind.One of
person,api_key,agent,system versions[].author.name- Name.
versions[].createdAt- When.
versions[].diffversions[].diff.added- Added.
versions[].diff.changed- Changed.
versions[].diff.removed- Removed.
versions[].feedback- The feedback it answers.
versions[].itemCount- Changes in it.
versions[].source- What made it.One of
agent,feedback,edit versions[].version- Number.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/change-sets/da17397c-759e-4179-916f-87cbbcd79e42/reject" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: bf772211-3134-46cd-a3bb-07638014b2a9" \
-H "Content-Type: application/json" \
-d '{
"reason": "Spend is pacing ahead of plan; hold the budget until Friday."
}'