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

# List Agents

> Returns cursor-paginated V2 chat agents for a workspace, including their attached skills and triggers.



## OpenAPI

````yaml GET /v1/agents
openapi: 3.0.0
info:
  title: Conduit API
  version: 1.0.0
  description: Public API for Conduit.
servers:
  - url: https://api.conduit.ai
    description: Production
security: []
tags:
  - name: meta
    description: Discovery and API metadata endpoints.
  - name: agents
    description: >-
      V2 chat agent configuration, including instructions, skills, triggers, and
      automation behavior.
  - name: contacts
    description: >-
      Contact profile and contact-scoped related resources such as tickets and
      calls.
  - name: workspaces
    description: Workspaces accessible to the current API token.
  - name: escalations
    description: >-
      Chat escalations that require operator review, including message, proposed
      response, and disposition context when available.
  - name: conversations
    description: >-
      Canonical message threads. Use these endpoints to list threads, inspect
      conversation state, read transcripts, and send replies.
  - name: conversation-tags
    description: >-
      Conversation labels, root topics, and subtopics used for classification
      and topic analytics.
  - name: tickets
    description: >-
      Operational queue items tied to conversations, including ticket-scoped
      transcripts and replies.
  - name: calls
    description: Phone call records, transcripts, summaries, and recordings when available.
  - name: reservations
    description: >-
      PMS reservations synced from the workspace's integrations (Hostaway,
      Guesty, Airbnb, etc.), including guest identity, payment status, and stay
      dates.
  - name: appointments
    description: >-
      Scheduled appointments (bookings) backed by the Conduit booking service.
      Exposes allocation context and the upstream booking-service `external_id`.
  - name: helpdesk_tickets
    description: >-
      Helpdesk tickets mirrored from external helpdesk integrations (Zendesk,
      Pylon, Plain), including requester identity and upstream metadata.
  - name: kb
    description: >-
      Knowledge base search and node management. Nodes represent knowledge base
      entries (files or directories), chunks are the indexed retrieval units
      used by search.
  - name: skills
    description: >-
      Workspace agent skills that can be attached to V2 chat agents.
      Sidebar/global-assistant skills are intentionally excluded.
  - name: custom_tools
    description: >-
      Custom code tools: user-authored Python/JavaScript functions executed in a
      sandbox when an agent calls them. Includes a runtimes endpoint describing
      the entrypoint signature, return shape, and available dependencies per
      language.
  - name: inbox_types
    description: >-
      Workspace inbox types. Each id is stable and usable as a message trigger's
      `inboxTypeId` and as the `inbox_type_id` filter on list conversations.
  - name: workflows
    description: >-
      Workspace automation workflows: definitions, executions, and per-execution
      event timelines.
  - name: insights
    description: Aggregated workspace analytics, such as conversation automation rate.
