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

# Get Agent

> Returns a single V2 chat agent by id, including its attached skills, triggers, and configuration.



## OpenAPI

````yaml GET /v1/agents/{id}
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/{id}:
    get:
      tags:
        - agents
      summary: Get agent by id
      description: Returns a single V2 chat agent by id.
      operationId: getAgent
      parameters:
        - schema:
            type: string
            description: Agent id.
            example: ag77c0dy0mgdpzmqz6tesry8w184002s
          required: true
          name: id
          in: path
        - schema:
            type: string
            description: >-
              Optional workspace override. If omitted, Conduit resolves the
              agent's workspace automatically.
            example: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
          required: false
          name: workspace_id
          in: query
      responses:
        '200':
          description: Agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    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
                required:
                  - data
                description: Single V2 chat agent 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'
        '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
        '404':
          description: Not found
          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.

````