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

# Publish a flow

> Publishes the flow's current **draft**. The published version is what agents and customers run, so this is the call that makes a flow, or a tool, live.

Send `expectedUpdatedAt`, the `updatedAt` you last read, so the publish is refused with `409` when someone changed the draft since, instead of publishing a version you never saw.

<Note>Call **Validate a flow** first. Publishing runs every check except the branch checks, so it would accept a conversational flow with a branch that never reaches a Claudia block.</Note>

- Publishing a tool needs its tenant to be one your token grants (`403` otherwise).
- Graph consistency, the script lint, `settings.tool.outputSchema` and the declared inputs are checked; only lint problems that are new since the published version count. A failure is a `400` that lists what to fix.
- A flow held by the fraud check is a `403` with a message saying so.
- Publishing an unchanged draft succeeds with `historyCreated` `false` and records nothing.

Every publish records a version that **Restore a flow version** can return to.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json post /v1/typebots/{flowId}/publish
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}/publish:
    post:
      tags:
        - Flows
      summary: Publish a flow
      description: >-
        Publishes the flow's current **draft**. The published version is what
        agents and customers run, so this is the call that makes a flow, or a
        tool, live.


        Send `expectedUpdatedAt`, the `updatedAt` you last read, so the publish
        is refused with `409` when someone changed the draft since, instead of
        publishing a version you never saw.


        <Note>Call **Validate a flow** first. Publishing runs every check except
        the branch checks, so it would accept a conversational flow with a
        branch that never reaches a Claudia block.</Note>


        - Publishing a tool needs its tenant to be one your token grants (`403`
        otherwise).

        - Graph consistency, the script lint, `settings.tool.outputSchema` and
        the declared inputs are checked; only lint problems that are new since
        the published version count. A failure is a `400` that lists what to
        fix.

        - A flow held by the fraud check is a `403` with a message saying so.

        - Publishing an unchanged draft succeeds with `historyCreated` `false`
        and records nothing.


        Every publish records a version that **Restore a flow version** can
        return to.
      operationId: publishFlow
      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
              description: Optional guard against publishing a draft you have not seen.
              properties:
                expectedUpdatedAt:
                  type: string
                  format: date-time
                  description: >-
                    The `updatedAt` of the draft as you last read it: from **Get
                    a flow**, the answer of **Update a flow**, or the
                    `updatedAt` of your previous publish. When the draft changed
                    since, the publish answers 409 before anything is written.
                    Always send it.
      responses:
        '200':
          description: The draft is published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishResult'
        '400':
          description: >-
            The draft was not published. `message` lists what to fix: an
            inconsistent graph, a script or Set variable code that failed the
            lint, Output blocks that do not satisfy the output schema, invalid
            declared inputs, or a file-upload block on a free plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, expired or invalid credentials.
        '403':
          description: >-
            The flow's tenant is not one your token grants, or the fraud check
            flagged the flow (the message says which). Nothing was published.
          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 draft changed since the `expectedUpdatedAt` you sent. Nothing
            was published: read the flow again with **Get a flow**, check it,
            and publish again with the new `updatedAt`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit applied by the API gateway. Back off and retry.
components:
  schemas:
    PublishResult:
      type: object
      required:
        - message
        - historyCreated
        - updatedAt
      properties:
        message:
          type: string
          description: Always `success` when the call answers 200.
        historyCreated:
          type: boolean
          description: >-
            Whether this call stored a new history snapshot. False when the
            draft already matched what was published and the last snapshot
            (nothing new to record), or when the history already held this exact
            snapshot. Either way the published version is current.
        updatedAt:
          type: string
          description: >-
            ISO date of the draft's `updatedAt` at the end of the call. Send
            this value, not the one read before, as `expectedUpdatedAt` on the
            next publish.
      description: The outcome of a publish.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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