paths:
  /v1/agents:
    get:
      tags:
        - agents
      summary: List V2 chat agents
      description: >-
        Returns cursor-paginated V2 chat agents for a workspace, including their
        attached skills and triggers.
      operationId: listAgents
      parameters:
        - schema:
            type: string
            description: Workspace to query.
            example: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
          required: true
          name: workspace_id
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: V2 chat agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        workspace_id:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                          nullable: true
                        color:
                          type: string
                          nullable: true
                        icon_id:
                          type: number
                          nullable: true
                        version:
                          type: string
                          enum:
                            - v2
                        instructions:
                          type: string
                          nullable: true
                        model:
                          type: string
                          description: >-
                            The LLM this agent runs on: a kb_api `model_string`
                            (e.g. `openai:gpt-4o`), or `default` when no
                            override is set.
                        guardrails:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              title:
                                type: string
                              knowledge:
                                type: string
                            required:
                              - title
                              - knowledge
                        operation_mode:
                          type: string
                          enum:
                            - autopilot
                            - copilot
                            - inactive
                        autopilot_schedule:
                          type: object
                          nullable: true
                          properties:
                            timezone:
                              type: string
                              description: >-
                                IANA timezone the schedule is evaluated in, e.g.
                                "America/New_York".
                            days:
                              type: array
                              items:
                                type: object
                                properties:
                                  day:
                                    type: string
                                    enum:
                                      - sunday
                                      - monday
                                      - tuesday
                                      - wednesday
                                      - thursday
                                      - friday
                                      - saturday
                                    description: Day of the week this window applies to.
                                  enabled:
                                    type: boolean
                                    description: Whether autopilot is active on this day.
                                  ranges:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        start:
                                          type: string
                                          description: >-
                                            Window start as a 12-hour clock time,
                                            e.g. "09:00 AM".
                                        end:
                                          type: string
                                          description: >-
                                            Window end as a 12-hour clock time, e.g.
                                            "05:00 PM".
                                      required:
                                        - start
                                        - end
                                    description: >-
                                      Time windows during which autopilot is
                                      active on this day.
                                required:
                                  - day
                                  - enabled
                                  - ranges
                              description: Per-day autopilot windows.
                          required:
                            - timezone
                            - days
                          description: >-
                            Autopilot schedule. Autopilot only sends inside the
                            enabled day windows; outside them the agent falls
                            back to copilot. Omit or set null for always-on
                            autopilot.
                        custom_response_delay_ms:
                          type: number
                        auto_mark_as_done:
                          type: boolean
                        response_language:
                          type: string
                          nullable: true
                          enum:
                            - English
                            - Original
                            - Spanish
                            - French
                            - German
                            - Italian
                            - Portuguese
                        responseflow:
                          type: boolean
                        output_schema:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              description:
                                type: string
                              type:
                                type: string
                              is_required:
                                type: boolean
                            required:
                              - name
                              - type
                        skill_ids:
                          type: array
                          items:
                            type: string
                        connection_ids:
                          type: array
                          items:
                            type: string
                          description: >-
                            Ids of the integration connections linked to this
                            agent. Use list_agent_connections (GET
                            /v1/agents/{id}/connections) for the full connection
                            details and their tools.
                        enabled:
                          type: boolean
                        triggers:
                          type: array
                          items:
                            oneOf:
                              - type: object
                                properties:
                                  id:
                                    type: string
                                  workspace_id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                    nullable: true
                                  type:
                                    type: string
                                    enum:
                                      - message
                                  config:
                                    oneOf:
                                      - type: object
                                        properties:
                                          scopeType:
                                            type: string
                                            enum:
                                              - all
                                        required:
                                          - scopeType
                                        additionalProperties: false
                                      - type: object
                                        properties:
                                          scopeType:
                                            type: string
                                            enum:
                                              - inbox
                                          inboxTypeId:
                                            type: string
                                        required:
                                          - scopeType
                                          - inboxTypeId
                                        additionalProperties: false
                                      - type: object
                                        properties:
                                          scopeType:
                                            type: string
                                            enum:
                                              - channel
                                          channelType:
                                            type: string
                                            enum:
                                              - airbnb
                                              - booking_com
                                              - sms
                                              - whatsapp
                                              - messenger
                                              - email
                                              - unthreaded_email
                                              - pms
                                              - widget
                                              - instagram
                                              - vrbo
                                              - expedia
                                              - helpdesk
                                              - slack
                                              - line_oa
                                              - portal
                                        required:
                                          - scopeType
                                          - channelType
                                        additionalProperties: false
                                      - nullable: true
                                  enabled:
                                    type: boolean
                                  created_at:
                                    type: string
                                  updated_at:
                                    type: string
                                required:
                                  - id
                                  - workspace_id
                                  - name
                                  - description
                                  - type
                                  - config
                                  - enabled
                                  - created_at
                                  - updated_at
                              - type: object
                                properties:
                                  id:
                                    type: string
                                  workspace_id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                    nullable: true
                                  type:
                                    type: string
                                    enum:
                                      - webhook
                                  config:
                                    nullable: true
                                  enabled:
                                    type: boolean
                                  created_at:
                                    type: string
                                  updated_at:
                                    type: string
                                required:
                                  - id
                                  - workspace_id
                                  - name
                                  - description
                                  - type
                                  - enabled
                                  - created_at
                                  - updated_at
                              - type: object
                                properties:
                                  id:
                                    type: string
                                  workspace_id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                    nullable: true
                                  type:
                                    type: string
                                    enum:
                                      - cron
                                  config:
                                    nullable: true
                                  enabled:
                                    type: boolean
                                  created_at:
                                    type: string
                                  updated_at:
                                    type: string
                                required:
                                  - id
                                  - workspace_id
                                  - name
                                  - description
                                  - type
                                  - enabled
                                  - created_at
                                  - updated_at
                              - type: object
                                properties:
                                  id:
                                    type: string
                                  workspace_id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                    nullable: true
                                  type:
                                    type: string
                                    enum:
                                      - event
                                  config:
                                    nullable: true
                                  enabled:
                                    type: boolean
                                  created_at:
                                    type: string
                                  updated_at:
                                    type: string
                                required:
                                  - id
                                  - workspace_id
                                  - name
                                  - description
                                  - type
                                  - enabled
                                  - created_at
                                  - updated_at
                              - type: object
                                properties:
                                  id:
                                    type: string
                                  workspace_id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                    nullable: true
                                  type:
                                    type: string
                                    enum:
                                      - mention
                                  config:
                                    oneOf:
                                      - type: object
                                        properties:
                                          tool:
                                            type: string
                                            enum:
                                              - slack
                                          slackTeamId:
                                            type: string
                                            minLength: 1
                                          slackChannelId:
                                            type: string
                                            minLength: 1
                                        required:
                                          - tool
                                        additionalProperties: false
                                      - type: object
                                        properties:
                                          tool:
                                            type: string
                                            enum:
                                              - linear
                                          linearTeamId:
                                            type: string
                                            minLength: 1
                                        required:
                                          - tool
                                        additionalProperties: false
                                      - type: object
                                        properties:
                                          tool:
                                            type: string
                                            enum:
                                              - microsoft_teams
                                          tenantId:
                                            type: string
                                            minLength: 1
                                          teamId:
                                            type: string
                                            minLength: 1
                                          channelId:
                                            type: string
                                            minLength: 1
                                        required:
                                          - tool
                                        additionalProperties: false
                                  enabled:
                                    type: boolean
                                  created_at:
                                    type: string
                                  updated_at:
                                    type: string
                                required:
                                  - id
                                  - workspace_id
                                  - name
                                  - description
                                  - type
                                  - config
                                  - enabled
                                  - created_at
                                  - updated_at
                              - type: object
                                properties:
                                  id:
                                    type: string
                                  workspace_id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                    nullable: true
                                  type:
                                    type: string
                                    enum:
                                      - manual
                                  config:
                                    nullable: true
                                  enabled:
                                    type: boolean
                                  created_at:
                                    type: string
                                  updated_at:
                                    type: string
                                required:
                                  - id
                                  - workspace_id
                                  - name
                                  - description
                                  - type
                                  - enabled
                                  - created_at
                                  - updated_at
                        created_at:
                          type: string
                        updated_at:
                          type: string
                      required:
                        - id
                        - workspace_id
                        - name
                        - description
                        - color
                        - icon_id
                        - version
                        - instructions
                        - model
                        - guardrails
                        - operation_mode
                        - autopilot_schedule
                        - custom_response_delay_ms
                        - auto_mark_as_done
                        - response_language
                        - responseflow
                        - output_schema
                        - skill_ids
                        - connection_ids
                        - enabled
                        - triggers
                        - created_at
                        - updated_at
                  next_cursor:
                    type: string
                    nullable: true
                  has_more:
                    type: boolean
                required:
                  - data
                  - next_cursor
                  - has_more
                description: Cursor-paginated V2 chat agents response.
                example:
                  data:
                    - id: ag77c0dy0mgdpzmqz6tesry8w184002s
                      workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
                      name: Reservations
                      description: Handles booking and cancellation flows.
                      color: '#2563EB'
                      icon_id: 12
                      version: v2
                      instructions: >-
                        Answer booking questions, use policies before
                        escalating, and keep replies concise.
                      model: default
                      guardrails:
                        - id: guardrail_1
                          title: Do not promise refunds
                          knowledge: >-
                            Only cite refund terms from approved policy docs or
                            escalate.
                      operation_mode: autopilot
                      autopilot_schedule: null
                      custom_response_delay_ms: 10000
                      auto_mark_as_done: false
                      response_language: English
                      responseflow: true
                      output_schema:
                        - name: resolution
                          description: Short summary of the final outcome.
                          type: string
                          is_required: true
                      skill_ids:
                        - ks77c0dy0mgdpzmqz6tesry8w184002s
                      connection_ids:
                        - cn77c0dy0mgdpzmqz6tesry8w184002s
                      enabled: true
                      triggers:
                        - id: tr77c0dy0mgdpzmqz6tesry8w184002s
                          workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
                          name: All Messages
                          description: Runs for every inbound message.
                          type: message
                          config:
                            scopeType: all
                          enabled: true
                          created_at: '2026-04-01T17:22:10.000Z'
                          updated_at: '2026-04-03T03:14:15.000Z'
                        - id: tr88c0dy0mgdpzmqz6tesry8w184003s
                          workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
                          name: Contact Inbox
                          description: Runs only for contact-type inbox messages.
                          type: message
                          config:
                            scopeType: inbox
                            inboxTypeId: guest
                          enabled: true
                          created_at: '2026-04-01T17:22:10.000Z'
                          updated_at: '2026-04-03T03:14:15.000Z'
                        - id: tr99c0dy0mgdpzmqz6tesry8w184004s
                          workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
                          name: SMS Channel
                          description: Runs only for SMS channel messages.
                          type: message
                          config:
                            scopeType: channel
                            channelType: sms
                          enabled: true
                          created_at: '2026-04-01T17:22:10.000Z'
                          updated_at: '2026-04-03T03:14:15.000Z'
                      created_at: '2026-04-01T17:22:10.000Z'
                      updated_at: '2026-04-03T03:14:15.000Z'
                  next_cursor: page-token
                  has_more: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: >-
        Conduit API token. Use `Authorization: Bearer <token>`. Read/write
        endpoints require a token with write access.

````