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

# List flows

> Lists the flows of one workspace, newest first, without their content: the `id`, name, icon, creation date, published state and `type` of each.

The response is not paginated. Narrow it with `search`, `status`, `type`, `folderId` or the creation-date range instead of reading everything; `type=TOOL` lists only the tools.

- `type` is `default` for a conversational flow, `TOOL` for a tool that agents call (it takes inputs and returns an output) and `CONTEXT_ENRICHMENT` for a flow that enriches a conversation's context. `isTool` is `true` only for `TOOL`.
- `publishedTypebotId` is present only while the flow has a published version. A flow without it is a draft that nothing runs yet.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json get /v1/typebots
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:
    get:
      tags:
        - Flows
      summary: List flows
      description: >-
        Lists the flows of one workspace, newest first, without their content:
        the `id`, name, icon, creation date, published state and `type` of each.


        The response is not paginated. Narrow it with `search`, `status`,
        `type`, `folderId` or the creation-date range instead of reading
        everything; `type=TOOL` lists only the tools.


        - `type` is `default` for a conversational flow, `TOOL` for a tool that
        agents call (it takes inputs and returns an output) and
        `CONTEXT_ENRICHMENT` for a flow that enriches a conversation's context.
        `isTool` is `true` only for `TOOL`.

        - `publishedTypebotId` is present only while the flow has a published
        version. A flow without it is a draft that nothing runs yet.
      operationId: listFlows
      parameters:
        - name: workspaceId
          in: query
          required: true
          description: >-
            The workspace to read, e.g. `clx1a2b3c4d5e6f7g8h9`. Get it from
            **List workspaces**, which lists every workspace your token reaches.
            A workspace your token cannot reach answers 404, indistinguishable
            from one that does not exist.
          schema:
            type: string
        - name: folderId
          in: query
          required: false
          description: >-
            Only the flows inside this folder, by folder id. Pass `root` for the
            flows that sit outside any folder. Omit to list flows from every
            folder. Workspace guests always see only the flows shared with them,
            whatever this says.
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Keep only the flows whose name contains this text, ignoring case.
          schema:
            type: string
          example: refund
        - name: status
          in: query
          required: false
          description: >-
            Keep only flows in this state, as a comma-separated list: `active`
            (has a published version) and/or `inactive` (draft only). Omit for
            both.
          schema:
            type: string
          example: active
        - name: type
          in: query
          required: false
          description: >-
            Keep only flows of this type. `TOOL` lists the tools agents can
            call; `default` the ordinary flows. Omit for every type.
          schema:
            type: string
            enum:
              - default
              - TOOL
              - CONTEXT_ENRICHMENT
        - name: excludeTools
          in: query
          required: false
          description: >-
            When `true`, leaves out the `TOOL` and `CONTEXT_ENRICHMENT` flows
            and returns only ordinary ones. Prefer `type` when you know which
            type you want.
          schema:
            type: boolean
        - name: createdAtFrom
          in: query
          required: false
          description: >-
            Keep only flows created at or after this instant, as an ISO 8601 UTC
            timestamp. Must not be later than `createdAtTo`.
          schema:
            type: string
            format: date-time
          example: '2026-01-01T00:00:00.000Z'
        - name: createdAtTo
          in: query
          required: false
          description: >-
            Keep only flows created at or before this instant, as an ISO 8601
            UTC timestamp. Must not be earlier than `createdAtFrom`.
          schema:
            type: string
            format: date-time
          example: '2026-12-31T23:59:59.999Z'
      responses:
        '200':
          description: >-
            The matching flows, newest first. An empty list means the workspace
            has none that match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowSummaryList'
        '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 workspace with this id, 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:
    FlowSummaryList:
      type: object
      required:
        - typebots
      properties:
        typebots:
          type: array
          items:
            $ref: '#/components/schemas/FlowSummary'
          description: The flows that match, newest first.
      description: The flows of a workspace that match the filters.
    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.
    FlowSummary:
      type: object
      required:
        - id
        - name
        - isTool
        - type
      properties:
        id:
          type: string
          description: >-
            The flow's internal id — the `flowId` of **Get a flow** and **List
            flow versions**. Not the `publicId` slug.
        name:
          type: string
          description: The flow's name.
        icon:
          nullable: true
          type: string
          description: An emoji or image URL shown next to the flow name.
        createdAt:
          type: string
          format: date-time
          description: When the flow was created.
        publishedTypebotId:
          type: string
          description: >-
            Id of the flow's published version. Present only while the flow is
            published; absent for a draft.
        isTool:
          type: boolean
          description: >-
            True when the flow is a TOOL that agents can call (`type` is
            `TOOL`).
        type:
          type: string
          description: >-
            The flow type: `default` (conversational flow), `TOOL` (callable by
            agents) or `CONTEXT_ENRICHMENT`.
          enum:
            - default
            - TOOL
            - CONTEXT_ENRICHMENT
      description: A flow listed without its content.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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