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

# List or get agents

> List agents, or pass `id` for one with its configuration, inbound settings, channels,
knowledge bases and tools.



## OpenAPI

````yaml /openapi.json get /api/v1/public/agents
openapi: 3.1.0
info:
  description: >-
    Customer-facing API for managing outreach, leads, conversations, voice
    agents, knowledge bases, analytics, and webhooks.
  title: Sendora Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.sendora.ai
security: []
tags:
  - description: Leads, lead lists, importing, enriching and finding new prospects.
    name: Leads
  - description: Build, run and measure outreach, and enroll leads.
    name: Campaigns
  - description: Read and send messages, and manage who must not be contacted.
    name: Conversations
  - description: >-
      Voice and chat agents, their tools, knowledge bases, voices and website
      widgets.
    name: Agents
  - description: >-
      Start calls, and manage phone numbers, SMS registration, sending accounts
      and email domains.
    name: Calls and numbers
  - description: Webhooks, jobs, analytics and the Copilot assistant.
    name: Platform
  - description: Manage client workspaces, plans and branding.
    name: Agency
paths:
  /api/v1/public/agents:
    get:
      tags:
        - Agents
      summary: List or get agents
      description: >-
        List agents, or pass `id` for one with its configuration, inbound
        settings, channels,

        knowledge bases and tools.
      operationId: list_or_get_agents_api_v1_public_agents_get
      parameters:
        - description: Return this one agent with its full configuration.
          in: query
          name: id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Return this one agent with its full configuration.
            title: Id
        - description: Which kind of agent to list.
          in: query
          name: type
          required: false
          schema:
            default: voice
            description: Which kind of agent to list.
            enum:
              - voice
              - chat
            title: Type
            type: string
        - description: >-
            voices adds the voice choices for this agent. templates (without id)
            returns an object with agents and templates, the starting points for
            a new agent.
          in: query
          name: include
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              voices adds the voice choices for this agent. templates (without
              id) returns an object with agents and templates, the starting
              points for a new agent.
            title: Include
        - in: query
          name: page
          required: false
          schema:
            default: 1
            minimum: 1
            title: Page
            type: integer
        - in: query
          name: per_page
          required: false
          schema:
            default: 50
            maximum: 200
            minimum: 1
            title: Per Page
            type: integer
        - in: header
          name: X-API-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
        - in: header
          name: Authorization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                  - items:
                      $ref: '#/components/schemas/PublicVoiceAgentOut'
                    type: array
                  - items:
                      $ref: '#/components/schemas/PublicChatAgentOut'
                    type: array
                  - $ref: '#/components/schemas/VoiceAgentDetail'
                  - $ref: '#/components/schemas/PublicChatAgentOut'
                  - type: object
                title: Response List Or Get Agents Api V1 Public Agents Get
          description: Successful Response
        '401':
          description: The X-API-Key header is missing, invalid, expired, or revoked.
        '402':
          description: >-
            The workspace is suspended for billing, or the request would exceed
            a plan or usage limit.
        '403':
          description: >-
            The key is valid but lacks the required scope, or the workspace has
            no active plan, lacks the entitlement, or has this feature turned
            off or view-only.
        '410':
          description: The workspace behind this key has been deleted.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          description: >-
            An unexpected Sendora error occurred. Retry only if the operation is
            safe to repeat.
        '503':
          description: >-
            An entitlement or billing check is temporarily unavailable. Retry
            after the Retry-After interval.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - label: cURL
          lang: bash
          source: >-
            curl -X GET 'https://api.sendora.ai/api/v1/public/agents' -H
            "X-API-Key: $SENDORA_API_KEY"
        - label: Python
          lang: python
          source: |-
            import requests

            url = 'https://api.sendora.ai/api/v1/public/agents'
            headers = {'X-API-Key': '$SENDORA_API_KEY'}
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            print(response.json())
        - label: JavaScript
          lang: javascript
          source: >-
            const response = await
            fetch("https://api.sendora.ai/api/v1/public/agents", {
              method: "GET",
              headers: { 'X-API-Key': process.env.SENDORA_API_KEY },
            });

            if (!response.ok) throw new Error(await response.text());

            console.log(await response.json());
        - label: Go
          lang: go
          source: >-
            req, err := http.NewRequest("GET",
            "https://api.sendora.ai/api/v1/public/agents", nil)

            if err != nil { log.Fatal(err) }

            req.Header.Set("X-API-Key", os.Getenv("SENDORA_API_KEY"))

            resp, err := http.DefaultClient.Do(req)

            if err != nil { log.Fatal(err) }

            defer resp.Body.Close()
