API reference

Loops

Loops, their runs and the approvals their actions wait for.

GET/loops

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

Permission: read

Parameters

NameTypeRequiredDescription
statusquerystringOptionalcurrent (default: drafts and loops that are on or off), draft, active, paused or archived.
minequerystringOptionaltrue: only loops the acting person created, themselves or through an agent.
folderIdquerystringOptionalOnly loops in this folder; none: loops in no folder.
qquerystringOptionalOnly loops whose name contains this (any case).
triggerquerystringOptionalOnly loops with this trigger block (schedule, new-comment, …; none: no trigger yet).
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500, 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[].accountsobjectRequired
items[].accounts.allbooleanRequired
A step or its trigger chose all ad accounts.
items[].accounts.idsarray of stringsRequired
The ad accounts it names (in a workspace with one ad account, that one when it names none).
items[].archivedAtstring (date-time) or nullRequired
Archived.
items[].attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
items[].createdAtstring (date-time)Required
Created.
items[].createdByobjectRequired
items[].createdBy.idstring (uuid)Required
Person, API key or agent.
items[].createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
items[].createdBy.namestringRequired
Name at the time.
items[].deletablebooleanRequired
Never turned on and never run: it can be deleted for good.
items[].enabledbooleanRequired
On: its trigger starts runs.
items[].folderIdstring (uuid) or nullRequired
Its folder; null: none.
items[].idstring (uuid)Required
Loop.
items[].lastRunobject or nullRequired
Its latest live run.
items[].lastRun.atstring (date-time)Required
When it started.
items[].lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
items[].lastRun.idstring (uuid)Required
Run.
items[].lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
items[].namestringRequired
The definition's name.
items[].nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
items[].ownerobject or nullRequired
The person it runs for; null when nobody owns it yet.
items[].owner.idstring (uuid)Required
Person.
items[].owner.namestringRequired
Name.
items[].ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
items[].platformstringRequired
The ad platform it runs on, from GET /platforms.
items[].sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
items[].statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
items[].stepsintegerRequired
Steps, the trigger included.
items[].triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
items[].triggerConfigobject or nullRequired
The trigger step's settings (a schedule's every, at, weekdays, times and timeZone), when it has a trigger.
items[].updatedAtstring (date-time)Required
Last saved.
items[].usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
items[].versionintegerRequired
Send it back as If-Match when saving.
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/loops" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/loops

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.

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

definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
platformstring
Optional: the ad platform it runs on, from GET /platforms (default: the definition's platform; a loop with no steps yet starts on GET /platforms defaultPlatform; else meta).
separateboolean
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.
sourceChatIdstring (uuid)
Optional: an Agent chat the acting person started.

Response201 Created

actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.atstring (date-time) or nullRequired
When.
actionsAllowed.bystring (uuid)Required
The person who allowed it.
actionsAllowed.byNamestring or nullRequired
Their name.
actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.versionintegerRequired
The version they allowed.
allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
archivedAtstring (date-time) or nullRequired
Archived.
attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
createdAtstring (date-time)Required
Created.
createdByobjectRequired
createdBy.idstring (uuid)Required
Person, API key or agent.
createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
createdBy.namestringRequired
Name at the time.
definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
enabledbooleanRequired
On: its trigger starts runs.
enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
enabledBystring (uuid) or nullRequired
Who turned it on or off last.
folderIdstring (uuid) or nullRequired
Its folder; null: none.
idstring (uuid)Required
Loop.
issuesarray of objectsRequired
What to finish before the loop can run.
issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
issues[].messagestringRequired
What to do.
issues[].paramsobject
The values code's sentence names, present exactly when it is.
issues[].stepIdstring or nullRequired
The step, or null for the loop.
lastChangeobject or nullRequired
The latest revision.
lastRunobject or nullRequired
Its latest live run.
lastRun.atstring (date-time)Required
When it started.
lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
lastRun.idstring (uuid)Required
Run.
lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
namestringRequired
The definition's name.
nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
platformstringRequired
The ad platform it runs on, from GET /platforms.
runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.idstring (uuid)Required
Person.
runsAs.namestringRequired
Name.
sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
updatedAtstring (date-time)Required
Last saved.
usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
versionintegerRequired
Send it back as If-Match when 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 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/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"
  }'
POST/loops/enabled

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.

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

enabledbooleanRequired
On (true) or Off (false).
loopIdsarray of strings (uuid)Required
The loops (1-500).

Response200 OK

