API reference

Change sets

Plans of changes from the Agent and loops: propose, review, approve, send back and undo.

GET/change-sets

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

Permission: read

Parameters

NameTypeRequiredDescription
statusquerystringOptionalopen (pending, revising, approving), decided, or statuses separated by commas.
loopIdquerystringOptionalPlans from this loop.
runIdquerystringOptionalThe plan of this loop run.
chatIdquerystringOptionalPlans from this Agent chat.
minequerystringOptionaltrue: only plans proposed for the acting person.
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-200, default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].actsForobjectRequired
items[].actsFor.idstring (uuid)Required
Person.
items[].actsFor.namestringRequired
Name.
items[].canApprovebooleanRequired
The caller may approve it now.
items[].canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
items[].canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
items[].canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
items[].cannotApproveReasonstring or null
Why not, in words.
items[].cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
items[].cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
items[].capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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[].createdAtstring (date-time)Required
Proposed.
items[].decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
items[].expiresAtstring (date-time) or null
24 hours after it was proposed.
items[].idstring (uuid)Required
Change set.
items[].itemCountintegerRequired
Changes in the current version.
items[].itemsarray of objects
Detail: the changes.
items[].items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].items[].afterstringRequired
The value applying sets.
items[].items[].basedOnobject
items[].items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].items[].callobjectRequired
items[].items[].call.inputanyRequired
Its exact arguments.
items[].items[].call.toolstringRequired
The catalog tool.
items[].items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].items[].editablebooleanRequired
Its value can be edited now.
items[].items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].items[].objectobjectRequired
items[].items[].object.adAccountIdstring or null
act_…
items[].items[].object.adAccountNamestring or null
The ad account's name.
items[].items[].object.campaignIdstring or null
Its campaign.
items[].items[].object.campaignNamestring or null
Its campaign's name.
items[].items[].object.idstringRequired
Meta ID.
items[].items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].items[].object.namestring or null
Name as synced.
items[].items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].items[].permissionstringRequired
The permission applying it needs.
items[].items[].reasonstring or null
The agent's reason.
items[].items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].items[].summarystring or null
other changes: its effect in a sentence.
items[].items[].titlestring or null
other changes: what it does, as the approval card says it.
items[].leftOutarray of objects
Detail: proposals the limits left out.
items[].leftOut[].keystring or null
Key.
items[].leftOut[].reasonstringRequired
Why it's not in the plan.
items[].leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
items[].leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
items[].leftOut[].titlestringRequired
What it was.
items[].originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
items[].proposedByobjectRequired
items[].proposedBy.idstring (uuid)Required
Person, API key or agent.
items[].proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
items[].proposedBy.namestringRequired
Name.
items[].revisingobject or null
While revising: { since, feedback, by }.
items[].revisionErrorstring or null
Why the last revision made no new version.
items[].revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
items[].revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
items[].shownVersioninteger
Detail: the version summary and items are from.
items[].statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
items[].summarystring
Detail: Markdown.
items[].supersededBystring (uuid) or null
The newer version that replaced it.
items[].supersedesstring (uuid) or null
The plan it replaced.
items[].testbooleanRequired
From a test run: review only.
items[].titlestringRequired
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[].titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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[].totalsarray of objectsRequired
Per ad account and currency.
items[].totals[].adAccountIdstring or null
act_…
items[].totals[].adAccountNamestring or null
Name.
items[].totals[].bidsintegerRequired
Bid changes.
items[].totals[].currencystring or null
ISO 4217.
items[].totals[].decreasesintegerRequired
Budgets lowered.
items[].totals[].increasesintegerRequired
Budgets raised.
items[].totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
items[].totals[].othersinteger
Other changes (duplicates, comment actions).
items[].totals[].pausesintegerRequired
Paused.
items[].totals[].resumesintegerRequired
Turned on.
items[].updatedAtstring (date-time)Required
Last change.
items[].versionintegerRequired
The current version.
items[].versionsarray of objects
Detail: every version, oldest first.
items[].versions[].authorobjectRequired
items[].versions[].author.idstring (uuid)Required
Person, API key or agent.
items[].versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
items[].versions[].author.namestringRequired
Name.
items[].versions[].createdAtstring (date-time)Required
When.
items[].versions[].diffobjectRequired
items[].versions[].diff.addedarray of stringsRequired
Added.
items[].versions[].diff.changedarray of stringsRequired
Changed.
items[].versions[].diff.removedarray of stringsRequired
Removed.
items[].versions[].feedbackstring or null
The feedback it answers.
items[].versions[].itemCountintegerRequired
Changes in it.
items[].versions[].sourcestringRequired
What made it.One of agent, feedback, edit
items[].versions[].versionintegerRequired
Number.
nextAfterstring or nullRequired
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/change-sets" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/change-sets

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