components:
  schemas:
    PublicVoiceAgentOut:
      description: >-
        Deliberately minimal public representation of a voice agent.


        The authenticated operator API returns the full configuration, but
        public

        API keys must not receive system prompts, tool definitions, tenant IDs,
        or

        connected service resource identifiers as an incidental side effect of
        listing an

        agent. Configuration is accepted on write requests but is never echoed.
      properties:
        created_at:
          description: Created at returned by the Sendora API.
          format: date-time
          title: Created At
          type: string
        direction:
          default: outbound
          description: Direction returned by the Sendora API.
          title: Direction
          type: string
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Display name returned by the Sendora API.
          title: Display Name
        first_message:
          default: ''
          description: First message returned by the Sendora API.
          title: First Message
          type: string
        id:
          description: The voice agent's id. Pass it to any endpoint that takes `agent_id`.
          title: Id
          type: string
        is_active:
          default: false
          description: Is active returned by the Sendora API.
          title: Is Active
          type: boolean
        name:
          description: Name returned by the Sendora API.
          title: Name
          type: string
        ready:
          default: false
          description: Ready returned by the Sendora API.
          title: Ready
          type: boolean
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Updated at returned by the Sendora API.
          title: Updated At
      required:
        - id
        - name
        - created_at
      title: PublicVoiceAgentOut
      type: object
    PublicChatAgentOut:
      properties:
        channels:
          description: Channels returned by the Sendora API.
          items:
            $ref: '#/components/schemas/ChatAgentChannelOut'
          title: Channels
          type: array
        conversations_7d:
          default: 0
          description: Conversations with a message in the last 7 days.
          title: Conversations 7D
          type: integer
        id:
          description: Public id of the chat agent.
          title: Id
          type: string
        live:
          description: True when the agent answers on at least one connected channel.
          title: Live
          type: boolean
        name:
          description: Name returned by the Sendora API.
          title: Name
          type: string
      required:
        - id
        - name
        - live
        - channels
      title: PublicChatAgentOut
      type: object
    VoiceAgentDetail:
      properties:
        channels:
          description: Channel assignments, keyed by email, linkedin, whatsapp, phone.
          title: Channels
          type: object
        configuration:
          anyOf:
            - type: object
            - type: 'null'
          description: 'Editable settings: prompt, voice, model, limits.'
          title: Configuration
        created_at:
          description: Created at returned by the Sendora API.
          format: date-time
          title: Created At
          type: string
        direction:
          default: outbound
          description: Direction returned by the Sendora API.
          title: Direction
          type: string
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Display name returned by the Sendora API.
          title: Display Name
        first_message:
          default: ''
          description: First message returned by the Sendora API.
          title: First Message
          type: string
        id:
          description: The voice agent's id. Pass it to any endpoint that takes `agent_id`.
          title: Id
          type: string
        inbound:
          anyOf:
            - type: object
            - type: 'null'
          description: Inbound call settings.
          title: Inbound
        is_active:
          default: false
          description: Is active returned by the Sendora API.
          title: Is Active
          type: boolean
        knowledge_bases:
          anyOf:
            - items:
                type: object
              type: array
            - type: 'null'
          description: Knowledge bases returned by the Sendora API.
          title: Knowledge Bases
        name:
          description: Name returned by the Sendora API.
          title: Name
          type: string
        ready:
          default: false
          description: Ready returned by the Sendora API.
          title: Ready
          type: boolean
        tools:
          anyOf:
            - items:
                type: object
              type: array
            - type: 'null'
          description: Tools returned by the Sendora API.
          title: Tools
        type:
          default: voice
          description: Type returned by the Sendora API.
          title: Type
          type: string
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Updated at returned by the Sendora API.
          title: Updated At
        voices:
          anyOf:
            - items:
                type: object
              type: array
            - type: 'null'
          description: Present with include=voices.
          title: Voices
      required:
        - id
        - name
        - created_at
      title: VoiceAgentDetail
      type: object
    HTTPValidationError:
      properties:
        detail:
          description: Detail returned by the Sendora API.
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      required: []
      title: HTTPValidationError
      type: object
    ChatAgentChannelOut:
      properties:
        channel:
          description: Channel returned by the Sendora API.
          enum:
            - sms
            - whatsapp
            - email
          title: Channel
          type: string
        connected:
          description: >-
            Whether a number or mailbox is assigned to the agent for this
            channel.
          title: Connected
          type: boolean
        enabled:
          description: Whether the agent answers on this channel right now.
          title: Enabled
          type: boolean
        mode:
          description: >-
            `auto` replies right away; `draft` writes a draft for a person to
            approve.
          title: Mode
          type: string
      required:
        - channel
        - enabled
        - connected
        - mode
      title: ChatAgentChannelOut
      type: object
    ValidationError:
      properties:
        loc:
          description: Loc returned by the Sendora API.
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          description: Msg returned by the Sendora API.
          title: Message
          type: string
        type:
          description: Type returned by the Sendora API.
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Customer API key created in the Sendora dashboard.
      in: header
      name: X-API-Key
      type: apiKey

````

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