itemsarray of objectsRequired
One per loop, in the order asked.
items[].errorsarray of objects
Why it wasn't turned on.
items[].errors[].fieldstringRequired
Where.
items[].errors[].messagestringRequired
What to do.
items[].loopobject
items[].loop.actionsAllowedobject or nullRequired
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.atstring (date-time) or nullRequired
When.
items[].loop.actionsAllowed.bystring (uuid)Required
The person who allowed it.
items[].loop.actionsAllowed.byNamestring or nullRequired
Their name.
items[].loop.actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
items[].loop.actionsAllowed.versionintegerRequired
The version they allowed.
items[].loop.allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
items[].loop.archivedAtstring (date-time) or nullRequired
Archived.
items[].loop.attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
items[].loop.createdAtstring (date-time)Required
Created.
items[].loop.createdByobjectRequired
items[].loop.createdBy.idstring (uuid)Required
Person, API key or agent.
items[].loop.createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
items[].loop.createdBy.namestringRequired
Name at the time.
items[].loop.definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
items[].loop.deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
items[].loop.enabledbooleanRequired
On: its trigger starts runs.
items[].loop.enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
items[].loop.enabledBystring (uuid) or nullRequired
Who turned it on or off last.
items[].loop.folderIdstring (uuid) or nullRequired
Its folder; null: none.
items[].loop.idstring (uuid)Required
Loop.
items[].loop.issuesarray of objectsRequired
What to finish before the loop can run.
items[].loop.issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
items[].loop.issues[].messagestringRequired
What to do.
items[].loop.issues[].paramsobject
The values code's sentence names, present exactly when it is.
items[].loop.issues[].stepIdstring or nullRequired
The step, or null for the loop.
items[].loop.lastChangeobject or nullRequired
The latest revision.
items[].loop.lastRunobject or nullRequired
Its latest live run.
items[].loop.lastRun.atstring (date-time)Required
When it started.
items[].loop.lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
items[].loop.lastRun.idstring (uuid)Required
Run.
items[].loop.lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
items[].loop.namestringRequired
The definition's name.
items[].loop.nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
items[].loop.ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
items[].loop.platformstringRequired
The ad platform it runs on, from GET /platforms.
items[].loop.runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
items[].loop.runsAs.idstring (uuid)Required
Person.
items[].loop.runsAs.namestringRequired
Name.
items[].loop.sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
items[].loop.statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
items[].loop.triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
items[].loop.updatedAtstring (date-time)Required
Last saved.
items[].loop.usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
items[].loop.versionintegerRequired
Send it back as If-Match when saving.
items[].loopIdstring (uuid)Required
The loop.
items[].messagestring
Why it conflicted.
items[].outcomestringRequired
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 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/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"
    ]
  }'
POST/loops/move

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.

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

folderIdstring (uuid) or null
The folder; null takes them out of their folder.
folderNamestring
A folder by name instead; created when missing.
loopIdsarray of strings (uuid)Required
The loops (1-500).

Response200 OK

createdFolderbooleanRequired
folderName named a folder that didn't exist yet.
folderobject or nullRequired
Where they are now; null: no folder.
folder.createdAtstring (date-time)Required
Created.
folder.idstring (uuid)Required
Folder.
folder.loopCountintegerRequired
Loops in it that aren't archived.
folder.namestringRequired
Its name, unique in the workspace in any case.
folder.updatedAtstring (date-time)Required
Last renamed.
folder.versionintegerRequired
Send it back as expectedVersion when renaming.
loopIdsarray of strings (uuid)Required
The loops asked for.
movedintegerRequired
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 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/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/loops/{id}

Get a loop

Answers with the version as ETag.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop's ID.
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

actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.atstring (date-time) or nullRequired
When.
actionsAllowed.bystring (uuid)Required
The person who allowed it.
actionsAllowed.byNamestring or nullRequired
Their name.
actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.versionintegerRequired
The version they allowed.
allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
archivedAtstring (date-time) or nullRequired
Archived.
attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
createdAtstring (date-time)Required
Created.
createdByobjectRequired
createdBy.idstring (uuid)Required
Person, API key or agent.
createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
createdBy.namestringRequired
Name at the time.
definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
enabledbooleanRequired
On: its trigger starts runs.
enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
enabledBystring (uuid) or nullRequired
Who turned it on or off last.
folderIdstring (uuid) or nullRequired
Its folder; null: none.
idstring (uuid)Required
Loop.
issuesarray of objectsRequired
What to finish before the loop can run.
issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
issues[].messagestringRequired
What to do.
issues[].paramsobject
The values code's sentence names, present exactly when it is.
issues[].stepIdstring or nullRequired
The step, or null for the loop.
lastChangeobject or nullRequired
The latest revision.
lastRunobject or nullRequired
Its latest live run.
lastRun.atstring (date-time)Required
When it started.
lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
lastRun.idstring (uuid)Required
Run.
lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
namestringRequired
The definition's name.
nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
platformstringRequired
The ad platform it runs on, from GET /platforms.
runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.idstring (uuid)Required
Person.
runsAs.namestringRequired
Name.
sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
updatedAtstring (date-time)Required
Last saved.
usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
versionintegerRequired
Send it back as If-Match when 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-After seconds. 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"
PATCH/loops/{id}

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

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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

definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
expectedVersioninteger
The version you edited from (or If-Match).

Response200 OK

actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.atstring (date-time) or nullRequired
When.
actionsAllowed.bystring (uuid)Required
The person who allowed it.
actionsAllowed.byNamestring or nullRequired
Their name.
actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.versionintegerRequired
The version they allowed.
allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
archivedAtstring (date-time) or nullRequired
Archived.
attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
createdAtstring (date-time)Required
Created.
createdByobjectRequired
createdBy.idstring (uuid)Required
Person, API key or agent.
createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
createdBy.namestringRequired
Name at the time.
definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
enabledbooleanRequired
On: its trigger starts runs.
enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
enabledBystring (uuid) or nullRequired
Who turned it on or off last.
folderIdstring (uuid) or nullRequired
Its folder; null: none.
idstring (uuid)Required
Loop.
issuesarray of objectsRequired
What to finish before the loop can run.
issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
issues[].messagestringRequired
What to do.
issues[].paramsobject
The values code's sentence names, present exactly when it is.
issues[].stepIdstring or nullRequired
The step, or null for the loop.
lastChangeobject or nullRequired
The latest revision.
lastRunobject or nullRequired
Its latest live run.
lastRun.atstring (date-time)Required
When it started.
lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
lastRun.idstring (uuid)Required
Run.
lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
namestringRequired
The definition's name.
nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
platformstringRequired
The ad platform it runs on, from GET /platforms.
runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.idstring (uuid)Required
Person.
runsAs.namestringRequired
Name.
sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
updatedAtstring (date-time)Required
Last saved.
usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
versionintegerRequired
Send it back as If-Match when 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 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 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/loops/{id}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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.

