List all conversations with optional filtering.

GET

https://host.com/v1/conversations

GET

/v1/conversations

1 const url = 'https://host.com/v1/conversations';
2 const options = {
3   method: 'GET',
4   headers: {'X-API-Key': '<apiKey>', 'Content-Type': 'application/json'},
5   body: '{}'
6 };
7 
8 try {
9   const response = await fetch(url, options);
10   const data = await response.json();
11   console.log(data);
12 } catch (error) {
13   console.error(error);
14 }

1 {
2   "data": [
3     {
4       "userKey": "schen_2024",
5       "metadata": {
6         "topic": "Appointment Scheduling",
7         "priority": "high",
8         "channel": "chat"
9       },
10       "type": "chat",
11       "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
12       "name": "Conversation with Sarah Chen",
13       "assistantId": "a3f47b9e-8c2d-4f3a-9f1b-2e4d5c6a7b8c",
14       "createdAt": "2024-01-15T09:30:00Z",
15       "lastModifiedAt": "2024-01-15T10:15:00Z",
16       "isArchived": true
17     }
18   ],
19   "total": 1,
20   "page": 1,
21   "size": 1,
22   "pages": 1
23 }

Authentication

X-API-Keystring

API Key authentication. Generate your API key in the Gail Portal under General > Integrations > API Keys.

Query parameters

searchstringOptional

Optional search term to filter conversations.

typeenumOptional

Optional conversation type filter (e.g., Call, SMS).

Allowed values:

userIdstringOptionalformat: "uuid"

Optional user ID to filter conversations by user.

includeArchivedbooleanOptionalDefaults to false

When true, includes archived conversations in results.

afterstringOptionalformat: "uuid"

A GUID cursor to fetch items strictly after this ID.

beforestringOptionalformat: "uuid"

A GUID cursor to fetch items strictly before this ID.

limitintegerOptionalDefaults to 50

Maximum number of items to retrieve (default 50).

pageintegerOptionalDefaults to 1Deprecated

The page number (1-based).

sizeintegerOptionalDefaults to 50Deprecated

Number of items per page (default 50).

Response

datalist of objects or nullOptional

totalinteger or nullOptional

pageinteger or nullOptional

sizeinteger or nullOptional

pagesinteger or nullOptional

Errors

400

Bad Request Error

404

Not Found Error