Skip to main content

Try the live demo!

Search

Get Agent

Requires the `users:manage` permission.

GET /api/v1/agents/{id}

Requires the users:manage permission.

Authentication

Use an agent API key and secret.

Parameters

All parameters are path parameters. All parameters are required.

Name Type
id string

Responses

200

Agent retrieved successfully

Content type: application/json.

Field Type Required Description
status string No example: "success"
data object No
data.id integer No example: 1
data.created_at string (date-time) No example: "2025-08-28T10:00:00Z"
data.updated_at string (date-time) No example: "2025-08-28T10:00:00Z"
data.first_name string No example: "John"
data.last_name string No example: "Doe"
data.email string (email) No nullable: true example: "[email protected]"
data.type string No example: "agent"
data.availability_status string (enum) No enum: ["online", "away", "away_manual", "offline", "away_and_reassigning"] example: "online"
data.phone_number_country_code string No nullable: true example: "US"
data.phone_number string No nullable: true example: "1234567890"
data.avatar_url string No nullable: true example: "/avatars/agent1.jpg"
data.enabled boolean No example: true
data.last_active_at string (date-time) No nullable: true example: "2025-08-28T10:00:00Z"
data.last_login_at string (date-time) No nullable: true example: "2025-08-28T10:00:00Z"
data.roles array of string No nullable: true example: ["admin"]
data.roles[] string
data.permissions array of string No nullable: true example: ["conversations:read"]
data.permissions[] string
data.custom_attributes object No nullable: true
data.teams array of object No nullable: true
data.teams[].id integer No example: 1
data.teams[].name string No example: "Support Team"
data.teams[].emoji string No nullable: true example: "🛠️"
data.api_key string No nullable: true
data.api_key_last_used_at string (date-time) No nullable: true
data.country string No ISO 3166-1 alpha-2 country code nullable: true example: "US"
data.meta object No nullable: true
data.external_user_id string No External identifier for the user in your own system nullable: true

400

Invalid request

Content type: application/json.

All fields are optional.

Field Type Description
status string example: "error"
message string Error message example: "Invalid request"
data unspecified Additional error data nullable: true
error_type string (enum) enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

401

Unauthorized

Content type: application/json.

Response fields match the 400 response.

403

Forbidden

Content type: application/json.

Response fields match the 400 response.

404

Not found

Content type: application/json.

Response fields match the 400 response.

500

Internal server error

Content type: application/json.

Response fields match the 400 response.

Specification

Download the complete OpenAPI specification.

OpenAPI definition for this endpoint
openapi: 3.0.0
info:
  title: libredesk API
  description: >-
    REST API documentation for libredesk helpdesk system.


    ## Authentication


    The libredesk API supports two authentication methods:


    ### 1. Basic Authentication

    Use your API key and secret with Basic authentication:

    ```

    Authorization: Basic <base64_encoded_api_key:api_secret>

    ```


    ### 2. Token Authentication  

    Use your API key and secret with token authentication:

    ```

    Authorization: token api_key:api_secret

    ```


    To obtain API credentials, generate them from your agent profile in the
    libredesk dashboard.
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local development server
security:
  - basicAuth: []
  - tokenAuth: []
paths:
  /api/v1/agents/{id}:
    get:
      tags:
        - Agents
      summary: Get Agent
      description: Requires the `users:manage` permission.
      operationId: handleGetAgent
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Agent retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - basicAuth: []
        - tokenAuth: []
components:
  schemas:
    AgentResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/Agent'
    ErrorResponse:
      type: object
      description: Error response format
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error message
          example: Invalid request
        data:
          nullable: true
          description: Additional error data
        error_type:
          type: string
          enum:
            - GeneralException
            - PermissionException
            - InputException
            - DataException
            - NetworkException
            - NotFoundException
            - ConflictException
            - UnauthorizedException
            - RateLimitException
    Agent:
      type: object
      properties:
        id:
          type: integer
          example: 1
        created_at:
          type: string
          format: date-time
          example: '2025-08-28T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-08-28T10:00:00Z'
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        email:
          type: string
          format: email
          example: [email protected]
          nullable: true
        type:
          type: string
          example: agent
        availability_status:
          type: string
          enum:
            - online
            - away
            - away_manual
            - offline
            - away_and_reassigning
          example: online
        phone_number_country_code:
          type: string
          nullable: true
          example: US
        phone_number:
          type: string
          nullable: true
          example: '1234567890'
        avatar_url:
          type: string
          nullable: true
          example: /avatars/agent1.jpg
        enabled:
          type: boolean
          example: true
        last_active_at:
          type: string
          format: date-time
          nullable: true
          example: '2025-08-28T10:00:00Z'
        last_login_at:
          type: string
          format: date-time
          nullable: true
          example: '2025-08-28T10:00:00Z'
        roles:
          type: array
          items:
            type: string
          example:
            - admin
          nullable: true
        permissions:
          type: array
          items:
            type: string
          example:
            - conversations:read
          nullable: true
        custom_attributes:
          type: object
          nullable: true
        teams:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/TeamCompact'
        api_key:
          type: string
          nullable: true
        api_key_last_used_at:
          type: string
          format: date-time
          nullable: true
        country:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 country code
          example: US
        meta:
          type: object
          nullable: true
        external_user_id:
          type: string
          nullable: true
          description: External identifier for the user in your own system
    TeamCompact:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Support Team
        emoji:
          type: string
          nullable: true
          example: 🛠️
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication using base64 encoded API key and secret. Format:
        `Authorization: Basic <base64(api_key:api_secret)>`
    tokenAuth:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        Token authentication using API key and secret. Format: `Authorization:
        token api_key:api_secret`

Was this article helpful?