API reference

Loop templates

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-templates

List loop templates

The app's template library, most wanted first: each template's card copy and the definition a loop starts as when a person picks it, named after the template. To start from one, create a loop with its definition (POST /loops), changed as needed. Guests don't see loops (403).

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
In the library's order.
items[].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[].descriptionstringRequired
What it does, in a sentence.
items[].familystringRequired
The card it's one version of, the same on every platform (pause-losing-ads for its LinkedIn version): one card per family.
items[].featuredbooleanRequired
Shown first on the Loops page.
items[].groupstringRequired
Its section in the library.One of optimize, monitor, engage
items[].idstringRequired
Stable template ID.
items[].platformstringRequired
The ad platform it's for, from GET /platforms. Listed only where its definition passes the check saving runs there for this workspace (the platform is on for its organization and runs every step).
items[].platformsarray of stringsRequired
Every platform its card is listed on here (its family's listed versions), in GET /platforms' order: the platform marks the card shows.
items[].titlestringRequired
Its name in the library.
items[].whenstringRequired
When it runs, e.g. Every morning.

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-templates" \
  -H "Authorization: Bearer $PLUTO_KEY"