Response200 OK

deletedbooleanRequired
Always true.
idstring (uuid)Required
The loop that was deleted.
namestringRequired
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 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 DELETE "$PLUTO_API/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 58c4e1c4-fe54-476c-980b-046df81a0321"
POST/loops/{id}/archive

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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

expectedVersioninteger
Optional: the version you last read.

Response200 OK

actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.atstring (date-time) or nullRequired
When.
actionsAllowed.bystring (uuid)Required
The person who allowed it.
actionsAllowed.byNamestring or nullRequired
Their name.
actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.versionintegerRequired
The version they allowed.
allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
archivedAtstring (date-time) or nullRequired
Archived.
attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
createdAtstring (date-time)Required
Created.
createdByobjectRequired
createdBy.idstring (uuid)Required
Person, API key or agent.
createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
createdBy.namestringRequired
Name at the time.
definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
enabledbooleanRequired
On: its trigger starts runs.
enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
enabledBystring (uuid) or nullRequired
Who turned it on or off last.
folderIdstring (uuid) or nullRequired
Its folder; null: none.
idstring (uuid)Required
Loop.
issuesarray of objectsRequired
What to finish before the loop can run.
issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
issues[].messagestringRequired
What to do.
issues[].paramsobject
The values code's sentence names, present exactly when it is.
issues[].stepIdstring or nullRequired
The step, or null for the loop.
lastChangeobject or nullRequired
The latest revision.
lastRunobject or nullRequired
Its latest live run.
lastRun.atstring (date-time)Required
When it started.
lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
lastRun.idstring (uuid)Required
Run.
lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
namestringRequired
The definition's name.
nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
platformstringRequired
The ad platform it runs on, from GET /platforms.
runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.idstring (uuid)Required
Person.
runsAs.namestringRequired
Name.
sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
updatedAtstring (date-time)Required
Last saved.
usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
versionintegerRequired
Send it back as If-Match when 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 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/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
  }'
POST/loops/{id}/chat

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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.

Response200 OK

