> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Reference for querying conversation sessions and message history programmatically

<Hero title="Conversations" subtitle="Query conversation sessions and message history with REST endpoints and cursor-based pagination" />

This documentation describes the chat record query API for retrieving session records and conversation message history within a project. Use it to list sessions, inspect a single session, and retrieve messages for analytics, audit workflows, or downstream integrations.

## Base URL

```text theme={null}
https://transfer.navtalk.ai/api/chat
```

## Authentication

All requests require an `apikey` query parameter.

<Warning>
  Never expose your API key in client-side code or public repositories. API keys should be stored securely on your server and rotated regularly.
</Warning>

## Endpoints Overview

| Endpoint                         | Method | Description                                            |
| -------------------------------- | ------ | ------------------------------------------------------ |
| `/api/chat/sessions`             | `GET`  | List chat sessions for a project with optional filters |
| `/api/chat/sessions/{sessionId}` | `GET`  | Get details for a single chat session                  |
| `/api/chat/messages`             | `GET`  | List messages for a specific chat session              |

## List Chat Sessions

Retrieve a paginated list of chat sessions for a project.

```http theme={null}
GET /api/chat/sessions?apikey=YOUR_API_KEY&startTime=2025-11-12 00:00:00&endTime=2025-11-21 23:59:59&status=1&limit=20
```

### Query Parameters

| Name        | Type    | Required | Description                                            |
| ----------- | ------- | -------- | ------------------------------------------------------ |
| `apikey`    | string  | Yes      | Project API key used for authentication                |
| `startTime` | string  | No       | Start time in UTC, format `yyyy-MM-dd HH:mm:ss`        |
| `endTime`   | string  | No       | End time in UTC, format `yyyy-MM-dd HH:mm:ss`          |
| `status`    | integer | No       | Session status: `0=active`, `1=completed`, `2=failed`  |
| `limit`     | integer | No       | Maximum records to return. Default `20`, maximum `100` |
| `cursor`    | string  | No       | Pagination cursor for the next page                    |

### Response Example

```json theme={null}
{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "data": [
      {
        "id": "709b712f-dede-11f0-92bc-000e1eed4a72",
        "status": 1,
        "startTime": "2025-11-12 18:20:38",
        "endTime": "2025-11-12 18:20:50",
        "videoUrl": null
      },
      {
        "id": "709c1924-dede-11f0-92bc-000e1eed4a72",
        "status": 1,
        "startTime": "2025-11-12 23:17:42",
        "endTime": "2025-11-12 23:17:48",
        "videoUrl": null
      },
      {
        "id": "709c19a1-dede-11f0-92bc-000e1eed4a72",
        "status": 1,
        "startTime": "2025-11-14 07:44:42",
        "endTime": "2025-11-14 07:45:07",
        "videoUrl": null
      }
    ],
    "nextCursor": "MjAyNS0xMS0xNFQwNzo0NDo0Mnw3MDljMTlhMS1kZWRlLTExZjAtOTJiYy0wMDBlMWVlZDRhNzI="
  }
}
```

<Note>
  Results are ordered by `startTime` ascending, then by `id` ascending. `videoUrl` is `null` when no video was generated for the session.
</Note>

## Get Single Chat Session

Retrieve detailed information for a specific session.

```http theme={null}
GET /api/chat/sessions/709b712f-dede-11f0-92bc-000e1eed4a72?apikey=YOUR_API_KEY
```

### Path Parameters

| Name        | Type   | Required | Description                       |
| ----------- | ------ | -------- | --------------------------------- |
| `sessionId` | string | Yes      | Session identifier in UUID format |

### Query Parameters

| Name     | Type   | Required | Description                             |
| -------- | ------ | -------- | --------------------------------------- |
| `apikey` | string | Yes      | Project API key used for authentication |

### Response Example

```json theme={null}
{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "id": "709b712f-dede-11f0-92bc-000e1eed4a72",
    "status": 1,
    "startTime": "2025-11-12 18:20:38",
    "endTime": "2025-11-12 18:20:50",
    "videoUrl": null
  }
}
```

<Note>
  This endpoint returns the session object directly in `data`, not in a nested `data.data` array.
</Note>

## List Chat Messages

