Authentication
Every call carries theid_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.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: