> ## Documentation Index > Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Returns a paginated list of all agents for the authenticated account. ## OpenAPI ````yaml /api-v2-merged-openapi.json get /agents openapi: 3.1.0 info: title: Chatbase API v2 version: 2.0.0 description: >- Chatbase API v2 - A robust, structured API for managing agents and conversations. servers: - url: https://www.chatbase.co/api/v2 description: Chatbase API v2 security: [] paths: /agents: get: tags: - Agents summary: List agents description: Returns a paginated list of all agents for the authenticated account. parameters: - schema: type: string description: Opaque cursor from a previous response to fetch the next page example: eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ== required: false description: Opaque cursor from a previous response to fetch the next page name: cursor in: query - schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of items per page (1–100, default 20) example: 20 required: false description: Number of items per page (1–100, default 20) name: limit in: query responses: '200': description: Paginated list of agents content: application/json: schema: $ref: '#/components/schemas/ListAgentsResponse' '400': description: >- The request body failed schema validation. Inspect the `details` object in the error response for field-level errors. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: VALIDATION_INVALID_BODY message: Invalid request '401': description: >- No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_MISSING_API_KEY message: Authentication required '403': description: >- Your current plan does not include API access. Upgrade to the Standard plan or higher to use the API. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: SUBSCRIPTION_API_RESTRICTED_PLAN message: A Standard plan or higher is required to access the API '429': description: >- Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMIT_TOO_MANY_REQUESTS message: Too many requests, please try again later '500': description: >- An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL_SERVER_ERROR message: Something went wrong, please try again '503': description: >- Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient — retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: SERVICE_UNDER_MAINTENANCE message: >- The API is temporarily unavailable for scheduled maintenance, please try again later security: - bearerAuth: [] components: schemas: ListAgentsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/Agent' pagination: type: object properties: cursor: type: - string - 'null' description: Cursor for the next page, or null if no more pages hasMore: type: boolean description: Whether more results are available total: type: number description: Total number of items matching the query required: - cursor - hasMore - total required: - data - pagination ErrorResponse: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message details: type: object additionalProperties: type: string description: Field-level validation errors required: - code - message required: - error Agent: type: object properties: id: type: string description: Agent ID example: 5QHA6VB-DIAbBhxwqxfdi name: type: string description: Agent name example: Support Bot instructions: type: string description: System prompt / instructions for the agent channelInstructions: type: - object - 'null' properties: chat_widget: anyOf: - type: string - type: object properties: chat: type: string voice: type: string help_page: anyOf: - type: string - type: object properties: chat: type: string voice: type: string center_stage: anyOf: - type: string - type: object properties: chat: type: string voice: type: string side_panel: anyOf: - type: string - type: object properties: chat: type: string voice: type: string slack: anyOf: - type: string - type: object properties: chat: type: string voice: type: string whatsapp: anyOf: - type: string - type: object properties: chat: type: string voice: type: string messenger: anyOf: - type: string - type: object properties: chat: type: string voice: type: string instagram: anyOf: - type: string - type: object properties: chat: type: string voice: type: string salesforce: anyOf: - type: string - type: object properties: chat: type: string voice: type: string zendesk: anyOf: - type: string - type: object properties: chat: type: string voice: type: string zendesk_messaging: anyOf: - type: string - type: object properties: chat: type: string voice: type: string api: anyOf: - type: string - type: object properties: chat: type: string voice: type: string email: anyOf: - type: string - type: object properties: chat: type: string voice: type: string android_sdk: anyOf: - type: string - type: object properties: chat: type: string voice: type: string ios_sdk: anyOf: - type: string - type: object properties: chat: type: string voice: type: string phone: anyOf: - type: string - type: object properties: chat: type: string voice: type: string description: Per-channel instruction overrides model: type: string enum: - gpt-4o - gpt-4o-mini - o4-mini - gpt-oss-120b - gpt-oss-20b - gpt-5 - gpt-5.1 - gpt-5.2 - gpt-5.4 - gpt-5.4-mini - gpt-5.4-nano - gpt-5.5 - gpt-5.6-terra - gpt-5.6-luna - gpt-5-mini - gpt-5-nano - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-sonnet-4-6 - claude-opus-4-5 - claude-haiku-4-5 - claude-sonnet-4-5 - gemini-2.5-pro - gemini-3-flash - gemini-3.1-flash-lite - gemini-3.1-pro - gemini-3.5-flash - gemini-3.5-flash-lite - gemini-3.6-flash - grok-3 - grok-3-mini - grok-4 - DeepSeek-V3 - DeepSeek-R1 - DeepSeek-V4-Flash - Llama-4-Scout-17B-16E-Instruct - Llama-4-Maverick-17B-128E-Instruct-FP8 - kimi-k2 - mistral-medium-3.5 - mistral-small-2603 - glm-5.2 description: AI model used by the agent example: gpt-5.1 autoRetrain: type: boolean description: Whether the agent automatically retrains every 7 days temp: type: number minimum: 0 maximum: 1 description: Model temperature (0–1) example: 0 visibility: type: string enum: - public - private description: Whether the agent is publicly accessible or private allowedDomains: type: - array - 'null' items: type: string description: Domains allowed to embed this agent suggestedMessages: type: - array - 'null' items: anyOf: - type: object properties: text: type: string minLength: 1 type: type: string enum: - single order: type: number icon: type: - string - 'null' required: - text - type - order - type: object properties: name: type: string minLength: 1 type: type: string enum: - nested order: type: number icon: type: - string - 'null' items: type: array items: type: object properties: text: type: string minLength: 1 order: type: number icon: type: - string - 'null' required: - text - order minItems: 1 maxItems: 20 required: - name - type - order - items description: Suggested quick-reply messages shown to users initialMessages: type: array items: type: string description: Initial messages shown when a conversation starts creditLimit: type: - integer - 'null' description: Per-agent credit limit (null = no limit) notificationsSettings: type: - object - 'null' properties: dailyLeadsCollected: type: object properties: active: type: boolean emails: type: array items: type: string pattern: ^\w+([+.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,})+$ maxItems: 10 required: - active - emails dailyConversations: type: object properties: active: type: boolean emails: type: array items: type: string pattern: ^\w+([+.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,})+$ maxItems: 10 required: - active - emails required: - dailyLeadsCollected - dailyConversations description: Email notification settings including recipient addresses ipRateLimits: $ref: '#/components/schemas/AgentIpRateLimits' voiceSettings: type: - object - 'null' properties: voice: type: object properties: voiceName: type: string speed: type: number minimum: 0.7 maximum: 1.2 stability: type: number minimum: 0 maximum: 1 similarity: type: number minimum: 0 maximum: 1 instructions: type: string maxLength: 500 required: - speed - stability - similarity transcriber: type: object properties: model: type: string language: type: string minSilenceDuration: type: number minimum: 0.1 maximum: 3 activationThreshold: type: number minimum: 0 maximum: 1 required: - model - language - minSilenceDuration - activationThreshold recordings: type: object properties: enabled: type: boolean retentionDays: type: integer minimum: 0 required: - enabled - retentionDays maxConcurrentSessions: type: - integer - 'null' exclusiveMinimum: 0 maxCallDurationSeconds: type: - integer - 'null' exclusiveMinimum: 0 maxDailyCallsPerUser: type: - integer - 'null' exclusiveMinimum: 0 model: type: string enum: - gpt-4o - gpt-4o-mini - o4-mini - gpt-oss-120b - gpt-oss-20b - gpt-5 - gpt-5.1 - gpt-5.2 - gpt-5.4 - gpt-5.4-mini - gpt-5.4-nano - gpt-5.5 - gpt-5.6-terra - gpt-5.6-luna - gpt-5-mini - gpt-5-nano - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-sonnet-4-6 - claude-opus-4-5 - claude-haiku-4-5 - claude-sonnet-4-5 - gemini-2.5-pro - gemini-3-flash - gemini-3.1-flash-lite - gemini-3.1-pro - gemini-3.5-flash - gemini-3.5-flash-lite - gemini-3.6-flash - grok-3 - grok-3-mini - grok-4 - DeepSeek-V3 - DeepSeek-R1 - DeepSeek-V4-Flash - Llama-4-Scout-17B-16E-Instruct - Llama-4-Maverick-17B-128E-Instruct-FP8 - kimi-k2 - mistral-medium-3.5 - mistral-small-2603 - glm-5.2 - auto temperature: type: number minimum: 0 maximum: 1 allowInterruptions: type: boolean allowTextInput: type: boolean endConversationAfterSilenceSeconds: type: - integer - 'null' minimum: 10 initialMessage: type: string maxLength: 500 errorMessage: type: string maxLength: 500 description: Voice mode settings styles: $ref: '#/components/schemas/AgentStyles' createdAt: type: string description: ISO 8601 creation timestamp example: '2024-01-15T10:30:00.000Z' lastMessageAt: type: - string - 'null' description: ISO 8601 timestamp of the last received message lastTrainedAt: type: - string - 'null' description: ISO 8601 timestamp of the last completed training status: type: - string - 'null' description: Current training status of the agent example: trained size: type: number description: Total size of training data in bytes required: - id - name - instructions - channelInstructions - model - autoRetrain - temp - visibility - allowedDomains - suggestedMessages - initialMessages - creditLimit - notificationsSettings - ipRateLimits - voiceSettings - styles - createdAt - lastMessageAt - lastTrainedAt - status - size AgentIpRateLimits: type: object properties: limit: type: integer minimum: 1 maximum: 200 description: Maximum messages per timeframe (1–200) example: 20 timeframe: type: integer minimum: 1 maximum: 3600 description: Timeframe in seconds for the rate limit (1–3600) example: 240 message: type: string description: Message shown when rate limit is exceeded example: Too many messages in a row required: - limit - timeframe - message AgentStyles: type: - object - 'null' properties: chat: type: - object - 'null' properties: theme: type: string enum: - light - dark default: light buttonColor: anyOf: - type: string pattern: ^#([0-9A-F]{3}){1,2}$/i - type: string enum: - transparent headerColor: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i userMessageColor: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i displayName: type: - string - 'null' autoOpenChatWindowAfter: type: - number - 'null' mobile: type: - object - 'null' properties: initialMessages: type: - object - 'null' properties: enabled: type: boolean value: type: array items: type: string required: - enabled - value autoOpenChatWindowAfter: type: - object - 'null' properties: enabled: type: boolean value: type: number required: - enabled - value showAutoOpen: type: - boolean - 'null' alignChatButton: type: - string - 'null' enum: - left - right - null messagePlaceholder: type: - string - 'null' footer: type: - string - 'null' showFeedback: type: - boolean - 'null' showCopyButton: type: - boolean - 'null' dismissableNotice: type: - string - 'null' showDictation: type: - boolean - 'null' showAttachments: type: - boolean - 'null' showVoiceMode: type: - boolean - 'null' description: Chat widget styles centerStage: type: - object - 'null' properties: enabled: type: boolean default: false theme: type: string enum: - light - dark default: light displayName: type: - string - 'null' welcomeMessage: type: - string - 'null' messagePlaceholder: type: - string - 'null' footer: type: - string - 'null' dismissableNotice: type: - string - 'null' suggestedMessages: type: - array - 'null' items: anyOf: - type: object properties: text: type: string minLength: 1 type: type: string enum: - single order: type: number icon: type: - string - 'null' required: - text - type - order - type: object properties: name: type: string minLength: 1 type: type: string enum: - nested order: type: number icon: type: - string - 'null' items: type: array items: type: object properties: text: type: string minLength: 1 order: type: number icon: type: - string - 'null' required: - text - order minItems: 1 maxItems: 20 required: - name - type - order - items showChatBubble: type: boolean default: true showAttachments: type: boolean default: false showDictation: type: boolean default: true showVoiceMode: type: boolean default: false showCopyButton: type: boolean default: false showFeedback: type: boolean default: true showDataSource: type: boolean default: true buttonColor: anyOf: - type: string pattern: ^#([0-9A-F]{3}){1,2}$/i - type: string enum: - transparent headerColor: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i userMessageColor: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i tintedGrayscale: type: object properties: enabled: type: boolean default: false hue: type: number minimum: 0 maximum: 360 default: 0 tint: type: number minimum: 0 maximum: 10 default: 0 shade: type: number minimum: 0 maximum: 10 default: 0 accentColor: type: object properties: enabled: type: boolean default: false color: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i default: '#09090B' customSurfaceColors: type: object properties: enabled: type: boolean default: false background: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i default: '#FFFFFF' foreground: type: string pattern: ^#([0-9A-F]{3}){1,2}$/i default: '#FFFFFF' typography: type: object properties: fontFamily: type: string pattern: ^[a-zA-Z0-9 ,'"_-]+$ default: Inter fontSize: type: string pattern: ^\d+(\.\d+)?(px|rem|em)$ default: 16px width: type: string enum: - small - medium - large default: medium closeOnOutsideClick: type: boolean default: true notificationIndicator: type: object properties: enabled: type: boolean default: false number: type: integer minimum: 0 maximum: 99 default: 1 notificationMessage: type: object properties: enabled: type: boolean default: false text: type: string maxLength: 200 default: '' description: Center stage widget styles required: - chat - centerStage securitySchemes: bearerAuth: type: http scheme: bearer description: API key from your account settings ````