changeSetIdstring (uuid)
Optional: make the next version of this plan.
expectedVersioninteger
Optional, with changeSetId: the version you revised (a newer one is a 409).
itemsarray of objectsRequired
1 to 500 changes.
items[].inputanyRequired
Its arguments, exactly as the tool takes them.
items[].reasonstring
Optional: why, for the person.
items[].toolstringRequired
The change.One of set_budget, set_delivery_status, set_bid
summarystringRequired
Markdown for the person: what the plan changes and why.
titlestring
Optional: the title (default "<you> wants to make N changes").

Response201 Created

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/change-sets/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe change set's ID.
versionquerystringOptionalOptional: an older version to show.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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-After seconds. 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"
POST/change-sets/{id}/approve

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.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe change set's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

versionintegerRequired
The version you reviewed.

Response200 OK

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
POST/change-sets/{id}/edit

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe change set's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

removearray of strings
Changes to take out.
setarray of objects
New values.
set[].afterstringRequired
The new value, a decimal string.
set[].keystringRequired
A change's key.
versionintegerRequired
The version you edited.

Response200 OK

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
POST/change-sets/{id}/feedback

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe change set's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

retryConflictsboolean
After applying (partially_applied or failed): 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.
textstring
The feedback, up to 4000 characters (optional with retryConflicts).
versioninteger
Optional: the version it's about; a newer one is a 409.

Response202 Accepted

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
POST/change-sets/{id}/items/{key}/undo

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.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe change set's ID.
keypathstringRequired
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

Response200 OK

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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 '{}'
POST/change-sets/{id}/reject

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe change set's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

reasonstring
Optional, up to 1000 characters.

Response200 OK

