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.
List loop folders
The workspace's loop folders by name, with how many loops (not archived) each holds. One level: folders don't nest.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- By name.
items[].createdAt- Created.
items[].id- Folder.
items[].loopCount- Loops in it that aren't archived.
items[].name- Its name, unique in the workspace in any case.
items[].updatedAt- Last renamed.
items[].version- Send it back as
expectedVersionwhen renaming.
curl "$PLUTO_API/loop-folders" \
-H "Authorization: Bearer $PLUTO_KEY"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
id- Optional: the folder's ID.
name- Its name.
Response
createdAt- Created.
id- Folder.
loopCount- Loops in it that aren't archived.
name- Its name, unique in the workspace in any case.
updatedAt- Last renamed.
version- Send it back as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/loop-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 a loop folder
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop folder's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
createdAt- Created.
id- Folder.
loopCount- Loops in it that aren't archived.
name- Its name, unique in the workspace in any case.
updatedAt- Last renamed.
version- Send it back as
expectedVersionwhen 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-Afterseconds. 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"Rename a loop folder
Give the version you read as expectedVersion: a folder renamed since is a 409 with the folder as it is.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop folder's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you read.
name- Its new name.
Response
createdAt- Created.
id- Folder.
loopCount- Loops in it that aren't archived.
name- Its name, unique in the workspace in any case.
updatedAt- Last renamed.
version- Send it back as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/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 a loop folder
Its loops stay, in no folder (each move is audited); no loop is deleted. expectedVersion is optional.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The loop folder's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Optional: the version you read.
Response
id- The folder.
movedLoops- Loops taken out of it, archived ones included.
name- Its name.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/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
}'