Skip to main content

​
Overview

Conversations are read-only AI Career Chat sessions belonging to a chatbot. Each conversation has an ordered list of messages. List conversations for a chatbot, fetch a single conversation, and page through its messages with cursor pagination keyed on sequenceOrder.
Message content is free text authored by the candidate and may contain personal information they entered into the chat. Handle it accordingly.

​
List Chatbot Conversations

List the conversations for a chatbot (page paginated, newest first). Endpoint: GET /qsi/gather/chatbots/{chatbotId}/conversations
​
chatbotId
string
required
UUID of the chatbot
​
page
number
Page number (default: 1)
​
pageSize
number
Items per page (default: 50)
{
  "data": {
    "conversations": [
      {
        "id": "conv-uuid",
        "status": "ACTIVE",
        "startedAt": "2026-01-01T00:00:00Z",
        "endedAt": "2026-01-01T00:10:00Z",
        "candidateProfileId": "cp-uuid",
        "chatId": "chatbot-uuid",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-01T00:10:00Z"
      }
    ],
    "pagination": { "total": 3, "page": 1, "totalPages": 1, "pageSize": 50 }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}
A chatbot with no sessions returns 200 with an empty conversations array.

​
Get Conversation

Retrieve a single conversation. Endpoint: GET /qsi/gather/conversations/{conversationId}
​
conversationId
string
required
UUID of the conversation
{
  "data": {
    "conversation": {
      "id": "conv-uuid",
      "status": "ENDED",
      "startedAt": "2026-01-01T00:00:00Z",
      "endedAt": "2026-01-01T00:10:00Z",
      "candidateProfileId": "cp-uuid",
      "chatId": "chatbot-uuid",
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:10:00Z"
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}
status is one of ACTIVE, ENDED, or ARCHIVED.

​
List Conversation Messages

Page through a conversation’s messages in order, using cursor pagination on sequenceOrder. Endpoint: GET /qsi/gather/conversations/{conversationId}/messages
​
conversationId
string
required
UUID of the conversation
​
cursor
number
Return messages with sequenceOrder greater than this value. Omit for the first page.
​
limit
number
Page size (default: 50, max: 100)
{
  "data": {
    "items": [
      {
        "id": "msg-uuid",
        "role": "USER",
        "content": "Do you have any remote roles?",
        "sequenceOrder": 1,
        "metadata": { "uiType": "TEXT" },
        "conversationId": "conv-uuid",
        "createdAt": "2026-01-01T00:00:01Z",
        "updatedAt": "2026-01-01T00:00:01Z"
      }
    ],
    "nextCursor": null
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}
Messages use cursor pagination, not page-based pagination — the response contains nextCursor instead of a pagination/total object. Pass the returned nextCursor as the next request’s cursor to fetch the following page. When nextCursor is null, there are no more messages. role is one of USER, ASSISTANT, or SYSTEM.

​
Error Responses

Errors use the standard envelope: a nested error object (code, message, and an optional details) alongside a meta block. 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Conversation not found"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to retrieve conversation"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

Chatbots

Manage chatbots and configuration

Analytics

Chatbot engagement and funnel metrics