Retrieve messages for a specific chat session with optional filtering and pagination.

```http theme={null}
GET /api/chat/messages?apikey=YOUR_API_KEY&sessionId=709b712f-dede-11f0-92bc-000e1eed4a72&startTime=2025-11-12 18:20:00&endTime=2025-11-12 18:21:00&role=0&limit=50
```

### Query Parameters

| Name        | Type    | Required | Description                                            |
| ----------- | ------- | -------- | ------------------------------------------------------ |
| `apikey`    | string  | Yes      | Project API key used for authentication                |
| `sessionId` | string  | Yes      | Session identifier in UUID format                      |
| `startTime` | string  | No       | Start time in UTC, format `yyyy-MM-dd HH:mm:ss`        |
| `endTime`   | string  | No       | End time in UTC, format `yyyy-MM-dd HH:mm:ss`          |
| `role`      | integer | No       | Message role filter: `0=user`, `1=AI/assistant`        |
| `limit`     | integer | No       | Maximum records to return. Default `50`, maximum `200` |
| `cursor`    | string  | No       | Pagination cursor for the next page                    |

### Response Example

```json theme={null}
{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "data": [
      {
        "id": "70c27233-dede-11f0-92bc-000e1eed4a72",
        "role": 0,
        "messageType": 0,
        "content": "zaiganma",
        "createdAt": "2025-11-12 18:20:43"
      },
      {
        "id": "70c27301-dede-11f0-92bc-000e1eed4a72",
        "role": 1,
        "messageType": 0,
        "content": "It sounds like you're trying to convey something-could you clarify or share a bit more about what you need help with? I'm here to help.",
        "createdAt": "2025-11-12 18:20:45"
      },
      {
        "id": "70c273da-dede-11f0-92bc-000e1eed4a72",
        "role": 0,
        "messageType": 0,
        "content": "Thank You For Watching",
        "createdAt": "2025-11-12 18:20:45"
      }
    ],
    "nextCursor": "MjAyNS0xMS0xMlQxODoyMDo0NXw3MGMyNzNkYS1kZWRlLTExZjAtOTJiYy0wMDBlMWVlZDRhNzI="
  }
}
```

### Message Fields

| Field         | Type    | Description                                  |
| ------------- | ------- | -------------------------------------------- |
| `id`          | string  | Message UUID                                 |
| `role`        | integer | `0=user`, `1=AI/assistant`                   |
| `messageType` | integer | Message type. Current value is `0` for text  |
| `content`     | string  | Plain-text message content                   |
| `createdAt`   | string  | Message time in `yyyy-MM-dd HH:mm:ss` format |

<Note>
  Messages are ordered by `createdAt` ascending, then by `id` ascending.
</Note>

## Usage Guide

<Steps>
  <Step title="Get an API key">
    Obtain an active API key from your project settings before making requests.
  </Step>

  <Step title="List sessions">
    Call `GET /api/chat/sessions` to retrieve sessions for your project. Use `startTime`, `endTime`, and `status` to narrow the result set.
  </Step>

  <Step title="Inspect a session">
    Use the returned session `id` as `sessionId` in `GET /api/chat/sessions/{sessionId}` when you need session-level details.
  </Step>

  <Step title="Fetch messages">
    Call `GET /api/chat/messages` with `sessionId` to retrieve the conversation history. Use `role` if you only need user or assistant messages.
  </Step>

  <Step title="Paginate with nextCursor">
    For both list endpoints, omit `cursor` on the first request. On subsequent requests, pass the previous `nextCursor` until it is empty or `null`.
  </Step>

  <Step title="Handle UTC timestamps">
    All input time filters should use UTC and the format `yyyy-MM-dd HH:mm:ss`.
  </Step>
</Steps>

## Error Handling

| Code  | Meaning                                             |
| ----- | --------------------------------------------------- |
| `400` | Invalid API key or missing required parameters      |
| `403` | API key expired or project not active               |
| `404` | Session not found or does not belong to the project |
| `500` | Internal server error                               |

## Security Notes

* Never expose your API key in browser-side code.
* API keys are project-scoped and can expire.
* Send all requests over HTTPS.
* Rotate keys regularly.
* Monitor usage for abnormal traffic patterns.