> ## 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.

# Update a flow

> Changes a flow and returns it in full. The change lands in the **draft**: agents keep running the published version until you call **Publish a flow**.

Send only the fields you change, plus `typebot.updatedAt` from your last read. `updatedAt` is required (`400` without it), and a stale one is a `409` with nothing saved: read the flow again, redo the change and resend.

<Warning>`groups`, `edges`, `events`, `variables` and `settings` each **replace** the stored value as a whole. To change one block, read the flow, edit that block inside the full `groups` array and send `groups`, `edges` and `events` back complete. Sending only the group you touched deletes every other group.</Warning>

A tool has extra rules:

- Its name cannot change, it cannot be archived, and `tenant` and `toolDescription` cannot be emptied (`400`).
- When the flow is a tool before or after the change, both tenants must be ones your token grants (`403` otherwise). Flows that are not tools are not checked.
- When it becomes a tool, or moves to another tenant, its name must not collide with another tool there (`400`).

The result is checked like on create (graph consistency, script lint, client-side `Set variable`, `outputSchema`). Only problems that are new since the stored draft count, and a refusal lists each one and saves nothing.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json patch /v1/typebots/{flowId}
openapi: 3.0.3
info:
  title: Controlled Flows API
  version: 1.0.0
  description: >-
    Read, build, validate and publish controlled flows and the tools agents
    call.
servers:
  - url: https://api.cloudhumans.com/typebot
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: The workspaces that hold your flows.
  - name: Flows
    description: >-
      Read, create, change, validate and publish flows. Writes land in the
      draft; only a publish makes them live.
  - name: Versions
    description: The saved versions of a flow, and restoring one.
  - name: Credentials
    description: >-
      REST API credentials that HTTP Request blocks send without exposing the
      secret in the flow.