actsForobjectRequired
actsFor.idstring (uuid)Required
Person.
actsFor.namestringRequired
Name.
canApprovebooleanRequired
The caller may approve it now.
canDecidebooleanRequired
The caller may edit, send back, approve or reject it.
canRetryConflictsboolean
The caller may send the changes that conflicted back (feedback with retryConflicts).
canUndoboolean
The caller may undo its applied changes (the person it was for, or an organization owner or admin, with publish).
cannotApproveReasonstring or null
Why not, in words.
cannotApproveReasonCodestring
cannotApproveReason's code (plan_*), for an app to say it in its language; absent when approving is allowed.
cannotApproveReasonParamsany
The values cannotApproveReasonCode's sentence names (an object), present exactly when it is.
capabilitiesarray of strings
What approving or rejecting it needs: each change's capability (budgets:write for budgets and bids, delivery:write for 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.
createdAtstring (date-time)Required
Proposed.
decisionobject or null
Once decided: { status, by, at, reason, reasonCode?, reasonParams?, version }. reasonCode and reasonParams: the code of a reason Pluto wrote, for an app to say in its language; absent for a person's own reason.
expiresAtstring (date-time) or null
24 hours after it was proposed.
idstring (uuid)Required
Change set.
itemCountintegerRequired
Changes in the current version.
itemsarray of objects
Detail: the changes.
items[].actionstringRequired
What it changes; other has no before and after (a duplicate, a comment reply or moderation, another tool a loop step asks about) and is described by title and summary.One of budget, status, bid, other
items[].afterstringRequired
The value applying sets.
items[].basedOnobject
items[].basedOn.syncedAtstring (date-time) or null
When Meta last changed the object, as synced.
items[].basedOn.valuestring or nullRequired
The value it was planned against.
items[].beforestring or null
The value when the plan was made: a decimal string in currency, or ACTIVE/PAUSED; null when unknown.
items[].callobjectRequired
items[].call.inputanyRequired
Its exact arguments.
items[].call.toolstringRequired
The catalog tool.
items[].currencystring or null
ISO 4217 for money; null when not money or unknown (never guessed).
items[].dailyBudgetstring or null
The object's own daily budget (what pausing or resuming it does to daily spend).
items[].editablebooleanRequired
Its value can be edited now.
items[].fieldstringRequired
The field (call for other).One of daily_budget, lifetime_budget, status, bid, call
items[].keystringRequired
Stable across versions: <kind>:<meta id>:<budget|status|bid>.
items[].objectobjectRequired
items[].object.adAccountIdstring or null
act_…
items[].object.adAccountNamestring or null
The ad account's name.
items[].object.campaignIdstring or null
Its campaign.
items[].object.campaignNamestring or null
Its campaign's name.
items[].object.idstringRequired
Meta ID.
items[].object.kindstringRequired
Kind (comment and call for other changes).One of campaign, ad_set, ad, comment, call
items[].object.namestring or null
Name as synced.
items[].percentstring or null
Signed change of a budget in percent (20, -15.5).
items[].permissionstringRequired
The permission applying it needs.
items[].reasonstring or null
The agent's reason.
items[].resultobject or null
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 } }. readback is what the next sync read back: live when Meta shows the applied value, differs with the value Meta shows. messageCode and messageParams: a registered message's code, for an app to say in its language.
items[].summarystring or null
other changes: its effect in a sentence.
items[].titlestring or null
other changes: what it does, as the approval card says it.
leftOutarray of objects
Detail: proposals the limits left out.
leftOut[].keystring or null
Key.
leftOut[].reasonstringRequired
Why it's not in the plan.
leftOut[].reasonCodestring
A registered reason's code, for an app to say it in its language.
leftOut[].reasonParamsany
The values reasonCode's sentence names, present exactly when it is.
leftOut[].titlestringRequired
What it was.
originanyRequired
{ kind: loop, loopId, loopName, runId, stepId }, { kind: chat, chatId, chatTitle, messageId } or { kind: api, actor }.
proposedByobjectRequired
proposedBy.idstring (uuid)Required
Person, API key or agent.
proposedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
proposedBy.namestringRequired
Name.
revisingobject or null
While revising: { since, feedback, by }.
revisionErrorstring or null
Why the last revision made no new version.
revisionErrorCodestring
A registered revisionError's code, for an app to say it in its language.
revisionErrorParamsany
The values revisionErrorCode's sentence names (an object), present exactly when it is.
shownVersioninteger
Detail: the version summary and items are from.
statusstringRequired
Status.One of pending, revising, approving, applied, partially_applied, rejected, expired, superseded, failed
summarystring
Detail: Markdown.
supersededBystring (uuid) or null
The newer version that replaced it.
supersedesstring (uuid) or null
The plan it replaced.
testbooleanRequired
From a test run: review only.
titlestringRequired
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).
titleCodeany
The title as a code, for an app to say in its language: { code, params } with code change_set.title.proposed ("{who} wants to make {count} changes") or change_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.
totalsarray of objectsRequired
Per ad account and currency.
totals[].adAccountIdstring or null
act_…
totals[].adAccountNamestring or null
Name.
totals[].bidsintegerRequired
Bid changes.
totals[].currencystring or null
ISO 4217.
totals[].decreasesintegerRequired
Budgets lowered.
totals[].increasesintegerRequired
Budgets raised.
totals[].netDailystringRequired
Net change of daily spend, signed (+120.00): daily budgets, and objects turned on or off with their daily budget.
totals[].othersinteger
Other changes (duplicates, comment actions).
totals[].pausesintegerRequired
Paused.
totals[].resumesintegerRequired
Turned on.
updatedAtstring (date-time)Required
Last change.
versionintegerRequired
The current version.
versionsarray of objects
Detail: every version, oldest first.
versions[].authorobjectRequired
versions[].author.idstring (uuid)Required
Person, API key or agent.
versions[].author.kindstringRequired
Actor kind.One of person, api_key, agent, system
versions[].author.namestringRequired
Name.
versions[].createdAtstring (date-time)Required
When.
versions[].diffobjectRequired
versions[].diff.addedarray of stringsRequired
Added.
versions[].diff.changedarray of stringsRequired
Changed.
versions[].diff.removedarray of stringsRequired
Removed.
versions[].feedbackstring or null
The feedback it answers.
versions[].itemCountintegerRequired
Changes in it.
versions[].sourcestringRequired
What made it.One of agent, feedback, edit
versions[].versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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."
  }'