approvalsarray of objectsRequired
The approvals these messages carry.
approvals[].canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approvals[].canDecidebooleanRequired
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[].capabilitystringRequired
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[].chatIdstring (uuid)Required
Chat.
approvals[].createdAtstring (date-time)Required
Proposed.
approvals[].decidedAtstring (date-time) or nullRequired
Decided.
approvals[].effectobjectRequired
approvals[].effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entitiesarray of objectsRequired
What it changes.
approvals[].effect.entities[].idstring (uuid)Required
ID.
approvals[].effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approvals[].effect.entities[].launchIdstring (uuid)Required
Its launch.
approvals[].effect.entities[].namestring or nullRequired
Name.
approvals[].effect.linesarray of objectsRequired
Human details, never field names or IDs.
approvals[].effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approvals[].effect.lines[].valuestringRequired
Its value, e.g. New comment.
approvals[].effect.moneyarray of objectsRequired
Amounts it spends or sets.
approvals[].effect.money[].amountstringRequired
A decimal amount; never a float.
approvals[].effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].labelstringRequired
Label.
approvals[].effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approvals[].effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approvals[].errorobject or nullRequired
Why it failed, or the reason it was declined.
approvals[].error.codestringRequired
Stable code.
approvals[].error.messagestringRequired
For the person.
approvals[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approvals[].idstring (uuid)Required
Approval.
approvals[].messageIdstring (uuid)Required
The answer that proposed it.
approvals[].permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approvals[].resultobject or nullRequired
After approving.
approvals[].result.jobIdstring (uuid) or nullRequired
The job it started.
approvals[].result.summarystringRequired
What happened.
approvals[].statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approvals[].titlestringRequired
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[].toolstringRequired
The MCP tool it runs.
createdAtstring (date-time)Required
Started.
effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
hasEarlierbooleanRequired
Older messages exist: ?before=<first message id>.
idstring (uuid)Required
Chat.
lastMessageAtstring (date-time) or nullRequired
Last message.
loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
messagesarray of objectsRequired
The newest page (100 by default), oldest first.
messages[].approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
messages[].attachmentsarray of objectsRequired
Files the person attached.
messages[].attachments[].contentTypestring
A chat file's type.
messages[].attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
messages[].attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
messages[].attachments[].mediaIdstring (uuid)
A media library item.
messages[].attachments[].namestringRequired
File name.
messages[].attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytesinteger
A chat file's size.
messages[].chatIdstring (uuid)Required
Chat.
messages[].completedAtstring (date-time) or nullRequired
Finished.
messages[].createdAtstring (date-time)Required
Written.
messages[].errorobject or nullRequired
Why the answer failed.
messages[].error.codestringRequired
Stable code.
messages[].error.messagestringRequired
For the person.
messages[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
messages[].idstring (uuid)Required
Message.
messages[].modelstring or nullRequired
The model that produced the answer; null for the person's messages.
messages[].partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
messages[].parts[].choiceIdstring
question: the choice it was answered with.
messages[].parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
messages[].parts[].columnsarray of objects
table: its columns.
messages[].parts[].dataarray of objects
Every kind but combo and table: the series.
messages[].parts[].descriptionstring
One line under the title: the period, the unit.
messages[].parts[].groupsarray of objects
combo: its groups.
messages[].parts[].idstringRequired
The part; the same ID again replaces it.
messages[].parts[].itemsarray of objects
ads: the ads, in the order shown.
messages[].parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
messages[].parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
messages[].parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
messages[].parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
messages[].parts[].rowsarray of objects
table: its rows.
messages[].parts[].selectedarray of strings
selection: the options you confirmed.
messages[].parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
messages[].parts[].sizestring
simple-normalized only.One of small, medium, large
messages[].parts[].textstring
question: the question. text: the words (Markdown).
messages[].parts[].titlestring
What it shows.
messages[].parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
messages[].parts[].xAxisobject
label, hide.
messages[].parts[].yAxisobject
label, integersOnly.
messages[].rolestringRequired
Who wrote it.One of user, assistant
messages[].sentBystring (uuid) or nullRequired
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[].sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
messages[].sources[].titlestringRequired
Its title (its site when it named none).
messages[].sources[].urlstringRequired
The page.
messages[].statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
messages[].stepsarray of objectsRequired
What the Agent did, in order.
messages[].steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
messages[].steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entitiesarray of objectsRequired
What it touched.
messages[].steps[].entities[].idstring (uuid)Required
ID.
messages[].steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
messages[].steps[].entities[].launchIdstring (uuid)Required
Its launch.
messages[].steps[].entities[].namestring or nullRequired
Name.
messages[].steps[].finishedAtstring (date-time) or nullRequired
Finished.
messages[].steps[].idstringRequired
Step.
messages[].steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
messages[].steps[].labelstringRequired
Present tense while running, past tense when done.
messages[].steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
messages[].steps[].startedAtstring (date-time)Required
Started.
messages[].steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
messages[].steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
messages[].textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
messages[].versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMsinteger or nullRequired
Active time, excluding waits for approval.
modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
sourcestringRequired
Where it started.One of page, panel, home, loop
statusstringRequired
What it's doing.One of idle, running, awaiting_approval
titlestring or nullRequired
Title; null until the first answer names it.
unreadbooleanRequired
An answer arrived after the person last read it.
updatedAtstring (date-time)Required
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 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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/chat" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: b4823e6c-4cf8-4686-a846-8c592410b02b"
GET/loops/{id}/duplicate

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop's ID.
platformquerystringOptionalThe ad platform the copy would run on, from GET /platforms (default: the loop's own).
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

leftOutarray of objectsRequired
The blocks it would leave out.
leftOut[].reasonstringRequired
Why the platform doesn't run it.
leftOut[].stepIdstringRequired
The step.
leftOut[].titlestringRequired
Its block's title.
platformstringRequired
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-After seconds. 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"
POST/loops/{id}/duplicate

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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

platformstring
Optional: the ad platform the copy runs on, from GET /platforms (default: the loop's own).

Response201 Created

leftOutarray of objectsRequired
The blocks it left out.
leftOut[].reasonstringRequired
Why the platform doesn't run it.
leftOut[].stepIdstringRequired
The step.
leftOut[].titlestringRequired
Its block's title.
loopobjectRequired
loop.actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
loop.actionsAllowed.atstring (date-time) or nullRequired
When.
loop.actionsAllowed.bystring (uuid)Required
The person who allowed it.
loop.actionsAllowed.byNamestring or nullRequired
Their name.
loop.actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
loop.actionsAllowed.versionintegerRequired
The version they allowed.
loop.allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
loop.archivedAtstring (date-time) or nullRequired
Archived.
loop.attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
loop.createdAtstring (date-time)Required
Created.
loop.createdByobjectRequired
loop.createdBy.idstring (uuid)Required
Person, API key or agent.
loop.createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
loop.createdBy.namestringRequired
Name at the time.
loop.definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
loop.deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
loop.enabledbooleanRequired
On: its trigger starts runs.
loop.enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
loop.enabledBystring (uuid) or nullRequired
Who turned it on or off last.
loop.folderIdstring (uuid) or nullRequired
Its folder; null: none.
loop.idstring (uuid)Required
Loop.
loop.issuesarray of objectsRequired
What to finish before the loop can run.
loop.issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
loop.issues[].messagestringRequired
What to do.
loop.issues[].paramsobject
The values code's sentence names, present exactly when it is.
loop.issues[].stepIdstring or nullRequired
The step, or null for the loop.
loop.lastChangeobject or nullRequired
The latest revision.
loop.lastRunobject or nullRequired
Its latest live run.
loop.lastRun.atstring (date-time)Required
When it started.
loop.lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
loop.lastRun.idstring (uuid)Required
Run.
loop.lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
loop.namestringRequired
The definition's name.
loop.nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
loop.ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
loop.platformstringRequired
The ad platform it runs on, from GET /platforms.
loop.runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
loop.runsAs.idstring (uuid)Required
Person.
loop.runsAs.namestringRequired
Name.
loop.sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
loop.statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
loop.triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
loop.updatedAtstring (date-time)Required
Last saved.
loop.usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
loop.versionintegerRequired
Send it back as If-Match when 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 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/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"
  }'
PUT/loops/{id}/enabled

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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

allowActionsboolean
Optional: let this version act without asking (a person holding every live capability its steps need, with expectedVersion), or false to withdraw it.
enabledbooleanRequired
On (true) or Off (false).
expectedVersioninteger
Optional: the version you last read (or If-Match).

Response200 OK

actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.atstring (date-time) or nullRequired
When.
actionsAllowed.bystring (uuid)Required
The person who allowed it.
actionsAllowed.byNamestring or nullRequired
Their name.
actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.versionintegerRequired
The version they allowed.
allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
archivedAtstring (date-time) or nullRequired
Archived.
attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
createdAtstring (date-time)Required
Created.
createdByobjectRequired
createdBy.idstring (uuid)Required
Person, API key or agent.
createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
createdBy.namestringRequired
Name at the time.
definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
enabledbooleanRequired
On: its trigger starts runs.
enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
enabledBystring (uuid) or nullRequired
Who turned it on or off last.
folderIdstring (uuid) or nullRequired
Its folder; null: none.
idstring (uuid)Required
Loop.
issuesarray of objectsRequired
What to finish before the loop can run.
issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
issues[].messagestringRequired
What to do.
issues[].paramsobject
The values code's sentence names, present exactly when it is.
issues[].stepIdstring or nullRequired
The step, or null for the loop.
lastChangeobject or nullRequired
The latest revision.
lastRunobject or nullRequired
Its latest live run.
lastRun.atstring (date-time)Required
When it started.
lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
lastRun.idstring (uuid)Required
Run.
lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
namestringRequired
The definition's name.
nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
platformstringRequired
The ad platform it runs on, from GET /platforms.
runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.idstring (uuid)Required
Person.
runsAs.namestringRequired
Name.
sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
updatedAtstring (date-time)Required
Last saved.
usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
versionintegerRequired
Send it back as If-Match when 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 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 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
  }'
GET/loops/{id}/revisions

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop's ID.
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
Newest first.
items[].actionstringRequired
What happened.One of created, updated, archived
items[].actorobjectRequired
items[].actor.idstring (uuid)Required
Person, API key or agent.
items[].actor.kindstringRequired
Actor kind.One of person, api_key, agent, system
items[].actor.namestringRequired
Name at the time.
items[].chatIdstring (uuid) or nullRequired
The Agent chat (agent_chat only).
items[].createdAtstring (date-time)Required
When.
items[].idstring (uuid)Required
Revision.
items[].loopIdstring (uuid)Required
Loop.
items[].messageIdstring (uuid) or nullRequired
The Agent's answer that made the change.
items[].summarystringRequired
What changed, e.g. "Added 3 steps".
items[].versionintegerRequired
The version this saved.
items[].viastringRequired
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-After seconds. 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"
GET/loops/{id}/runs

List a loop's runs

Live and test runs, newest first.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop's ID.
modequerystringOptionallive or test; both by default.
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[].countsobjectRequired
items[].counts.actedinteger
Items acted on.
items[].counts.actionsDoneinteger
Actions done.
items[].counts.actionsPlannedinteger
Actions a test run planned.
items[].counts.approvalinteger
Items waiting for approval.
items[].counts.approvalsPendinginteger
Approvals waiting.
items[].counts.deferredinteger
Items waiting for a rate limit.
items[].counts.failedinteger
Items that failed.
items[].counts.itemsinteger
Items its For each steps found.
items[].counts.no_actioninteger
Items with nothing to do.
items[].counts.plannedinteger
Items a test run would act on.
items[].counts.skippedinteger
Items left alone (not managed in Pluto, changed outside Pluto, declined).
items[].counts.stepsinteger
Step instances.
items[].createdAtstring (date-time)Required
Created.
items[].errorobject or nullRequired
Why it failed: code, message and the stepId that failed, when a step did.
items[].finishedAtstring (date-time) or nullRequired
Ended.
items[].idstring (uuid)Required
Run.
items[].loopIdstring (uuid)Required
Loop.
items[].loopVersionintegerRequired
The loop's version it ran.
items[].modestringRequired
test: a dry run that changed nothing.One of live, test
items[].startedAtstring (date-time) or nullRequired
Started.
items[].startedByobjectRequired
items[].startedBy.idstring (uuid)Required
Person, API key or agent.
items[].startedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
items[].startedBy.namestringRequired
Name at the time.
items[].statusstringRequired
waiting: on a Wait step or a rate limit.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
items[].triggerobjectRequired
items[].trigger.blockstringRequired
The trigger block: schedule, data-updated, metric-threshold, budget-spent, new-comment, status-changed, changed-in-meta, new-lead, creative-uploaded or manual.
items[].trigger.parentobject
items[].trigger.parent.loopIdstring (uuid)Required
The loop whose run started it.
items[].trigger.parent.loopNamestringRequired
That loop's name.
items[].trigger.parent.runIdstring (uuid)Required
That run.
items[].trigger.sourcestringRequired
What started it: schedule, event, manual (by hand), test or loop (another loop's Run loop step).
items[].trigger.subjectstring or nullRequired
What it was about (a comment, an ad), when the trigger names something.
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.
  • 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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/runs" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/loops/{id}/runs

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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

modestring
Optional: live (default) or test.One of live, test

Response202 Accepted

countsobjectRequired
counts.actedinteger
Items acted on.
counts.actionsDoneinteger
Actions done.
counts.actionsPlannedinteger
Actions a test run planned.
counts.approvalinteger
Items waiting for approval.
counts.approvalsPendinginteger
Approvals waiting.
counts.deferredinteger
Items waiting for a rate limit.
counts.failedinteger
Items that failed.
counts.itemsinteger
Items its For each steps found.
counts.no_actioninteger
Items with nothing to do.
counts.plannedinteger
Items a test run would act on.
counts.skippedinteger
Items left alone (not managed in Pluto, changed outside Pluto, declined).
counts.stepsinteger
Step instances.
createdAtstring (date-time)Required
Created.
errorobject or nullRequired
Why it failed: code, message and the stepId that failed, when a step did.
finishedAtstring (date-time) or nullRequired
Ended.
idstring (uuid)Required
Run.
loopIdstring (uuid)Required
Loop.
loopVersionintegerRequired
The loop's version it ran.
modestringRequired
test: a dry run that changed nothing.One of live, test
startedAtstring (date-time) or nullRequired
Started.
startedByobjectRequired
startedBy.idstring (uuid)Required
Person, API key or agent.
startedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
startedBy.namestringRequired
Name at the time.
statusstringRequired
waiting: on a Wait step or a rate limit.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
triggerobjectRequired
trigger.blockstringRequired
The trigger block: schedule, data-updated, metric-threshold, budget-spent, new-comment, status-changed, changed-in-meta, new-lead, creative-uploaded or manual.
trigger.parentobject
trigger.parent.loopIdstring (uuid)Required
The loop whose run started it.
trigger.parent.loopNamestringRequired
That loop's name.
trigger.parent.runIdstring (uuid)Required
That run.
trigger.sourcestringRequired
What started it: schedule, event, manual (by hand), test or loop (another loop's Run loop step).
trigger.subjectstring or nullRequired
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 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/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"
  }'
POST/loops/{id}/unarchive

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop'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.

Response200 OK

actionsAllowedobject or nullRequired
Whether it acts without asking first (budgets, bids, delivery, deletes, public replies), who allowed it and for which version; null: it asks.
actionsAllowed.atstring (date-time) or nullRequired
When.
actionsAllowed.bystring (uuid)Required
The person who allowed it.
actionsAllowed.byNamestring or nullRequired
Their name.
actionsAllowed.currentbooleanRequired
It's the current version; false once the loop was saved since, and it asks again.
actionsAllowed.versionintegerRequired
The version they allowed.
allowNeedsarray of stringsRequired
What letting this version act without asking needs from whoever allows it: every live capability its steps need (budgets:write, delivery:write, ...) and loops:write. Allowing it is refused, naming the first one missing, to someone without each.
archivedAtstring (date-time) or nullRequired
Archived.
attentionstring or nullRequired
On, but its trigger watches nothing: needsPages (a New comment trigger with several Pages in the workspace and none chosen) or needsAccounts (an ad account trigger with several ad accounts and none it can be sure of). Choose them on the trigger. Null otherwise.One of needsPages, needsAccounts
createdAtstring (date-time)Required
Created.
createdByobjectRequired
createdBy.idstring (uuid)Required
Person, API key or agent.
createdBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
createdBy.namestringRequired
Name at the time.
definitionobjectRequired
The LoopDefinition { version: 1, name, platform, trigger, nodes, edges } (the loop builder's contract, docs/architecture.md "Loops"). platform is the ad platform the loop runs on, from GET /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 in config are decimal strings. An Agent or Write reply step's skills pins up to 5 skills by name from GET /loop-skills (shared with the workspace or Pluto's); another name is a 422.
deletablebooleanRequired
Never turned on and never run: DELETE /loops/{id} deletes it for good. Otherwise archive it.
enabledbooleanRequired
On: its trigger starts runs.
enabledAtstring (date-time) or nullRequired
When it was last turned on or off.
enabledBystring (uuid) or nullRequired
Who turned it on or off last.
folderIdstring (uuid) or nullRequired
Its folder; null: none.
idstring (uuid)Required
Loop.
issuesarray of objectsRequired
What to finish before the loop can run.
issues[].codestring
A registered message's stable code (such as loop_name_missing), for an app to say it in its language; absent for a message without one.
issues[].messagestringRequired
What to do.
issues[].paramsobject
The values code's sentence names, present exactly when it is.
issues[].stepIdstring or nullRequired
The step, or null for the loop.
lastChangeobject or nullRequired
The latest revision.
lastRunobject or nullRequired
Its latest live run.
lastRun.atstring (date-time)Required
When it started.
lastRun.finishedAtstring (date-time) or nullRequired
When it finished; null while it runs.
lastRun.idstring (uuid)Required
Run.
lastRun.statusstringRequired
Its status.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
namestringRequired
The definition's name.
nextRunAtstring (date-time) or nullRequired
When its schedule next runs (on, scheduled loops only).
ownerIdstring (uuid) or nullRequired
The person behind the creator: runs act for them.
platformstringRequired
The ad platform it runs on, from GET /platforms.
runsAsobject or nullRequired
Whom its runs act as: the owner, or the person who last changed its steps when they may do less.
runsAs.idstring (uuid)Required
Person.
runsAs.namestringRequired
Name.
sourceChatIdstring (uuid) or nullRequired
The Agent chat that holds the loop's history.
statusstringRequired
draft until turned on; active is On, paused is Off.One of draft, active, paused, archived
triggerstring or nullRequired
The trigger block (schedule, manual, ...), when it has one.
updatedAtstring (date-time)Required
Last saved.
usesAibooleanRequired
Whether a step uses AI (counts toward AI usage).
versionintegerRequired
Send it back as If-Match when 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 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/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9/unarchive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 873ba764-7d6b-437d-a3ed-2ba33a520cde"
GET/loop-runs/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop run's ID.
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

approvalsarray of objectsRequired
Its approvals.
approvals[].canApprovebooleanRequired
The viewer is a person holding the capability of the action, and it's pending.
approvals[].capabilitystringRequired
The capability deciding it needs beyond loops:write, as an ID: the action's own (budgets:write for a budget change), or the first of what it needs that the viewer lacks.
approvals[].createdAtstring (date-time)Required
Asked.
approvals[].decidedAtstring (date-time) or nullRequired
When.
approvals[].decidedBystring (uuid) or nullRequired
Who decided.
approvals[].effectobjectRequired
What approving does, exactly: title, summary, lines, money as decimal strings with the currency, entities and warnings.
approvals[].errorobject or nullRequired
code and message when it failed or was declined (with the reason).
approvals[].expiresAtstring (date-time)Required
When it expires.
approvals[].idstring (uuid)Required
Approval.
approvals[].itemNamestring or nullRequired
The item's name.
approvals[].loopIdstring (uuid)Required
Loop.
approvals[].permissionstringRequired
The permission approving needs.One of publish, admin, organization
approvals[].resultobject or nullRequired
What the action returned (summary, data), once approved.
approvals[].runIdstring (uuid)Required
Run.
approvals[].scopestringRequired
The item's scope.
approvals[].statusstringRequired
Expires 24 hours after it was asked.One of pending, approved, rejected, failed, expired, cancelled
approvals[].stepIdstringRequired
The step that asked.
approvals[].toolstringRequired
The catalog tool approving runs.
approvals[].toolTitlestringRequired
Its title.
countsobjectRequired
counts.actedinteger
Items acted on.
counts.actionsDoneinteger
Actions done.
counts.actionsPlannedinteger
Actions a test run planned.
counts.approvalinteger
Items waiting for approval.
counts.approvalsPendinginteger
Approvals waiting.
counts.deferredinteger
Items waiting for a rate limit.
counts.failedinteger
Items that failed.
counts.itemsinteger
Items its For each steps found.
counts.no_actioninteger
Items with nothing to do.
counts.plannedinteger
Items a test run would act on.
counts.skippedinteger
Items left alone (not managed in Pluto, changed outside Pluto, declined).
counts.stepsinteger
Step instances.
createdAtstring (date-time)Required
Created.
errorobject or nullRequired
Why it failed: code, message and the stepId that failed, when a step did.
finishedAtstring (date-time) or nullRequired
Ended.
idstring (uuid)Required
Run.
itemTotalsmap of integerRequired
By For each step id: every item it found, listed or not.
itemsarray of objectsRequired
The items its For each steps found (the first 500, in the order found).
items[].adAccountIdstring or nullRequired
Its ad account (act_…).
items[].currencystring or nullRequired
The ad account's currency (ISO 4217).
items[].detailstring or nullRequired
Why, in a sentence.
items[].idstringRequired
Its Meta ID (Pluto's for comments).
items[].kindstringRequired
What it is.One of account, campaign, ad_set, ad, comment
items[].namestring or nullRequired
Name.
items[].outcomestring or nullRequired
What happened to it; null while running.One of acted, planned, approval, no_action, skipped, deferred, failed
items[].scopestringRequired
The item's scope.
items[].stepIdstringRequired
The For each step that found it.
itemsTotalintegerRequired
Every item its For each steps found, listed or not.
itemsTruncatedbooleanRequired
items stops short: there are more than 500 items. itemsTotal counts every one.
loopIdstring (uuid)Required
Loop.
loopVersionintegerRequired
The loop's version it ran.
modestringRequired
test: a dry run that changed nothing.One of live, test
startedAtstring (date-time) or nullRequired
Started.
startedByobjectRequired
startedBy.idstring (uuid)Required
Person, API key or agent.
startedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
startedBy.namestringRequired
Name at the time.
statusstringRequired
waiting: on a Wait step or a rate limit.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
stepStatesmap of objectRequired
By step id: the step across its items.
stepsarray of objectsRequired
Every step instance, in the order they were recorded.
steps[].activitystring or nullRequired
What an AI step is doing while it runs.One of thinking, generating, tool, approval
steps[].approvalIdstring (uuid) or nullRequired
The approval it waits for.
steps[].availableAtstring (date-time) or nullRequired
When a waiting or deferred step is due again.
steps[].blockstringRequired
Its block.
steps[].errorobject or nullRequired
code and message when it failed.
steps[].finishedAtstring (date-time) or nullRequired
Finished.
steps[].inputanyRequired
The tool arguments it ran (or would run) with.
steps[].itemNamestring or nullRequired
The item's name.
steps[].outputanyRequired
What it returned or produced.
steps[].outputsarray of stringsRequired
The outputs it continued on (next, a path, error); empty when the path ended here.
steps[].scopestringRequired
"" for the run, or the item it ran for (each-ad=123, nested each-ad-set=7/each-ad=123).
steps[].startedAtstring (date-time) or nullRequired
Started.
steps[].statusstringRequired
planned: what a test run would do; deferred: waiting for a rate limit.One of queued, running, waiting, awaiting_approval, deferred, succeeded, planned, skipped, failed
steps[].stepIdstringRequired
The step.
steps[].summarystring or nullRequired
A sentence for the history, e.g. "Pause “Spring – 3”".
steps[].titlestringRequired
The block as people read it.
steps[].toolstring or nullRequired
The catalog tool it ran, or would run.
steps[].toolTitlestring or nullRequired
The tool's title.
triggerobjectRequired
trigger.blockstringRequired
The trigger block: schedule, data-updated, metric-threshold, budget-spent, new-comment, status-changed, changed-in-meta, new-lead, creative-uploaded or manual.
trigger.parentobject
trigger.parent.loopIdstring (uuid)Required
The loop whose run started it.
trigger.parent.loopNamestringRequired
That loop's name.
trigger.parent.runIdstring (uuid)Required
That run.
trigger.sourcestringRequired
What started it: schedule, event, manual (by hand), test or loop (another loop's Run loop step).
trigger.subjectstring or nullRequired
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-After seconds. 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"
POST/loop-runs/{id}/cancel

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop run'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.

Response200 OK

countsobjectRequired
counts.actedinteger
Items acted on.
counts.actionsDoneinteger
Actions done.
counts.actionsPlannedinteger
Actions a test run planned.
counts.approvalinteger
Items waiting for approval.
counts.approvalsPendinginteger
Approvals waiting.
counts.deferredinteger
Items waiting for a rate limit.
counts.failedinteger
Items that failed.
counts.itemsinteger
Items its For each steps found.
counts.no_actioninteger
Items with nothing to do.
counts.plannedinteger
Items a test run would act on.
counts.skippedinteger
Items left alone (not managed in Pluto, changed outside Pluto, declined).
counts.stepsinteger
Step instances.
createdAtstring (date-time)Required
Created.
errorobject or nullRequired
Why it failed: code, message and the stepId that failed, when a step did.
finishedAtstring (date-time) or nullRequired
Ended.
idstring (uuid)Required
Run.
loopIdstring (uuid)Required
Loop.
loopVersionintegerRequired
The loop's version it ran.
modestringRequired
test: a dry run that changed nothing.One of live, test
startedAtstring (date-time) or nullRequired
Started.
startedByobjectRequired
startedBy.idstring (uuid)Required
Person, API key or agent.
startedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
startedBy.namestringRequired
Name at the time.
statusstringRequired
waiting: on a Wait step or a rate limit.One of queued, running, waiting, awaiting_approval, succeeded, failed, cancelled, skipped
triggerobjectRequired
trigger.blockstringRequired
The trigger block: schedule, data-updated, metric-threshold, budget-spent, new-comment, status-changed, changed-in-meta, new-lead, creative-uploaded or manual.
trigger.parentobject
trigger.parent.loopIdstring (uuid)Required
The loop whose run started it.
trigger.parent.loopNamestringRequired
That loop's name.
trigger.parent.runIdstring (uuid)Required
That run.
trigger.sourcestringRequired
What started it: schedule, event, manual (by hand), test or loop (another loop's Run loop step).
trigger.subjectstring or nullRequired
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 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/loop-runs/0c5c40b9-69f1-4c36-ad8b-39a2d806f990/cancel" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: bd062000-e277-4780-8c17-0dbbb05b6c3c"
POST/loop-runs/{id}/undo

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

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop run'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

indexinteger
Optional: one change, by its position in the step's changes; all of them when absent.
scopestring
Its scope: "" for the run (default), or the item's.
stepIdstringRequired
The step that made the changes.

Response200 OK

refusedarray of stringsRequired
Changes that couldn't be undone, each with why.
undonearray of integersRequired
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 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/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"
  }'
POST/loop-approvals/{id}/approve

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop approval'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

object

Response200 OK

canApprovebooleanRequired
The viewer is a person holding the capability of the action, and it's pending.
capabilitystringRequired
The capability deciding it needs beyond loops:write, as an ID: the action's own (budgets:write for a budget change), or the first of what it needs that the viewer lacks.
createdAtstring (date-time)Required
Asked.
decidedAtstring (date-time) or nullRequired
When.
decidedBystring (uuid) or nullRequired
Who decided.
effectobjectRequired
What approving does, exactly: title, summary, lines, money as decimal strings with the currency, entities and warnings.
errorobject or nullRequired
code and message when it failed or was declined (with the reason).
expiresAtstring (date-time)Required
When it expires.
idstring (uuid)Required
Approval.
itemNamestring or nullRequired
The item's name.
loopIdstring (uuid)Required
Loop.
permissionstringRequired
The permission approving needs.One of publish, admin, organization
resultobject or nullRequired
What the action returned (summary, data), once approved.
runIdstring (uuid)Required
Run.
scopestringRequired
The item's scope.
statusstringRequired
Expires 24 hours after it was asked.One of pending, approved, rejected, failed, expired, cancelled
stepIdstringRequired
The step that asked.
toolstringRequired
The catalog tool approving runs.
toolTitlestringRequired
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 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/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 '{}'
POST/loop-approvals/{id}/reject

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe loop approval'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; shown in the run.

Response200 OK

canApprovebooleanRequired
The viewer is a person holding the capability of the action, and it's pending.
capabilitystringRequired
The capability deciding it needs beyond loops:write, as an ID: the action's own (budgets:write for a budget change), or the first of what it needs that the viewer lacks.
createdAtstring (date-time)Required
Asked.
decidedAtstring (date-time) or nullRequired
When.
decidedBystring (uuid) or nullRequired
Who decided.
effectobjectRequired
What approving does, exactly: title, summary, lines, money as decimal strings with the currency, entities and warnings.
errorobject or nullRequired
code and message when it failed or was declined (with the reason).
expiresAtstring (date-time)Required
When it expires.
idstring (uuid)Required
Approval.
itemNamestring or nullRequired
The item's name.
loopIdstring (uuid)Required
Loop.
permissionstringRequired
The permission approving needs.One of publish, admin, organization
resultobject or nullRequired
What the action returned (summary, data), once approved.
runIdstring (uuid)Required
Run.
scopestringRequired
The item's scope.
statusstringRequired
Expires 24 hours after it was asked.One of pending, approved, rejected, failed, expired, cancelled
stepIdstringRequired
The step that asked.
toolstringRequired
The catalog tool approving runs.
toolTitlestringRequired
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 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/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."
  }'