paths:
  /v1/typebots/{flowId}:
    patch:
      tags:
        - Flows
      summary: Update a flow
      description: >-
        Changes a flow and returns it in full. The change lands in the
        **draft**: agents keep running the published version until you call
        **Publish a flow**.


        Send only the fields you change, plus `typebot.updatedAt` from your last
        read. `updatedAt` is required (`400` without it), and a stale one is a
        `409` with nothing saved: read the flow again, redo the change and
        resend.


        <Warning>`groups`, `edges`, `events`, `variables` and `settings` each
        **replace** the stored value as a whole. To change one block, read the
        flow, edit that block inside the full `groups` array and send `groups`,
        `edges` and `events` back complete. Sending only the group you touched
        deletes every other group.</Warning>


        A tool has extra rules:


        - Its name cannot change, it cannot be archived, and `tenant` and
        `toolDescription` cannot be emptied (`400`).

        - When the flow is a tool before or after the change, both tenants must
        be ones your token grants (`403` otherwise). Flows that are not tools
        are not checked.

        - When it becomes a tool, or moves to another tenant, its name must not
        collide with another tool there (`400`).


        The result is checked like on create (graph consistency, script lint,
        client-side `Set variable`, `outputSchema`). Only problems that are new
        since the stored draft count, and a refusal lists each one and saves
        nothing.
      operationId: updateFlow
      parameters:
        - name: flowId
          in: path
          required: true
          description: >-
            The flow's internal id, e.g. `clx9z8y7x6w5v4u3t2s1`. Get it from
            **List flows** (the `id` field of each flow). It is NOT the
            `publicId` slug that appears in a flow's public URL: a slug answers
            404 here. A flow your token cannot write to answers 404,
            indistinguishable from one that does not exist.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - typebot
              description: The change to apply.
              properties:
                typebot:
                  type: object
                  required:
                    - updatedAt
                  description: >-
                    The fields to change, and only those, plus `updatedAt`.
                    Fields you omit keep their stored value, except that groups,
                    edges, events, variables, settings and theme replace the
                    stored value as a whole when sent.
                  properties:
                    name:
                      type: string
                      description: >-
                        The flow's name. Send it only to rename an
                        conversational flow. A TOOL cannot be renamed — the name
                        is the identity agents reference — and sending a
                        different name for one answers 400. Sending the
                        unchanged name is accepted.
                    icon:
                      type: string
                      description: An emoji or image URL shown next to the flow name.
                    folderId:
                      type: string
                      nullable: true
                      description: >-
                        The folder to put the flow in. An id that does not exist
                        puts it outside any folder on create; send `null` on
                        update to take it out of its folder.
                    groups:
                      type: array
                      items:
                        type: object
                        additionalProperties: true
                      description: >-
                        The flow's groups, each with its `id`, `title`,
                        `graphCoordinates` and ordered `blocks`. Same shape
                        **Get a flow** returns. REPLACES the whole list: groups
                        you leave out are deleted, with their blocks. Read the
                        flow with **Get a flow** first and send the complete
                        array with your changes applied. A tool's inputs are the
                        variables of a block of type `Declare variables`.
                    edges:
                      type: array
                      items:
                        type: object
                        additionalProperties: true
                      description: >-
                        The connections between groups and blocks: each has an
                        `id`, a `from` and a `to` pointing at group and block
                        ids that exist in `groups`. Same shape **Get a flow**
                        returns. REPLACES the whole list: send the complete
                        array together with `groups` and `events`. An edge
                        pointing at a missing group or block answers 400.
                    events:
                      type: array
                      items:
                        type: object
                        additionalProperties: true
                      description: >-
                        The flow's start event, exactly one entry. Same shape
                        **Get a flow** returns. REPLACES the list: send it with
                        `groups` and `edges` — a flow with no start event
                        answers 400.
                    variables:
                      type: array
                      items:
                        type: object
                        additionalProperties: true
                      description: >-
                        The variables the flow declares, each with an `id` and
                        `name`, and `isInputVariable` true for a tool input
                        declared in a `Declare variables` block. Same shape
                        **Get a flow** returns. Sent together with `groups` it
                        REPLACES the list; variables the blocks no longer use
                        are dropped.
                    settings:
                      type: object
                      additionalProperties: true
                      description: >-
                        The flow's settings. `general.type` is `default`, `TOOL`
                        or `CONTEXT_ENRICHMENT`; for a TOOL, `tool.outputSchema`
                        is a JSON Schema (root `type` `object`) that every
                        answer of the tool must satisfy, allowed only on a TOOL
                        and refused with 400 when it does not compile. REPLACES
                        the whole settings object: start from what **Get a
                        flow** returned and change only the keys you mean to, or
                        the others are lost. Turning a flow into a TOOL
                        (`general.type` `TOOL`) needs a `tenant` and
                        `toolDescription` in the same call. An conversational
                        flow cannot become CONTEXT_ENRICHMENT, and a
                        CONTEXT_ENRICHMENT flow must keep `general.type`
                        `CONTEXT_ENRICHMENT` whenever settings are sent.
                    theme:
                      type: object
                      additionalProperties: true
                      description: >-
                        The flow's visual theme. REPLACES the stored theme when
                        sent.
                    selectedThemeTemplateId:
                      type: string
                      nullable: true
                      description: >-
                        The id of the theme template applied to the flow. Null
                        for none.
                    publicId:
                      type: string
                      nullable: true
                      description: >-
                        The slug of the flow's public URL, lowercase letters,
                        digits and hyphens. Already taken answers 400; on update
                        at least 4 characters. Send `null` to clear it.
                        Publishing a flow without one generates it.
                    customDomain:
                      type: string
                      nullable: true
                      description: >-
                        A custom domain for the flow's public URL. One that is
                        already in use answers 400. Rarely needed.
                    tenant:
                      type: string
                      nullable: true
                      description: >-
                        The Claudia tenant that owns a TOOL. Send it only to
                        move a tool to another tenant, or together with
                        `toolDescription` and `settings` when you turn a flow
                        into a TOOL; a TOOL cannot have it emptied (400). The
                        tool's tenant before and the one you end up with must
                        both be granted. For a TOOL it must be a tenant your
                        token grants, otherwise 403; flows that are not tools
                        are not checked. It is the tenant of one of your Claudia
                        projects.
                    toolDescription:
                      type: string
                      nullable: true
                      description: >-
                        What an agent is told the tool does and when to use it.
                        Send it only to change it; a TOOL cannot have it emptied
                        (400). Write it for the agent that will read it: what
                        the tool does, when to call it, what it returns.
                    isClosed:
                      type: boolean
                      description: True stops the flow from accepting new conversations.
                    isArchived:
                      type: boolean
                      description: >-
                        True archives the flow. A TOOL cannot be archived:
                        sending true for one answers 400.
                    updatedAt:
                      type: string
                      format: date-time
                      description: >-
                        The `updatedAt` of the flow as you last read it (**Get a
                        flow**, or the answer of your previous update).
                        REQUIRED: without it the call answers 400. When the flow
                        changed since, the call answers 409 and nothing is
                        saved, instead of overwriting someone else's edit. After
                        a 409, read the flow again with **Get a flow**, redo
                        your change on top of it and resend.
      responses:
        '200':
          description: The flow after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowSaved'
        '400':
          description: >-
            The change was refused and nothing was saved. `message` says why:
            `updatedAt` missing, a tool renamed or archived, tenant or tool
            description emptied, a tool name already used in the target tenant,
            a public id or domain already taken, an invalid output schema, an
            inconsistent graph or a script or Set variable code that failed the
            lint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, expired or invalid credentials.
        '403':
          description: >-
            The tenant the flow has before the change (if it is a TOOL) or the
            one it ends up with is not one your token grants. Nothing was saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            No such resource, or none your token can reach — the two are
            deliberately indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            The flow changed since the `updatedAt` you sent. Nothing was saved:
            read the flow again with **Get a flow**, redo your change on top of
            it and resend.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit applied by the API gateway. Back off and retry.
