> ## Documentation Index > Fetch the complete documentation index at: https://docs.libredesk.io/llms.txt > Use this file to discover all available pages before exploring further. # Paginated Search Conversations > Matches conversations whose reference number equals the query or whose contact email contains it, with filters and cursor pagination. An exact reference number match is listed first. Returns only conversations the caller can access. Requires the `conversations:read` permission. ## OpenAPI ````yaml get /api/v1/search/conversations 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 ``` ### 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/search/conversations: get: tags: - Search summary: Paginated Search Conversations description: >- Matches conversations whose reference number equals the query or whose contact email contains it, with filters and cursor pagination. An exact reference number match is listed first. Returns only conversations the caller can access. Requires the `conversations:read` permission. operationId: handlePaginatedSearchConversations parameters: - name: query in: query required: true schema: type: string minLength: 3 description: Search query (minimum 3 characters) - name: filters in: query required: false schema: type: string description: >- JSON-encoded filter. Either an array of conditions that are AND-ed, e.g. `[{"model":"conversations","field":"status_id","operator":"equals","value":"1"}]`, or a group `{"logic":"AND","rules":[...]}` with at most one level of nested groups. Operators: `equals`, `not equals`, `greater than`, `less than`, `set`, `not set`, `in`, `between`, `contains`, `ilike`, `not contains`. Filterable fields: `conversations` (status_id, priority_id, assigned_team_id, assigned_user_id, inbox_id, last_message_at, last_interaction_at, last_interaction_sender, created_at, waiting_since, next_sla_deadline_at, snoozed_until, sla_policy_id, tags), `conversation_statuses` (id, name), `users` (email, external_user_id), `inboxes` (channel). - name: sort in: query required: false schema: type: string enum: - newest - oldest - started_first - started_last default: newest description: >- `newest` and `oldest` sort by last message time. `started_last` and `started_first` sort by creation time. Defaults to `newest`. - name: cursor in: query required: false schema: type: string description: >- `next_cursor` from the previous page. A cursor works only with the `sort` it was created with. - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 30 description: >- Number of results per page (defaults to 30). Values above 100 use 100. responses: '200': description: Search results retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ConversationSearchPageResponse' '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' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - basicAuth: [] - tokenAuth: [] components: schemas: ConversationSearchPageResponse: type: object properties: status: type: string example: success data: type: object properties: results: type: array items: $ref: '#/components/schemas/ConversationSearchResult' per_page: type: integer has_more: type: boolean description: Whether another page exists next_cursor: type: string description: >- Pass as `cursor` to fetch the next page. Empty when `has_more` is false. 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 ConversationSearchResult: type: object properties: created_at: type: string format: date-time example: '2025-08-28T10:00:00Z' uuid: type: string example: 550e8400-e29b-41d4-a716-446655440000 reference_number: type: string example: '150' subject: type: string nullable: true example: Order inquiry last_message: type: string nullable: true last_message_at: type: string format: date-time nullable: true assigned_user_id: type: integer nullable: true assigned_team_id: type: integer nullable: true assignee: type: object description: Assigned agent. Fields are null when no agent is assigned. properties: first_name: type: string nullable: true last_name: type: string nullable: true avatar_url: type: string nullable: true team_name: type: string nullable: true status: type: string nullable: true example: Open priority: type: string nullable: true inbox_name: type: string nullable: true inbox_channel: type: string nullable: true enum: - email - livechat contact: type: object properties: first_name: type: string nullable: true last_name: type: string nullable: true email: type: string nullable: true avatar_url: type: string nullable: true tags: type: array items: type: string securitySchemes: basicAuth: type: http scheme: basic description: >- Basic authentication using base64 encoded API key and secret. Format: `Authorization: Basic ` tokenAuth: type: apiKey name: Authorization in: header description: >- Token authentication using API key and secret. Format: `Authorization: token api_key:api_secret` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.