> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Build, validate and publish controlled flows and the tools your agents call.

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.

```text theme={null}
https://api.cloudhumans.com/typebot/v1
```

## Authentication

Every call carries the `id_token` from [Sign in](https://docs.cloudhumans.com/api-reference/claudia/sign-in.md) 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

| Concept | What it is |
| - | - |
| Workspace | Holds the flows of one customer. Its `id` is the `workspaceId` the other endpoints take. |
| Flow | A graph of `groups` (holding ordered `blocks`) joined by `edges`, plus `variables` and `settings`. In requests and responses a flow travels in the `typebot` field. |
| Flow type | `settings.general.type`: `default` for a conversational flow, `TOOL` for a tool agents call, `CONTEXT_ENRICHMENT` for a flow that enriches a conversation's context. |
| Draft and published version | Every write changes the draft. Agents and customers run the published version until you publish again. |
| Version | A snapshot recorded on every publish and restore, which you can return to. |
| REST API credential | A base URL, headers and query params that an HTTP Request block sends without the secret appearing in the flow. |

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](https://docs.cloudhumans.com/api-reference/controlled-flows/v1/flows/get-a-flow.md) returns the full definition
and its `updatedAt`.

**2. Send the change with updatedAt**

[Update a flow](https://docs.cloudhumans.com/api-reference/controlled-flows/v1/flows/update-a-flow.md) 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](https://docs.cloudhumans.com/api-reference/controlled-flows/v1/flows/validate-a-flow.md) 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](https://docs.cloudhumans.com/api-reference/controlled-flows/v1/flows/publish-a-flow.md) with
`expectedUpdatedAt` set to the `updatedAt` you validated. Only now do agents and customers see
the change.

> [!WARNING]
>
> 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:

| Status | Meaning |
| - | - |
| `400` | The request or the resulting flow is invalid. `message` says what to fix; nothing was saved. |
| `401` | The token is missing, expired or invalid. Sign in again. |
| `403` | Your token does not grant the tool's tenant, or the action needs the workspace admin role. |
| `404` | The workspace or flow does not exist, or your token cannot reach it — the two look the same on purpose. |
| `409` | Someone changed the flow since you read it, or a credential with that name already exists. Read again and retry. |
| `429` | Too many requests. Wait and retry. |

## Over MCP

These endpoints are also tools on the [Cloud Humans MCP server](https://docs.cloudhumans.com/mcp/overview.md), so an assistant
can build and publish a flow with you in conversation, under the same permissions as your token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.