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

# Retrieve all the agents

Returns a list of all active agents in the organization.


## OpenAPI

````yaml https://api.getfernand.com/openapi.json get /agents
openapi: 3.0.3
info:
  title: Fernand API Documentation
  version: '3.0'
  description: This is the documentation for the [Fernand](https://getfernand.com) API.
  termsOfService: https://getfernand.com/terms
  contact:
    name: Fernand Support
    url: https://getfernand.com
    email: support@getfernand.com
  x-logo:
    url: https://app.getfernand.com/images/favicon/icon_128.png
servers:
  - url: https://api.getfernand.com
    description: ''
    x-last-modified: 1764750693905
security:
  - apiKeyHeader: []
externalDocs:
  description: You can access our documentation online by visiting https://api.fernand.help
  url: https://api.fernand.help
paths:
  /agents:
    get:
      tags:
        - Agents
      summary: Retrieve all the agents
      description: Returns a list of all active agents in the organization.
      operationId: listAgents
      parameters:
        - name: complete
          in: query
          required: false
          schema:
            type: boolean
          description: If true, includes roles and owner status in the response.
      responses:
        '200':
          description: Successfully retrieved the list of agents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized if API authentication is invalid or missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the agent
          example: 12345
        name:
          type: string
          maxLength: 250
          nullable: true
          description: Display name of the agent
          example: Richard Hendricks
        firstname:
          type: string
          description: First name extracted from the agent's name
          example: Richard
        email:
          type: string
          format: email
          maxLength: 250
          description: Primary email address of the agent
          example: richard.hendricks@piedpiper.com
        notification_email:
          type: string
          format: email
          maxLength: 250
          nullable: true
          description: >-
            Alternative email for receiving notifications (if different from
            primary email)
          example: richard.piper44@gmail.com
        timezone:
          type: string
          maxLength: 250
          nullable: true
          description: Agent's timezone (e.g., America/New_York, Europe/Paris)
          example: America/Los_Angeles
        signature:
          type: string
          nullable: true
          description: Email signature for the agent (HTML allowed)
          example: <p>Best regards,<br>Richard H.</p>
        avatar:
          type: string
          maxLength: 250
          nullable: true
          description: >-
            URL to the agent's avatar image. Either at Gravatar (default) or on
            our CDN if imported.
          example: >-
            https://www.gravatar.com/avatar/6d918cc24709975e61413ea4c2fb93f6?s=80&d=404
        dark_mode:
          type: boolean
          nullable: true
          description: Whether dark mode is enabled (null means system default)
          example: true
        is_mfa_enabled:
          type: boolean
          description: Whether multi-factor authentication is enabled for this agent
          example: false
        is_paying:
          type: boolean
          description: Whether this agent occupies a paid seat in the organization
          example: true
        is_removed:
          type: boolean
          description: Whether this agent has been removed from the organization
          example: false
        is_current_user:
          type: boolean
          description: Whether this agent is the currently authenticated user
          example: true
        roles:
          type: array
          items:
            type: string
          description: List of permission roles assigned to the agent
          example:
            - conversation.create
            - conversation.reply
            - teammate.invite
        owner:
          type: boolean
          description: Whether this agent is the organization owner
          example: false
        prev_next:
          type: string
          enum:
            - historical
            - natural
          description: Navigation preference for keyboard shortcuts (only for current user)
          example: historical
        newsletter:
          type: boolean
          description: >-
            Whether agent is subscribed to the newsletter (only for current
            user)
          example: true
        notifications:
          type: object
          description: >-
            Notification preferences organized by target and event (only for
            current user)
          example:
            BROWSER:
              INCOMING_EMAIL: true
              MENTIONED: true
            EMAIL:
              INCOMING_EMAIL: true
              ASSIGNED_ACTIVITY: false
        ai_prompt_answer:
          type: string
          description: >-
            Custom AI prompt template for generating responses (only for current
            user)
          example: Your name is ${agent_firstname}. Reply to ${contact_name} concisely.
        fernand_hash:
          type: string
          nullable: true
          description: >-
            Secure key for signing emails in the Fernand chat integration (only
            for current user)
          example: abc123def456...
        bounce_error:
          type: string
          maxLength: 250
          nullable: true
          description: Error message if email has bounced (only for current user)
          example: Mailbox full
        custom_inboxes:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              name:
                type: string
              query:
                type: object
          description: Custom inbox configurations (only for current user)
          example:
            - key: 60977abb694a6b2061de23fe26429ace
              name: Inbox
              query:
                assigned: me+none
                is: opened
                order: priority
        lock_reason:
          type: string
          maxLength: 250
          nullable: true
          description: >-
            Reason account is locked (email, bounced, ban) - only for current
            locked user
          example: email
        locked_ts:
          type: integer
          format: int64
          description: >-
            Unix timestamp (milliseconds) when account was locked - only for
            current locked user
          example: 1234567890000
      required:
        - id
        - email
        - is_paying
        - is_removed
      x-computed-hash: 21eea128ff5bdf8d8bf0e07ab393cdc4ad23991f171cb3892276f0f844b86fce
      x-last-modified: 1769075324
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      description: >-
        Authenticate your account by including your secret key in API requests.

        You can manage your API keys in the
        [Dashboard](https://app.getfernand.com/).


        Authentication to the API is performed by using the HTTP Header
        X-API-Key.
      name: X-API-Key
      in: header
      x-last-modified: 1764750344730

````