GET /api/v1/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.
Authentication
Use an agent API key and secret.
Parameters
All parameters are query parameters.
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search query (minimum 3 characters) minLength: 3 |
| filters | string | No | 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). |
| sort | string (enum) | No | newest and oldest sort by last message time. started_last and started_first sort by creation time. Defaults to newest. default: "newest" enum: ["newest", "oldest", "started_first", "started_last"] |
| cursor | string | No | next_cursor from the previous page. A cursor works only with the sort it was created with. |
| page_size | integer | No | Number of results per page (defaults to 30). Values above 100 use 100. default: 30 minimum: 1 maximum: 100 |
Responses
200
Search results retrieved successfully
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | No | example: "success" |
| data | object | No | |
| data.results | array of object | No | |
| data.results[].created_at | string (date-time) | No | example: "2025-08-28T10:00:00Z" |
| data.results[].uuid | string | No | example: "550e8400-e29b-41d4-a716-446655440000" |
| data.results[].reference_number | string | No | example: "150" |
| data.results[].subject | string | No | nullable: true example: "Order inquiry" |
| data.results[].last_message | string | No | nullable: true |
| data.results[].last_message_at | string (date-time) | No | nullable: true |
| data.results[].assigned_user_id | integer | No | nullable: true |
| data.results[].assigned_team_id | integer | No | nullable: true |
| data.results[].assignee | object | No | Assigned agent. Fields are null when no agent is assigned. |
| data.results[].assignee.first_name | string | No | nullable: true |
| data.results[].assignee.last_name | string | No | nullable: true |
| data.results[].assignee.avatar_url | string | No | nullable: true |
| data.results[].team_name | string | No | nullable: true |
| data.results[].status | string | No | nullable: true example: "Open" |
| data.results[].priority | string | No | nullable: true |
| data.results[].inbox_name | string | No | nullable: true |
| data.results[].inbox_channel | string (enum) | No | enum: ["email", "livechat"] nullable: true |
| data.results[].contact | object | No | |
| data.results[].contact.first_name | string | No | nullable: true |
| data.results[].contact.last_name | string | No | nullable: true |
| data.results[].contact.email | string | No | nullable: true |
| data.results[].contact.avatar_url | string | No | nullable: true |
| data.results[].tags | array of string | No | |
| data.results[].tags[] | string | ||
| data.per_page | integer | No | |
| data.has_more | boolean | No | Whether another page exists |
| data.next_cursor | string | No | Pass as cursor to fetch the next page. Empty when has_more is false. |
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.
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/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 <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`