> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List workflows

> Retrieve all workflows for your project. Workflows are returned ordered by creation time (newest first). Use query parameters to filter by status, name, or creation date.

Common use cases:
- List all active workflows ready for execution
- Find workflows by partial name match
- Audit workflow creation over time




## OpenAPI

````yaml /api/platform/v1/openapi-workflows.yaml get /workflows
openapi: 3.1.0
info:
  title: Kapso Platform API – Advanced Resources
  version: 0.1.0
  description: >
    Build WhatsApp automation workflows and serverless functions. Create
    multi-step conversation flows, inspect executions, and deploy custom logic.
servers:
  - url: https://api.kapso.ai/platform/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Workflows
    description: Create and manage conversation workflows and executions
  - name: Workflow Triggers
    description: Configure workflow triggers to automate execution
  - name: Functions
    description: Manage serverless functions, deployments, and secrets
  - name: WhatsApp Conversations
    description: Query WhatsApp conversation data and related resources
paths:
  /workflows:
    get:
      tags:
        - Workflows
      summary: List workflows
      description: >
        Retrieve all workflows for your project. Workflows are returned ordered
        by creation time (newest first). Use query parameters to filter by
        status, name, or creation date.


        Common use cases:

        - List all active workflows ready for execution

        - Find workflows by partial name match

        - Audit workflow creation over time
      operationId: listWorkflows
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - draft
              - active
              - archived
          description: Filter by workflow status (draft, active, or archived)
        - name: name_contains
          in: query
          schema:
            type: string
          description: Case-insensitive substring search on workflow name
          example: onboarding
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
          description: Only return workflows created on or after this timestamp
        - name: created_before
          in: query
          schema:
            type: string
            format: date-time
          description: Only return workflows created on or before this timestamp
      responses:
        '200':
          description: Workflows retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    WorkflowListResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
      description: List of workflows for the project
    Workflow:
      type: object
      required:
        - id
        - name
        - slug
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique workflow identifier
        name:
          type: string
          description: Workflow name (unique per project)
        slug:
          type: string
          description: >
            URL-safe workflow identifier (lowercase alphanumeric with hyphens).
            Stable across renames — useful as an external sync key.
            Auto-generated from `name` on create if not provided. Unique within
            the project.
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          example: inbound-support
        description:
          type:
            - string
            - 'null'
          description: Optional workflow description
        status:
          type: string
          enum:
            - draft
            - active
            - archived
          description: |
            Workflow lifecycle status:
            - `draft`: Under development, not executable
            - `active`: Published and executable
            - `archived`: Inactive, no longer in use
        lock_version:
          type:
            - integer
            - 'null'
          description: >
            Optimistic locking version. Increment on each update to prevent
            concurrent modification conflicts. Include this value when updating
            to ensure you're working with the latest version.
        message_debounce_seconds:
          type:
            - integer
            - 'null'
          description: >
            Debounce window for incoming messages in seconds (default: 1). When
            a user sends multiple messages rapidly, the workflow waits this
            duration before processing to batch messages together. Prevents
            workflow from reacting to every keystroke.
        agent_default_tools_version:
          type:
            - integer
            - 'null'
          description: >-
            Version used to decide which built-in agent tools are required by
            default for this workflow.
        inbound_message_read_mode:
          type: string
          enum:
            - disabled
            - read_only
            - read_with_typing
          description: >
            Controls how inbound WhatsApp messages are marked as read before the
            workflow responds (default: read_with_typing).

            - `disabled`: Do nothing — messages are not marked as read

            - `read_only`: Mark messages as read without showing a typing
            indicator

            - `read_with_typing`: Mark as read and show a typing indicator
            before responding
        created_at:
          type: string
          format: date-time
          description: Workflow creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last modification timestamp
        project_id:
          type: string
          format: uuid
          description: Project this workflow belongs to
        execution_count:
          type: integer
          minimum: 0
          description: Total number of times this workflow has been executed
        last_executed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of most recent execution, null if never executed
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
  responses:
    UnauthorizedError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````