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

# Get a flow

> Returns one flow with its whole definition: `groups` (the blocks), `edges` (how groups connect), `events`, `variables` and `settings`. The response can be large, so use it to inspect one flow and **List flows** to survey many.

A flow is a tool when `settings.general.type` is `TOOL`. A tool carries a `tenant` (the Claudia project that owns it) and a `toolDescription` (what an agent is told the tool does). Its inputs are the variables of its `Declare variables` block: each has a `description`, a `required` flag and optionally a `type` (`string`, `number` or `boolean`; `string` when absent), an `enum`, a `pattern` and a `format`. The same variables appear in `variables` with `isInputVariable` set.

`settings.tool.outputSchema`, when present, is a JSON Schema (root `type` `object`) that every answer of the tool must satisfy. `currentUserMode` says what your token can do on the flow: `write`, `read` or `guest`. The flow's `id` is its internal id, not its `publicId` slug.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json get /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}:
    get:
      tags:
        - Flows
      summary: Get a flow
      description: >-
        Returns one flow with its whole definition: `groups` (the blocks),
        `edges` (how groups connect), `events`, `variables` and `settings`. The
        response can be large, so use it to inspect one flow and **List flows**
        to survey many.


        A flow is a tool when `settings.general.type` is `TOOL`. A tool carries
        a `tenant` (the Claudia project that owns it) and a `toolDescription`
        (what an agent is told the tool does). Its inputs are the variables of
        its `Declare variables` block: each has a `description`, a `required`
        flag and optionally a `type` (`string`, `number` or `boolean`; `string`
        when absent), an `enum`, a `pattern` and a `format`. The same variables
        appear in `variables` with `isInputVariable` set.


        `settings.tool.outputSchema`, when present, is a JSON Schema (root
        `type` `object`) that every answer of the tool must satisfy.
        `currentUserMode` says what your token can do on the flow: `write`,
        `read` or `guest`. The flow's `id` is its internal id, not its
        `publicId` slug.
      operationId: getFlow
      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 flow and what your token can do on it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowDetail'
        '400':
          description: >-
            The request could not be answered as written. `message` says which
            input was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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:
    FlowDetail:
      type: object
      required:
        - typebot
      properties:
        typebot:
          $ref: '#/components/schemas/Flow'
        currentUserMode:
          type: string
          description: 'What your token can do on the flow: `write`, `read` or `guest`.'
          enum:
            - guest
            - read
            - write
      description: A flow and the access your token holds on it.
    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.