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

# Validate a flow

> Checks the current **draft** by the same rules the builder applies before publishing, and returns `{ isValid, errors }`. It only reads: nothing is changed or published.

Call it before **Publish a flow** and publish only when `isValid` is `true`. Publishing does not run the branch checks below, so a conversational flow with a branch that never reaches a Claudia block would publish and leave customers stuck.

What it checks:

- In a conversational flow (`settings.general.type` `default` or absent), every branch reaches a Claudia block, and a Claudia block has text alongside it.
- In a `TOOL` or `CONTEXT_ENRICHMENT` flow, every branch ends in a Tool Output block.
- Input blocks have text between them, Condition blocks are complete, flow link blocks point at a flow that exists, and HTTP Request blocks point at an existing credential.
- Edges and references point at groups and blocks that exist.
- A tool's scripts are linted, its Output blocks satisfy `settings.tool.outputSchema`, and its declared inputs have a valid `pattern` and `format`.

Branch checks are skipped for a secondary flow. Each error has a `type`, the `groupId` it concerns when there is one, a `message` and a `severity`. `error` (also when `severity` is absent) blocks publishing and makes `isValid` false; `warning` does not.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json get /v1/typebots/{flowId}/validate
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}/validate:
    get:
      tags:
        - Flows
      summary: Validate a flow
      description: >-
        Checks the current **draft** by the same rules the builder applies
        before publishing, and returns `{ isValid, errors }`. It only reads:
        nothing is changed or published.


        Call it before **Publish a flow** and publish only when `isValid` is
        `true`. Publishing does not run the branch checks below, so a
        conversational flow with a branch that never reaches a Claudia block
        would publish and leave customers stuck.


        What it checks:


        - In a conversational flow (`settings.general.type` `default` or
        absent), every branch reaches a Claudia block, and a Claudia block has
        text alongside it.

        - In a `TOOL` or `CONTEXT_ENRICHMENT` flow, every branch ends in a Tool
        Output block.

        - Input blocks have text between them, Condition blocks are complete,
        flow link blocks point at a flow that exists, and HTTP Request blocks
        point at an existing credential.

        - Edges and references point at groups and blocks that exist.

        - A tool's scripts are linted, its Output blocks satisfy
        `settings.tool.outputSchema`, and its declared inputs have a valid
        `pattern` and `format`.


        Branch checks are skipped for a secondary flow. Each error has a `type`,
        the `groupId` it concerns when there is one, a `message` and a
        `severity`. `error` (also when `severity` is absent) blocks publishing
        and makes `isValid` false; `warning` does not.
      operationId: validateFlow
      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 reach answers 404,
            indistinguishable from one that does not exist.
          schema:
            type: string
      responses:
        '200':
          description: >-
            The verdict on the current draft. Publish only when `isValid` is
            true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowValidation'
        '401':
          description: Missing, expired or invalid credentials.
        '404':
          description: >-
            No such resource, or none your token can reach — the two are
            deliberately indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit applied by the API gateway. Back off and retry.
components:
  schemas:
    FlowValidation:
      type: object
      required:
        - isValid
        - errors
      properties:
        isValid:
          type: boolean
          description: >-
            True when no item of `errors` has severity `error`. Warnings do not
            make it false.
        errors:
          type: array
          description: >-
            Everything the validation found, errors and warnings. Empty when the
            draft is clean.
          items:
            type: object
            required:
              - type
            properties:
              type:
                type: string
                enum:
                  - conditionalBlocks
                  - missingTextBeforeClaudia
                  - brokenLinks
                  - missingTextBetweenInputBlocks
                  - missingClaudiaInFlowBranches
                  - missingWorkflowEndInFlowBranches
                  - missingCredential
                  - deprecatedCredential
                  - danglingEdgeTarget
                  - staleEdgeReference
                  - scriptLint
                  - toolOutputSchema
                  - toolInputSchema
                description: >-
                  What kind of problem it is. `missingClaudiaInFlowBranches` is
                  a controlled-flow branch that never reaches a Claudia block;
                  `missingWorkflowEndInFlowBranches` is a TOOL or
                  CONTEXT_ENRICHMENT branch that never ends in a Tool Output
                  block.
              groupId:
                type: string
                description: >-
                  The group the problem is in, when it concerns one. Match it
                  with `groups[].id` from **Get a flow**.
              severity:
                type: string
                enum:
                  - error
                  - warning
                description: >-
                  `error` blocks publishing; `warning` does not. Absent means
                  `error`.
              message:
                type: string
                description: >-
                  A short description that names the group, e.g. `Welcome -
                  Missing Claudia block in flow branches`.
      description: The verdict of validating a flow's current draft.
    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.