API reference

Loop folders

Loops: a LoopDefinition (the loop builder's flow), its revisions (who changed it: a person, the Agent in a chat, an MCP agent or an API key) and the Agent chat that holds its history, shared with everyone who can see the loop.

GET/loop-folders

List loop folders

The workspace's loop folders by name, with how many loops (not archived) each holds. One level: folders don't nest.

Permission: read

Parameters

NameTypeRequiredDescription
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
By name.
items[].createdAtstring (date-time)Required
Created.
items[].idstring (uuid)Required
Folder.
items[].loopCountintegerRequired
Loops in it that aren't archived.
items[].namestringRequired
Its name, unique in the workspace in any case.
items[].updatedAtstring (date-time)Required
Last renamed.
items[].versionintegerRequired
Send it back as expectedVersion when renaming.

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/loop-folders" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/loop-folders

Create a loop folder

Names are unique in any case, up to 80 characters. id lets a client choose the folder's ID (a retry, an optimistic list). Members who can edit loops create folders.

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

idstring (uuid)
Optional: the folder's ID.
namestringRequired
Its name.

Response201 Created

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
Folder.
loopCountintegerRequired
Loops in it that aren't archived.
namestringRequired
Its name, unique in the workspace in any case.
updatedAtstring (date-time)Required
Last renamed.
versionintegerRequired
Send it back as expectedVersion when renaming.

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/loop-folders" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 93f5eb23-da49-4a7d-ac4b-479a4f58033c" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dfe42d8e-c35b-4932-b4c5-c631bd71b216",
    "name": "Vitamin C Serum, UGC 9x16"
  }'
GET/loop-folders/{id}

Get a loop folder

Permission: read

Parameters

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

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
Folder.
loopCountintegerRequired
Loops in it that aren't archived.
namestringRequired
Its name, unique in the workspace in any case.
updatedAtstring (date-time)Required
Last renamed.
versionintegerRequired
Send it back as expectedVersion when renaming.

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-folders/dfe42d8e-c35b-4932-b4c5-c631bd71b216" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/loop-folders/{id}

Rename a loop folder

Give the version you read as expectedVersion: a folder renamed since is a 409 with the folder as it is.

Permission: writeCommand: send Idempotency-Key

Parameters

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

expectedVersionintegerRequired
The version you read.
namestringRequired
Its new name.

Response200 OK

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
Folder.
loopCountintegerRequired
Loops in it that aren't archived.
namestringRequired
Its name, unique in the workspace in any case.
updatedAtstring (date-time)Required
Last renamed.
versionintegerRequired
Send it back as expectedVersion when renaming.

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/loop-folders/dfe42d8e-c35b-4932-b4c5-c631bd71b216" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: a2ffbdec-9306-47cc-b3a0-4ac5493a5739" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "name": "Vitamin C Serum, UGC 9x16"
  }'
DELETE/loop-folders/{id}

Delete a loop folder

Its loops stay, in no folder (each move is audited); no loop is deleted. expectedVersion is optional.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Response200 OK

idstring (uuid)Required
The folder.
movedLoopsintegerRequired
Loops taken out of it, archived ones included.
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/loop-folders/dfe42d8e-c35b-4932-b4c5-c631bd71b216" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 13dc5898-c110-4510-86c5-274b0b61356c" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'