Loops
Loops, their runs and the approvals their actions wait for.
List loops
Most recently changed first. Anyone who views the workspace reads loops, people and their keys and agents alike; guests don't (403, naming ads:read).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Optional | current (default: drafts and loops that are on or off), draft, active, paused or archived. |
mine | string | Optional | true: only loops the acting person created, themselves or through an agent. |
folderId | string | Optional | Only loops in this folder; none: loops in no folder. |
q | string | Optional | Only loops whose name contains this (any case). |
trigger | string | Optional | Only loops with this trigger block (schedule, new-comment, …; none: no trigger yet). |
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500, 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[].accountsitems[].accounts.all- A step or its trigger chose all ad accounts.
items[].accounts.ids- The ad accounts it names (in a workspace with one ad account, that one when it names none).
items[].archivedAt- Archived.
items[].attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts items[].createdAt- Created.
items[].createdByitems[].createdBy.id- Person, API key or agent.
items[].createdBy.kind- Actor kind.One of
person,api_key,agent,system items[].createdBy.name- Name at the time.
items[].deletable- Never turned on and never run: it can be deleted for good.
items[].enabled- On: its trigger starts runs.
items[].folderId- Its folder; null: none.
items[].id- Loop.
items[].lastRun- Its latest live run.
items[].lastRun.at- When it started.
items[].lastRun.finishedAt- When it finished; null while it runs.
items[].lastRun.id- Run.
items[].lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped items[].name- The definition's name.
items[].nextRunAt- When its schedule next runs (on, scheduled loops only).
items[].owner- The person it runs for; null when nobody owns it yet.
items[].owner.id- Person.
items[].owner.name- Name.
items[].ownerId- The person behind the creator: runs act for them.
items[].platform- The ad platform it runs on, from
GET /platforms. items[].sourceChatId- The Agent chat that holds the loop's history.
items[].statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archiveditems[].steps- Steps, the trigger included.
items[].trigger- The trigger block (
schedule,manual, ...), when it has one. items[].triggerConfig- The trigger step's settings (a schedule's
every,at,weekdays,timesandtimeZone), when it has a trigger. items[].updatedAt- Last saved.
items[].usesAi- Whether a step uses AI (counts toward AI usage).
items[].version- Send it back as
If-Matchwhen saving. nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/loops" \
-H "Authorization: Bearer $PLUTO_KEY"Create a loop draft
Saves a new draft (version 1) and its first revision. sourceChatId attaches an Agent chat the acting person started as the loop's history; the in-app Agent always attaches the chat it answers in. Answers with the version as ETag.
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
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. platform- Optional: the ad platform it runs on, from
GET /platforms(default: the definition'splatform; a loop with no steps yet starts onGET /platformsdefaultPlatform; elsemeta). separate- For the in-app Agent in a loop's builder: a new loop separate from the one open there. It doesn't take the builder's chat.
sourceChatId- Optional: an Agent chat the acting person started.
Response
actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.at- When.
actionsAllowed.by- The person who allowed it.
actionsAllowed.byName- Their name.
actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.version- The version they allowed.
allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. archivedAt- Archived.
attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts createdAt- Created.
createdBycreatedBy.id- Person, API key or agent.
createdBy.kind- Actor kind.One of
person,api_key,agent,system createdBy.name- Name at the time.
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. enabled- On: its trigger starts runs.
enabledAt- When it was last turned on or off.
enabledBy- Who turned it on or off last.
folderId- Its folder; null: none.
id- Loop.
issues- What to finish before the loop can run.
issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. issues[].message- What to do.
issues[].params- The values
code's sentence names, present exactly when it is. issues[].stepId- The step, or null for the loop.
lastChange- The latest revision.
lastRun- Its latest live run.
lastRun.at- When it started.
lastRun.finishedAt- When it finished; null while it runs.
lastRun.id- Run.
lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped name- The definition's name.
nextRunAt- When its schedule next runs (on, scheduled loops only).
ownerId- The person behind the creator: runs act for them.
platform- The ad platform it runs on, from
GET /platforms. runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.id- Person.
runsAs.name- Name.
sourceChatId- The Agent chat that holds the loop's history.
statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedtrigger- The trigger block (
schedule,manual, ...), when it has one. updatedAt- Last saved.
usesAi- Whether a step uses AI (counts toward AI usage).
version- Send it back as
If-Matchwhen saving.
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/loops" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2eecdca9-e28e-40c1-9969-e9c0186dfa45" \
-H "Content-Type: application/json" \
-d '{
"definition": {},
"platform": "platform",
"separate": true,
"sourceChatId": "b92c243c-34d1-4512-a8e5-431c6dda1898"
}'Turn loops on/off
Turns 1 to 500 loops On or Off, each exactly like PUT /loops/{id}/enabled and in its own savepoint, so one loop that isn't ready never stops the others: accepted with the loop, rejected with what to finish first (errors, by step), or conflict (archived) with a message. Always 200 when the request itself is valid. Each loop is its own command under the request's Idempotency-Key, so a retry answers the same. A read-only organization may turn loops off, not on.
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
enabled- On (true) or Off (false).
loopIds- The loops (1-500).
Response
items- One per loop, in the order asked.
items[].errors- Why it wasn't turned on.
items[].errors[].field- Where.
items[].errors[].message- What to do.
items[].loopitems[].loop.actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
items[].loop.actionsAllowed.at- When.
items[].loop.actionsAllowed.by- The person who allowed it.
items[].loop.actionsAllowed.byName- Their name.
items[].loop.actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
items[].loop.actionsAllowed.version- The version they allowed.
items[].loop.allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. items[].loop.archivedAt- Archived.
items[].loop.attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts items[].loop.createdAt- Created.
items[].loop.createdByitems[].loop.createdBy.id- Person, API key or agent.
items[].loop.createdBy.kind- Actor kind.One of
person,api_key,agent,system items[].loop.createdBy.name- Name at the time.
items[].loop.definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. items[].loop.deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. items[].loop.enabled- On: its trigger starts runs.
items[].loop.enabledAt- When it was last turned on or off.
items[].loop.enabledBy- Who turned it on or off last.
items[].loop.folderId- Its folder; null: none.
items[].loop.id- Loop.
items[].loop.issues- What to finish before the loop can run.
items[].loop.issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. items[].loop.issues[].message- What to do.
items[].loop.issues[].params- The values
code's sentence names, present exactly when it is. items[].loop.issues[].stepId- The step, or null for the loop.
items[].loop.lastChange- The latest revision.
items[].loop.lastRun- Its latest live run.
items[].loop.lastRun.at- When it started.
items[].loop.lastRun.finishedAt- When it finished; null while it runs.
items[].loop.lastRun.id- Run.
items[].loop.lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped items[].loop.name- The definition's name.
items[].loop.nextRunAt- When its schedule next runs (on, scheduled loops only).
items[].loop.ownerId- The person behind the creator: runs act for them.
items[].loop.platform- The ad platform it runs on, from
GET /platforms. items[].loop.runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
items[].loop.runsAs.id- Person.
items[].loop.runsAs.name- Name.
items[].loop.sourceChatId- The Agent chat that holds the loop's history.
items[].loop.statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archiveditems[].loop.trigger- The trigger block (
schedule,manual, ...), when it has one. items[].loop.updatedAt- Last saved.
items[].loop.usesAi- Whether a step uses AI (counts toward AI usage).
items[].loop.version- Send it back as
If-Matchwhen saving. items[].loopId- The loop.
items[].message- Why it conflicted.
items[].outcome- What happened.One of
accepted,rejected,conflict
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/loops/enabled" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 93c47f64-01bd-4cdf-ba38-cfef059d8a72" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"loopIds": [
"94956d8d-acdf-4e32-b384-25d0b605c2a9"
]
}'Move loops to a folder
Moves 1 to 500 loops into a folder (folderId), into a folder by name (folderName: found in any case, created when the workspace has none by that name) or out of their folder (folderId: null). Give one of the two. Moving changes nothing else: not a loop's version, updatedAt, status or runs. Each loop whose folder changed is audited with its folder before and after. Loops not in this workspace are a 422 naming them.
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
folderId- The folder; null takes them out of their folder.
folderName- A folder by name instead; created when missing.
loopIds- The loops (1-500).
Response
createdFolderfolderNamenamed a folder that didn't exist yet.folder- Where they are now; null: no folder.
folder.createdAt- Created.
folder.id- Folder.
folder.loopCount- Loops in it that aren't archived.
folder.name- Its name, unique in the workspace in any case.
folder.updatedAt- Last renamed.
folder.version- Send it back as
expectedVersionwhen renaming. loopIds- The loops asked for.
moved- Loops whose folder changed.
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/loops/move" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1b7320fe-dac2-433c-9fd4-8f68f420d795" \
-H "Content-Type: application/json" \
-d '{
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"folderName": "UGC",
"loopIds": [
"94956d8d-acdf-4e32-b384-25d0b605c2a9"
]
}'Get a loop
Answers with the version as ETag.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop's ID. |
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
actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.at- When.
actionsAllowed.by- The person who allowed it.
actionsAllowed.byName- Their name.
actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.version- The version they allowed.
allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. archivedAt- Archived.
attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts createdAt- Created.
createdBycreatedBy.id- Person, API key or agent.
createdBy.kind- Actor kind.One of
person,api_key,agent,system createdBy.name- Name at the time.
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. enabled- On: its trigger starts runs.
enabledAt- When it was last turned on or off.
enabledBy- Who turned it on or off last.
folderId- Its folder; null: none.
id- Loop.
issues- What to finish before the loop can run.
issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. issues[].message- What to do.
issues[].params- The values
code's sentence names, present exactly when it is. issues[].stepId- The step, or null for the loop.
lastChange- The latest revision.
lastRun- Its latest live run.
lastRun.at- When it started.
lastRun.finishedAt- When it finished; null while it runs.
lastRun.id- Run.
lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped name- The definition's name.
nextRunAt- When its schedule next runs (on, scheduled loops only).
ownerId- The person behind the creator: runs act for them.
platform- The ad platform it runs on, from
GET /platforms. runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.id- Person.
runsAs.name- Name.
sourceChatId- The Agent chat that holds the loop's history.
statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedtrigger- The trigger block (
schedule,manual, ...), when it has one. updatedAt- Last saved.
usesAi- Whether a step uses AI (counts toward AI usage).
version- Send it back as
If-Matchwhen saving.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9" \
-H "Authorization: Bearer $PLUTO_KEY"Save a loop version
definition replaces the saved one. Give the version you edited from as If-Match: "<version>" or expectedVersion: a loop saved since is a 409 whose current is the loop as it is now, and nothing changes. Saving what's already saved makes no new version. A loop that's on stays on, and its next runs use the new version; while the saved version has issues, its trigger starts no runs. Archived loops can't change (409).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. expectedVersion- The version you edited from (or
If-Match).
Response
actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.at- When.
actionsAllowed.by- The person who allowed it.
actionsAllowed.byName- Their name.
actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.version- The version they allowed.
allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. archivedAt- Archived.
attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts createdAt- Created.
createdBycreatedBy.id- Person, API key or agent.
createdBy.kind- Actor kind.One of
person,api_key,agent,system createdBy.name- Name at the time.
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. enabled- On: its trigger starts runs.
enabledAt- When it was last turned on or off.
enabledBy- Who turned it on or off last.
folderId- Its folder; null: none.
id- Loop.
issues- What to finish before the loop can run.
issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. issues[].message- What to do.
issues[].params- The values
code's sentence names, present exactly when it is. issues[].stepId- The step, or null for the loop.
lastChange- The latest revision.
lastRun- Its latest live run.
lastRun.at- When it started.
lastRun.finishedAt- When it finished; null while it runs.
lastRun.id- Run.
lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped name- The definition's name.
nextRunAt- When its schedule next runs (on, scheduled loops only).
ownerId- The person behind the creator: runs act for them.
platform- The ad platform it runs on, from
GET /platforms. runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.id- Person.
runsAs.name- Name.
sourceChatId- The Agent chat that holds the loop's history.
statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedtrigger- The trigger block (
schedule,manual, ...), when it has one. updatedAt- Last saved.
usesAi- Whether a step uses AI (counts toward AI usage).
version- Send it back as
If-Matchwhen saving.
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 PATCH "$PLUTO_API/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2d30f137-e9bd-4ec1-bfdb-1d386e5ccdd7" \
-H "Content-Type: application/json" \
-d '{
"definition": {},
"expectedVersion": 3
}'Delete a draft
Deletes a loop for good, with its revisions: only one that was never turned on and never ran (deletable). A loop with a history is a 409 saying to archive it instead, so what it did stays on record. Its Agent chat stays with its person and is no longer the loop's. Retrying with the same Idempotency-Key answers the same.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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. |
Response
deleted- Always true.
id- The loop that was deleted.
name- Its name.
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 DELETE "$PLUTO_API/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 58c4e1c4-fe54-476c-980b-046df81a0321"Archive a loop
The loop stops running, leaves the list and can't change; its chat, revisions and runs stay. If-Match or expectedVersion is optional. Archiving an archived loop answers with it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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
expectedVersion- Optional: the version you last read.
Response
actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.at- When.
actionsAllowed.by- The person who allowed it.
actionsAllowed.byName- Their name.
actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.version- The version they allowed.
allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. archivedAt- Archived.
attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts createdAt- Created.
createdBycreatedBy.id- Person, API key or agent.
createdBy.kind- Actor kind.One of
person,api_key,agent,system createdBy.name- Name at the time.
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. enabled- On: its trigger starts runs.
enabledAt- When it was last turned on or off.
enabledBy- Who turned it on or off last.
folderId- Its folder; null: none.
id- Loop.
issues- What to finish before the loop can run.
issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. issues[].message- What to do.
issues[].params- The values
code's sentence names, present exactly when it is. issues[].stepId- The step, or null for the loop.
lastChange- The latest revision.
lastRun- Its latest live run.
lastRun.at- When it started.
lastRun.finishedAt- When it finished; null while it runs.
lastRun.id- Run.
lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped name- The definition's name.
nextRunAt- When its schedule next runs (on, scheduled loops only).
ownerId- The person behind the creator: runs act for them.
platform- The ad platform it runs on, from
GET /platforms. runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.id- Person.
runsAs.name- Name.
sourceChatId- The Agent chat that holds the loop's history.
statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedtrigger- The trigger block (
schedule,manual, ...), when it has one. updatedAt- Last saved.
usesAi- Whether a step uses AI (counts toward AI usage).
version- Send it back as
If-Matchwhen saving.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 18d991b6-4a41-4c2f-b96f-ed92e1277edf" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Open the loop's Agent chat
The chat attached to the loop, or a new chat started now and attached (the builder's composer on first use). A chat started here is shared with everyone who can see the loop; people who can use the Agent write in it with POST /agent/chats/{id}/messages, passing context.loopId. A chat that made the loop elsewhere stays private to its person until they share it (PATCH /agent/chats/{id} with shared); anyone else gets 403 naming that person. Needs a person; archived loops are 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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. |
Response
approvals- The approvals these messages carry.
approvals[].canApprove- The viewer can approve it: the same as
canDecide. approvals[].canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approvals[].capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approvals[].chatId- Chat.
approvals[].createdAt- Proposed.
approvals[].decidedAt- Decided.
approvals[].effectapprovals[].effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entities- What it changes.
approvals[].effect.entities[].id- ID.
approvals[].effect.entities[].kind- Kind.One of
launch,adSet,ad approvals[].effect.entities[].launchId- Its launch.
approvals[].effect.entities[].name- Name.
approvals[].effect.lines- Human details, never field names or IDs.
approvals[].effect.lines[].label- A human label, e.g. Trigger.
approvals[].effect.lines[].value- Its value, e.g. New comment.
approvals[].effect.money- Amounts it spends or sets.
approvals[].effect.money[].amount- A decimal amount; never a float.
approvals[].effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].label- Label.
approvals[].effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approvals[].effect.summary- What it does, in a sentence; empty when that would only repeat
title. approvals[].effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approvals[].effect.warnings- Things to know before approving.
approvals[].error- Why it failed, or the reason it was declined.
approvals[].error.code- Stable code.
approvals[].error.message- For the person.
approvals[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approvals[].id- Approval.
approvals[].messageId- The answer that proposed it.
approvals[].permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approvals[].result- After approving.
approvals[].result.jobId- The job it started.
approvals[].result.summary- What happened.
approvals[].status- State.One of
pending,approved,rejected,failed,superseded approvals[].title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approvals[].tool- The MCP tool it runs.
createdAt- Started.
effort- The reasoning effort picked for the chat; null: the model's default.
hasEarlier- Older messages exist:
?before=<first message id>. id- Chat.
lastMessageAt- Last message.
loopId- The loop it is the history of (it made the loop, or was started in its builder).
messages- The newest page (100 by default), oldest first.
messages[].approvalIds- Approvals raised in this answer.
messages[].attachments- Files the person attached.
messages[].attachments[].contentType- A chat file's type.
messages[].attachments[].fileId- A chat file, uploaded for the message.
messages[].attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive messages[].attachments[].mediaId- A media library item.
messages[].attachments[].name- File name.
messages[].attachments[].pageCount- Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytes- A chat file's size.
messages[].chatId- Chat.
messages[].completedAt- Finished.
messages[].createdAt- Written.
messages[].error- Why the answer failed.
messages[].error.code- Stable code.
messages[].error.message- For the person.
messages[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. messages[].id- Message.
messages[].model- The model that produced the answer; null for the person's messages.
messages[].parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).messages[].parts[].choiceIdquestion: the choice it was answered with.messages[].parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).messages[].parts[].columnstable: its columns.messages[].parts[].data- Every kind but
comboandtable: the series. messages[].parts[].description- One line under the title: the period, the unit.
messages[].parts[].groupscombo: its groups.messages[].parts[].id- The part; the same ID again replaces it.
messages[].parts[].itemsads: the ads, in the order shown.messages[].parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table messages[].parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).messages[].parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).messages[].parts[].proposedselection: the options the Agent recommends, checked at first.messages[].parts[].rowstable: its rows.messages[].parts[].selectedselection: the options you confirmed.messages[].parts[].showLegend- Whether a legend shows; absent: for two or more series.
messages[].parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessages[].parts[].textquestion: the question.text: the words (Markdown).messages[].parts[].title- What it shows.
messages[].parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text messages[].parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. messages[].parts[].xAxislabel,hide.messages[].parts[].yAxislabel,integersOnly.messages[].role- Who wrote it.One of
user,assistant messages[].sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
messages[].sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
messages[].sources[].site- The hostname without
www.. messages[].sources[].title- Its title (its site when it named none).
messages[].sources[].url- The page.
messages[].status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user messages[].steps- What the Agent did, in order.
messages[].steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other messages[].steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entities- What it touched.
messages[].steps[].entities[].id- ID.
messages[].steps[].entities[].kind- Kind.One of
launch,adSet,ad messages[].steps[].entities[].launchId- Its launch.
messages[].steps[].entities[].name- Name.
messages[].steps[].finishedAt- Finished.
messages[].steps[].id- Step.
messages[].steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch messages[].steps[].label- Present tense while running, past tense when done.
messages[].steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. messages[].steps[].startedAt- Started.
messages[].steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped messages[].steps[].tool- The MCP tool; null for every kind but
tool. messages[].text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). messages[].version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMs- Active time, excluding waits for approval.
model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. ownerId- The chat's person: only they rename, delete or share it.
shared- Shared with everyone who can see its loop; false: private to its person.
source- Where it started.One of
page,panel,home,loop status- What it's doing.One of
idle,running,awaiting_approval title- Title; null until the first answer names it.
unread- An answer arrived after the person last read it.
updatedAt- Last change.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/chat" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b4823e6c-4cf8-4686-a846-8c592410b02b"Preview duplicating a loop
What duplicating the loop to platform would leave out: the blocks that platform doesn't run, each with its title and why. A loop whose trigger has no counterpart there is a 409 saying so.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop's ID. |
platform | string | Optional | The ad platform the copy would run on, from GET /platforms (default: the loop's own). |
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
leftOut- The blocks it would leave out.
leftOut[].reason- Why the platform doesn't run it.
leftOut[].stepId- The step.
leftOut[].title- Its block's title.
platform- The copy's platform.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/duplicate" \
-H "Authorization: Bearer $PLUTO_KEY"Duplicate a loop
Copies the loop as a new draft that's off, on its own platform (named "… copy") or on another one. Each block keeps its place and settings where the platform runs it; settings that name the first platform's ad accounts, Pages or forms start over; blocks the platform doesn't run are left out and listed, never converted. A loop whose trigger has no counterpart there is a 409. Retrying with the same Idempotency-Key answers the same.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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
platform- Optional: the ad platform the copy runs on, from
GET /platforms(default: the loop's own).
Response
leftOut- The blocks it left out.
leftOut[].reason- Why the platform doesn't run it.
leftOut[].stepId- The step.
leftOut[].title- Its block's title.
looploop.actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
loop.actionsAllowed.at- When.
loop.actionsAllowed.by- The person who allowed it.
loop.actionsAllowed.byName- Their name.
loop.actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
loop.actionsAllowed.version- The version they allowed.
loop.allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. loop.archivedAt- Archived.
loop.attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts loop.createdAt- Created.
loop.createdByloop.createdBy.id- Person, API key or agent.
loop.createdBy.kind- Actor kind.One of
person,api_key,agent,system loop.createdBy.name- Name at the time.
loop.definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. loop.deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. loop.enabled- On: its trigger starts runs.
loop.enabledAt- When it was last turned on or off.
loop.enabledBy- Who turned it on or off last.
loop.folderId- Its folder; null: none.
loop.id- Loop.
loop.issues- What to finish before the loop can run.
loop.issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. loop.issues[].message- What to do.
loop.issues[].params- The values
code's sentence names, present exactly when it is. loop.issues[].stepId- The step, or null for the loop.
loop.lastChange- The latest revision.
loop.lastRun- Its latest live run.
loop.lastRun.at- When it started.
loop.lastRun.finishedAt- When it finished; null while it runs.
loop.lastRun.id- Run.
loop.lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped loop.name- The definition's name.
loop.nextRunAt- When its schedule next runs (on, scheduled loops only).
loop.ownerId- The person behind the creator: runs act for them.
loop.platform- The ad platform it runs on, from
GET /platforms. loop.runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
loop.runsAs.id- Person.
loop.runsAs.name- Name.
loop.sourceChatId- The Agent chat that holds the loop's history.
loop.statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedloop.trigger- The trigger block (
schedule,manual, ...), when it has one. loop.updatedAt- Last saved.
loop.usesAi- Whether a step uses AI (counts toward AI usage).
loop.version- Send it back as
If-Matchwhen saving.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/duplicate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 019b7904-3053-412f-8d4d-49a6383ef6c3" \
-H "Content-Type: application/json" \
-d '{
"platform": "Brevanne"
}'Turn a loop on or off
On (active): its trigger starts runs. Off: paused (a draft stays a draft); runs already going finish. Neither is a new version. Turning it on checks that it's complete (every problem is a 422 naming its step: steps/<id>, or loop) and that a schedule's time zone is known (its IANA zone, or the ad account's when Pluto can tell which: the one its Find steps name, or the one all the workspace's ad accounts share). Runs act for the loop's owner, with the owner's permissions. allowActions: true lets this version act without asking (budgets, bids, delivery, public comment replies and moderation; deletes on an ad platform always ask): only a person who holds every live capability its steps need (a loop that changes budgets needs budgets:write, not ads:publish), signed in to the app (403 otherwise, naming the first one missing), with expectedVersion (422 without it); a later save asks again. false withdraws it, and so does turning it off. If-Match or expectedVersion is optional otherwise; archived loops are 409. Answers with the version as ETag.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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
allowActions- Optional: let this version act without asking (a person holding every live capability its steps need, with
expectedVersion), orfalseto withdraw it. enabled- On (true) or Off (false).
expectedVersion- Optional: the version you last read (or
If-Match).
Response
actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.at- When.
actionsAllowed.by- The person who allowed it.
actionsAllowed.byName- Their name.
actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.version- The version they allowed.
allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. archivedAt- Archived.
attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts createdAt- Created.
createdBycreatedBy.id- Person, API key or agent.
createdBy.kind- Actor kind.One of
person,api_key,agent,system createdBy.name- Name at the time.
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. enabled- On: its trigger starts runs.
enabledAt- When it was last turned on or off.
enabledBy- Who turned it on or off last.
folderId- Its folder; null: none.
id- Loop.
issues- What to finish before the loop can run.
issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. issues[].message- What to do.
issues[].params- The values
code's sentence names, present exactly when it is. issues[].stepId- The step, or null for the loop.
lastChange- The latest revision.
lastRun- Its latest live run.
lastRun.at- When it started.
lastRun.finishedAt- When it finished; null while it runs.
lastRun.id- Run.
lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped name- The definition's name.
nextRunAt- When its schedule next runs (on, scheduled loops only).
ownerId- The person behind the creator: runs act for them.
platform- The ad platform it runs on, from
GET /platforms. runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.id- Person.
runsAs.name- Name.
sourceChatId- The Agent chat that holds the loop's history.
statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedtrigger- The trigger block (
schedule,manual, ...), when it has one. updatedAt- Last saved.
usesAi- Whether a step uses AI (counts toward AI usage).
version- Send it back as
If-Matchwhen saving.
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 PUT "$PLUTO_API/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/enabled" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 4afd610c-4e34-4315-8e6a-718e940567a1" \
-H "Content-Type: application/json" \
-d '{
"allowActions": true,
"enabled": true,
"expectedVersion": 3
}'List a loop's revisions
Every saved version, newest first: who (actor), how (via: app, agent_chat with the chat and the Agent message, mcp or api) and what changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop's ID. |
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- Newest first.
items[].action- What happened.One of
created,updated,archived items[].actoritems[].actor.id- Person, API key or agent.
items[].actor.kind- Actor kind.One of
person,api_key,agent,system items[].actor.name- Name at the time.
items[].chatId- The Agent chat (
agent_chatonly). items[].createdAt- When.
items[].id- Revision.
items[].loopId- Loop.
items[].messageId- The Agent's answer that made the change.
items[].summary- What changed, e.g. "Added 3 steps".
items[].version- The version this saved.
items[].via- How the change arrived.One of
app,agent_chat,mcp,api
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/revisions" \
-H "Authorization: Bearer $PLUTO_KEY"List a loop's runs
Live and test runs, newest first.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop's ID. |
mode | string | Optional | live or test; both by default. |
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[].countsitems[].counts.acted- Items acted on.
items[].counts.actionsDone- Actions done.
items[].counts.actionsPlanned- Actions a test run planned.
items[].counts.approval- Items waiting for approval.
items[].counts.approvalsPending- Approvals waiting.
items[].counts.deferred- Items waiting for a rate limit.
items[].counts.failed- Items that failed.
items[].counts.items- Items its For each steps found.
items[].counts.no_action- Items with nothing to do.
items[].counts.planned- Items a test run would act on.
items[].counts.skipped- Items left alone (not managed in Pluto, changed outside Pluto, declined).
items[].counts.steps- Step instances.
items[].createdAt- Created.
items[].error- Why it failed:
code,messageand thestepIdthat failed, when a step did. items[].finishedAt- Ended.
items[].id- Run.
items[].loopId- Loop.
items[].loopVersion- The loop's version it ran.
items[].modetest: a dry run that changed nothing.One oflive,testitems[].startedAt- Started.
items[].startedByitems[].startedBy.id- Person, API key or agent.
items[].startedBy.kind- Actor kind.One of
person,api_key,agent,system items[].startedBy.name- Name at the time.
items[].statuswaiting: on a Wait step or a rate limit.One ofqueued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skippeditems[].triggeritems[].trigger.block- The trigger block:
schedule,data-updated,metric-threshold,budget-spent,new-comment,status-changed,changed-in-meta,new-lead,creative-uploadedormanual. items[].trigger.parentitems[].trigger.parent.loopId- The loop whose run started it.
items[].trigger.parent.loopName- That loop's name.
items[].trigger.parent.runId- That run.
items[].trigger.source- What started it:
schedule,event,manual(by hand),testorloop(another loop's Run loop step). items[].trigger.subject- What it was about (a comment, an ad), when the trigger names something.
nextAfter- 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.
- 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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/runs" \
-H "Authorization: Bearer $PLUTO_KEY"Run a loop now, or test it
Starts a run now, whatever the loop's trigger, and answers with it queued. mode: live (the default) acts, with the loop owner's permissions; changes that need publish wait for approval unless the loop may act. A live run of a loop that may act without asking, or of one that starts such a loop, needs every live capability their versions need from whoever starts it (403 naming the first one missing as missingCapability). mode: test reads your data, checks conditions and runs AI steps, then plans every action, notification and wait and executes none. The loop has to be complete (a 422 names each step to finish) and not archived (409). A live run while another live run of the loop is going is a 409. Retrying with the same Idempotency-Key returns the same run.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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
mode- Optional:
live(default) ortest.One oflive,test
Response
countscounts.acted- Items acted on.
counts.actionsDone- Actions done.
counts.actionsPlanned- Actions a test run planned.
counts.approval- Items waiting for approval.
counts.approvalsPending- Approvals waiting.
counts.deferred- Items waiting for a rate limit.
counts.failed- Items that failed.
counts.items- Items its For each steps found.
counts.no_action- Items with nothing to do.
counts.planned- Items a test run would act on.
counts.skipped- Items left alone (not managed in Pluto, changed outside Pluto, declined).
counts.steps- Step instances.
createdAt- Created.
error- Why it failed:
code,messageand thestepIdthat failed, when a step did. finishedAt- Ended.
id- Run.
loopId- Loop.
loopVersion- The loop's version it ran.
modetest: a dry run that changed nothing.One oflive,teststartedAt- Started.
startedBystartedBy.id- Person, API key or agent.
startedBy.kind- Actor kind.One of
person,api_key,agent,system startedBy.name- Name at the time.
statuswaiting: on a Wait step or a rate limit.One ofqueued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skippedtriggertrigger.block- The trigger block:
schedule,data-updated,metric-threshold,budget-spent,new-comment,status-changed,changed-in-meta,new-lead,creative-uploadedormanual. trigger.parenttrigger.parent.loopId- The loop whose run started it.
trigger.parent.loopName- That loop's name.
trigger.parent.runId- That run.
trigger.source- What started it:
schedule,event,manual(by hand),testorloop(another loop's Run loop step). trigger.subject- What it was about (a comment, an ad), when the trigger names something.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/runs" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 982aff5a-bd1a-411d-9e66-e9325fec0ef6" \
-H "Content-Type: application/json" \
-d '{
"mode": "live"
}'Unarchive a loop
Brings an archived loop back: paused (Off) when it was on once, else a draft. A new version, recorded as "Restored the loop". A loop that isn't archived answers as it is. Answers with the version as ETag.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop'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. |
Response
actionsAllowed- Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.at- When.
actionsAllowed.by- The person who allowed it.
actionsAllowed.byName- Their name.
actionsAllowed.current- It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.version- The version they allowed.
allowNeeds- What letting this version act without asking needs from whoever allows it: every live capability its steps need (
budgets:write,delivery:write, ...) andloops:write. Allowing it is refused, naming the first one missing, to someone without each. archivedAt- Archived.
attention- On, but its trigger watches nothing:
needsPages(a New comment trigger with several Pages in the workspace and none chosen) orneedsAccounts(an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One ofneedsPages,needsAccounts createdAt- Created.
createdBycreatedBy.id- Person, API key or agent.
createdBy.kind- Actor kind.One of
person,api_key,agent,system createdBy.name- Name at the time.
definition- The LoopDefinition
{ version: 1, name, platform, trigger, nodes, edges }(the loop builder's contract, docs/architecture.md "Loops").platformis the ad platform the loop runs on, fromGET /platforms(absent:meta): every block works on it, and it can't change once the loop has a block (duplicate the loop to another platform instead; Run loop starts loops on other platforms). Drafts may be unfinished; malformed ones are a 422 listing every problem by path (definition/nodes/2/block). Numbers and money inconfigare decimal strings. An Agent or Write reply step'sskillspins up to 5 skills by name fromGET /loop-skills(shared with the workspace or Pluto's); another name is a 422. deletable- Never turned on and never run:
DELETE /loops/{id}deletes it for good. Otherwise archive it. enabled- On: its trigger starts runs.
enabledAt- When it was last turned on or off.
enabledBy- Who turned it on or off last.
folderId- Its folder; null: none.
id- Loop.
issues- What to finish before the loop can run.
issues[].code- A registered
message's stable code (such asloop_name_missing), for an app to say it in its language; absent for a message without one. issues[].message- What to do.
issues[].params- The values
code's sentence names, present exactly when it is. issues[].stepId- The step, or null for the loop.
lastChange- The latest revision.
lastRun- Its latest live run.
lastRun.at- When it started.
lastRun.finishedAt- When it finished; null while it runs.
lastRun.id- Run.
lastRun.status- Its status.One of
queued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skipped name- The definition's name.
nextRunAt- When its schedule next runs (on, scheduled loops only).
ownerId- The person behind the creator: runs act for them.
platform- The ad platform it runs on, from
GET /platforms. runsAs- Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.id- Person.
runsAs.name- Name.
sourceChatId- The Agent chat that holds the loop's history.
statusdraftuntil turned on;activeis On,pausedis Off.One ofdraft,active,paused,archivedtrigger- The trigger block (
schedule,manual, ...), when it has one. updatedAt- Last saved.
usesAi- Whether a step uses AI (counts toward AI usage).
version- Send it back as
If-Matchwhen saving.
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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/unarchive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 873ba764-7d6b-437d-a3ed-2ba33a520cde"Get a run
A run with its steps, items and approvals.
Every step instance (one per step and scope: "" for the run, or the item a For each found), stepStates per step across its items, the items with their outcome (the first 500; itemsTruncated says there are more, itemsTotal counts every one and itemTotals every one per For each step) and the run's approvals.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop run's ID. |
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
approvals- Its approvals.
approvals[].canApprove- The viewer is a person holding the capability of the action, and it's pending.
approvals[].capability- The capability deciding it needs beyond
loops:write, as an ID: the action's own (budgets:writefor a budget change), or the first of what it needs that the viewer lacks. approvals[].createdAt- Asked.
approvals[].decidedAt- When.
approvals[].decidedBy- Who decided.
approvals[].effect- What approving does, exactly: title, summary, lines, money as decimal strings with the currency, entities and warnings.
approvals[].errorcodeandmessagewhen it failed or was declined (with the reason).approvals[].expiresAt- When it expires.
approvals[].id- Approval.
approvals[].itemName- The item's name.
approvals[].loopId- Loop.
approvals[].permission- The permission approving needs.One of
publish,admin,organization approvals[].result- What the action returned (
summary,data), once approved. approvals[].runId- Run.
approvals[].scope- The item's scope.
approvals[].status- Expires 24 hours after it was asked.One of
pending,approved,rejected,failed,expired,cancelled approvals[].stepId- The step that asked.
approvals[].tool- The catalog tool approving runs.
approvals[].toolTitle- Its title.
countscounts.acted- Items acted on.
counts.actionsDone- Actions done.
counts.actionsPlanned- Actions a test run planned.
counts.approval- Items waiting for approval.
counts.approvalsPending- Approvals waiting.
counts.deferred- Items waiting for a rate limit.
counts.failed- Items that failed.
counts.items- Items its For each steps found.
counts.no_action- Items with nothing to do.
counts.planned- Items a test run would act on.
counts.skipped- Items left alone (not managed in Pluto, changed outside Pluto, declined).
counts.steps- Step instances.
createdAt- Created.
error- Why it failed:
code,messageand thestepIdthat failed, when a step did. finishedAt- Ended.
id- Run.
itemTotals- By For each step id: every item it found, listed or not.
items- The items its For each steps found (the first 500, in the order found).
items[].adAccountId- Its ad account (
act_…). items[].currency- The ad account's currency (ISO 4217).
items[].detail- Why, in a sentence.
items[].id- Its Meta ID (Pluto's for comments).
items[].kind- What it is.One of
account,campaign,ad_set,ad,comment items[].name- Name.
items[].outcome- What happened to it; null while running.One of
acted,planned,approval,no_action,skipped,deferred,failed items[].scope- The item's scope.
items[].stepId- The For each step that found it.
itemsTotal- Every item its For each steps found, listed or not.
itemsTruncateditemsstops short: there are more than 500 items.itemsTotalcounts every one.loopId- Loop.
loopVersion- The loop's version it ran.
modetest: a dry run that changed nothing.One oflive,teststartedAt- Started.
startedBystartedBy.id- Person, API key or agent.
startedBy.kind- Actor kind.One of
person,api_key,agent,system startedBy.name- Name at the time.
statuswaiting: on a Wait step or a rate limit.One ofqueued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skippedstepStates- By step id: the step across its items.
steps- Every step instance, in the order they were recorded.
steps[].activity- What an AI step is doing while it runs.One of
thinking,generating,tool,approval steps[].approvalId- The approval it waits for.
steps[].availableAt- When a waiting or deferred step is due again.
steps[].block- Its block.
steps[].errorcodeandmessagewhen it failed.steps[].finishedAt- Finished.
steps[].input- The tool arguments it ran (or would run) with.
steps[].itemName- The item's name.
steps[].output- What it returned or produced.
steps[].outputs- The outputs it continued on (
next, a path,error); empty when the path ended here. steps[].scope""for the run, or the item it ran for (each-ad=123, nestedeach-ad-set=7/each-ad=123).steps[].startedAt- Started.
steps[].statusplanned: what a test run would do;deferred: waiting for a rate limit.One ofqueued,running,waiting,awaiting_approval,deferred,succeeded,planned,skipped,failedsteps[].stepId- The step.
steps[].summary- A sentence for the history, e.g. "Pause “Spring – 3”".
steps[].title- The block as people read it.
steps[].tool- The catalog tool it ran, or would run.
steps[].toolTitle- The tool's title.
triggertrigger.block- The trigger block:
schedule,data-updated,metric-threshold,budget-spent,new-comment,status-changed,changed-in-meta,new-lead,creative-uploadedormanual. trigger.parenttrigger.parent.loopId- The loop whose run started it.
trigger.parent.loopName- That loop's name.
trigger.parent.runId- That run.
trigger.source- What started it:
schedule,event,manual(by hand),testorloop(another loop's Run loop step). trigger.subject- What it was about (a comment, an ad), when the trigger names something.
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/loop-runs/0c5c40b9-69f1-4c36-ad8b-39a2d806f990" \
-H "Authorization: Bearer $PLUTO_KEY"Cancel a run
Stops a run that's still going: nothing more starts, its open approvals are canceled and what already ran stays done. Canceling a run that ended answers with it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop run'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. |
Response
countscounts.acted- Items acted on.
counts.actionsDone- Actions done.
counts.actionsPlanned- Actions a test run planned.
counts.approval- Items waiting for approval.
counts.approvalsPending- Approvals waiting.
counts.deferred- Items waiting for a rate limit.
counts.failed- Items that failed.
counts.items- Items its For each steps found.
counts.no_action- Items with nothing to do.
counts.planned- Items a test run would act on.
counts.skipped- Items left alone (not managed in Pluto, changed outside Pluto, declined).
counts.steps- Step instances.
createdAt- Created.
error- Why it failed:
code,messageand thestepIdthat failed, when a step did. finishedAt- Ended.
id- Run.
loopId- Loop.
loopVersion- The loop's version it ran.
modetest: a dry run that changed nothing.One oflive,teststartedAt- Started.
startedBystartedBy.id- Person, API key or agent.
startedBy.kind- Actor kind.One of
person,api_key,agent,system startedBy.name- Name at the time.
statuswaiting: on a Wait step or a rate limit.One ofqueued,running,waiting,awaiting_approval,succeeded,failed,cancelled,skippedtriggertrigger.block- The trigger block:
schedule,data-updated,metric-threshold,budget-spent,new-comment,status-changed,changed-in-meta,new-lead,creative-uploadedormanual. trigger.parenttrigger.parent.loopId- The loop whose run started it.
trigger.parent.loopName- That loop's name.
trigger.parent.runId- That run.
trigger.source- What started it:
schedule,event,manual(by hand),testorloop(another loop's Run loop step). trigger.subject- What it was about (a comment, an ad), when the trigger names something.
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/loop-runs/0c5c40b9-69f1-4c36-ad8b-39a2d806f990/cancel" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: bd062000-e277-4780-8c17-0dbbb05b6c3c"Undo what a step changed
Sets back what a step of a live run changed on its ad platform: each budget or delivery status in the step's output.changes returns to the value it replaced, or only the change at index. Runs as the caller, who needs each change's own permission (publish for money and delivery), through the same per-change safety checks as any automated change. A change the platform hasn't confirmed yet, or didn't apply, is left as it is, with why. Undoing twice changes nothing more; a test run has nothing to undo (409).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop run'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
index- Optional: one change, by its position in the step's
changes; all of them when absent. scope- Its scope:
""for the run (default), or the item's. stepId- The step that made the changes.
Response
refused- Changes that couldn't be undone, each with why.
undone- The changes undone now, by position.
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/loop-runs/0c5c40b9-69f1-4c36-ad8b-39a2d806f990/undo" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8d7f9d0e-c404-47cd-9d90-3e828c346382" \
-H "Content-Type: application/json" \
-d '{
"index": 0,
"scope": "read",
"stepId": "df0ba415-a2b8-4651-a79b-8af1a5bddadf"
}'Approve a loop's action
Runs the action exactly as the approval shows it, once, as the signed-in person, and the run continues. Only a person can approve (API keys and agents get 403), and approving needs the capability of the action (budgets:write for a budget, ads:delete for a deletion: 403 naming it otherwise). An approval already decided answers with its decision and runs nothing again; one whose run ended is a 409. A failed action answers with the approval failed and its error.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop approval'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
object
Response
canApprove- The viewer is a person holding the capability of the action, and it's pending.
capability- The capability deciding it needs beyond
loops:write, as an ID: the action's own (budgets:writefor a budget change), or the first of what it needs that the viewer lacks. createdAt- Asked.
decidedAt- When.
decidedBy- Who decided.
effect- What approving does, exactly: title, summary, lines, money as decimal strings with the currency, entities and warnings.
errorcodeandmessagewhen it failed or was declined (with the reason).expiresAt- When it expires.
id- Approval.
itemName- The item's name.
loopId- Loop.
permission- The permission approving needs.One of
publish,admin,organization result- What the action returned (
summary,data), once approved. runId- Run.
scope- The item's scope.
status- Expires 24 hours after it was asked.One of
pending,approved,rejected,failed,expired,cancelled stepId- The step that asked.
tool- The catalog tool approving runs.
toolTitle- Its title.
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/loop-approvals/4ea8f935-13f1-4ebc-ad6e-82b0cea42073/approve" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: f4fb6d56-86c2-41f3-af00-a4a9b190345a" \
-H "Content-Type: application/json" \
-d '{}'Reject a loop's action
Declines the action: nothing changes and that item's path ends. Only a person can reject (API keys and agents get 403), and rejecting needs the capability of the action, as approving does (403 naming it otherwise). An approval already decided answers with its decision.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop approval'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; shown in the run.
Response
canApprove- The viewer is a person holding the capability of the action, and it's pending.
capability- The capability deciding it needs beyond
loops:write, as an ID: the action's own (budgets:writefor a budget change), or the first of what it needs that the viewer lacks. createdAt- Asked.
decidedAt- When.
decidedBy- Who decided.
effect- What approving does, exactly: title, summary, lines, money as decimal strings with the currency, entities and warnings.
errorcodeandmessagewhen it failed or was declined (with the reason).expiresAt- When it expires.
id- Approval.
itemName- The item's name.
loopId- Loop.
permission- The permission approving needs.One of
publish,admin,organization result- What the action returned (
summary,data), once approved. runId- Run.
scope- The item's scope.
status- Expires 24 hours after it was asked.One of
pending,approved,rejected,failed,expired,cancelled stepId- The step that asked.
tool- The catalog tool approving runs.
toolTitle- Its title.
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/loop-approvals/4ea8f935-13f1-4ebc-ad6e-82b0cea42073/reject" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 655eb3a5-d8f5-4cdd-a5a9-0fa1cca56e55" \
-H "Content-Type: application/json" \
-d '{
"reason": "Spend is pacing ahead of plan; hold the budget until Friday."
}'