components:
  schemas:
    FlowSaved:
      type: object
      required:
        - typebot
      properties:
        typebot:
          $ref: '#/components/schemas/Flow'
      description: >-
        A flow as stored after a write. Its `updatedAt` is the value to send as
        `typebot.updatedAt` on the next **Update a flow** and as
        `expectedUpdatedAt` on **Publish a flow**.
    Error:
      type: object
      properties:
        message:
          type: string
          description: What went wrong.
        code:
          type: string
          description: Error code, e.g. `NOT_FOUND` or `BAD_REQUEST`.
        issues:
          type: array
          description: Per-field validation problems, present on a 400 for invalid input.
          items:
            type: object
            additionalProperties: true
      required:
        - message
        - code
      description: Something the caller needs to fix.
    Flow:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: The flow's internal id.
        name:
          type: string
          description: The flow's name.
        version:
          type: string
          description: 'The flow schema version: `3`, `4`, `5` or `6`.'
        icon:
          nullable: true
          type: string
          description: An emoji or image URL shown next to the flow name.
        folderId:
          nullable: true
          type: string
          description: The folder the flow sits in. Null when it is outside any folder.
        workspaceId:
          type: string
          description: The workspace the flow belongs to.
        publicId:
          nullable: true
          type: string
          description: >-
            The slug in the flow's public URL. Null until one is set. It is NOT
            the internal `id`.
        tenant:
          nullable: true
          type: string
          description: >-
            For a TOOL flow, the Claudia tenant that owns the tool. Null or
            absent for flows that are not tools.
        toolDescription:
          nullable: true
          type: string
          description: >-
            For a TOOL flow, what an agent is told the tool does and when to use
            it. Null or absent for flows that are not tools.
        createdAt:
          type: string
          format: date-time
          description: When the flow was created.
        updatedAt:
          type: string
          format: date-time
          description: When the flow was last changed.
        isArchived:
          type: boolean
          description: True when the flow was archived.
        isClosed:
          type: boolean
          description: True when the flow stopped accepting new conversations.
        groups:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The flow's groups, each with its `id`, `title` and ordered `blocks`.
            A TOOL's inputs live in a block of type `Declare variables`.
        edges:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The connections between groups and blocks: each has an `id`, a
            `from` and a `to` pointing at group and block ids.
        events:
          nullable: true
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The flow's start event(s). Null on flows saved with an older schema
            version.
        variables:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The variables the flow declares, each with an `id` and `name`, and
            `isInputVariable` true when it is a tool input declared in a
            `Declare variables` block.
        settings:
          type: object
          additionalProperties: true
          description: >-
            The flow's settings. `general.type` is `default`, `TOOL` or
            `CONTEXT_ENRICHMENT`. For a TOOL, `tool.outputSchema` is a JSON
            Schema (root `type` `object`) that every answer of the tool must
            satisfy; it is absent when the tool answers with untyped text.
      description: A flow with its full definition.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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