Skip to main content
The Controlled Flows API reads and changes the flows in your workspaces: the conversational flows customers talk to, and the tools your Claudia agents call. Everything you do in the flow builder — create a flow, edit its blocks, check it, publish it, go back to an older version — has an endpoint here.

Authentication

Every call carries the id_token from Sign in as Authorization: Bearer <id_token>. It is the same token the Cloud Chat and Claudia APIs take, and it reaches the same workspaces you see in the flow builder — nothing else to configure. A missing or invalid token gets a 401.

The pieces

A TOOL belongs to the tenant of one of your Claudia projects: tenant names it and toolDescription is what an agent is told the tool does. Your token must grant that tenant for every write that touches the tool.

Changing a flow safely

The order below is the one the flow builder follows, and the one that avoids publishing something broken:
1

Read the flow

Get a flow returns the full definition and its updatedAt.
2

Send the change with updatedAt

Update a flow takes only the fields you change, plus the updatedAt you read. A stale updatedAt gets a 409 and nothing is saved, so two people editing the same flow cannot overwrite each other.groups, edges, events, variables and settings each replace the stored value as a whole: send the complete array with your edit applied, not just the piece you touched.
3

Validate the draft

Validate a flow runs the same checks as the flow builder’s publish button and returns isValid with a list of errors, each pointing at the groupId to fix.
4

Publish

Publish a flow with expectedUpdatedAt set to the updatedAt you validated. Only now do agents and customers see the change.
Publishing does not run the branch checks — that every branch of a conversational flow reaches a Claudia block, and that every branch of a tool ends in a Tool Output block. Skip the validation step and a flow with a dead-end branch publishes and leaves customers stuck.

Errors

Errors come back as { "message", "code" }, with issues listing the fields at fault when the request itself is invalid. The status says what to do next:

Over MCP

These endpoints are also tools on the Cloud Humans MCP server, so an assistant can build and publish a flow with you in conversation, under the same permissions as your token.