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

# Ingest Export

> Upload and process an LLM conversation data export.

## `POST /api/ingest-export`

Ingests a conversation data export (JSON) for a given connection. The export file is normalized into individual conversations with a consistent `{ role, content, timestamp }` message format and stored in the Verso database.

Currently supports ChatGPT export format (DAG → linear message list normalization).

## Request

**Headers**

| Header          | Value                    |
| --------------- | ------------------------ |
| `Authorization` | `Bearer YOUR_APP_SECRET` |
| `Content-Type`  | `application/json`       |

**Body**

```json theme={null}
{
  "appId": "app_yourapp",
  "connectionId": "uuid",
  "conversations": [
    {
      "title": "Conversation title",
      "create_time": 1700000000,
      "update_time": 1700001000,
      "mapping": { "..." : "..." },
      "conversation_id": "chatgpt-uuid"
    }
  ]
}
```

| Field           | Type     | Required | Description                                       |
| --------------- | -------- | -------- | ------------------------------------------------- |
| `appId`         | `string` | Yes      | Your app identifier                               |
| `connectionId`  | `string` | Yes      | The connection to associate data with             |
| `conversations` | `array`  | Yes      | Array of raw conversation objects from the export |

## Processing

The endpoint performs a **diff/upsert** for each conversation:

1. **Normalize** — raw export data is converted to `NormalizedConversation` (linear message list)
2. **Check existing** — looks up by `(connection_id, external_id)`
3. **Insert** — if no existing record
4. **Update** — if existing record has an older `update_time`
5. **Skip** — if existing record is the same or newer

After processing, the connection's `last_ok_at` is updated. If any conversations were inserted or updated, a `data.imported` webhook is enqueued.

## Response

```json theme={null}
{
  "ok": true,
  "inserted": 42,
  "updated": 3,
  "unchanged": 0,
  "total": 45
}
```

| Field       | Type      | Description                                    |
| ----------- | --------- | ---------------------------------------------- |
| `ok`        | `boolean` | Always `true` on success                       |
| `inserted`  | `number`  | New conversations inserted                     |
| `updated`   | `number`  | Existing conversations updated (newer version) |
| `unchanged` | `number`  | Conversations skipped (same or older version)  |
| `total`     | `number`  | Total conversations in the export              |

## Errors

| Status | Error                                     | Cause                                            |
| ------ | ----------------------------------------- | ------------------------------------------------ |
| 400    | `Missing appId`                           | `appId` field not provided                       |
| 400    | `Missing connectionId`                    | `connectionId` field not provided                |
| 400    | `Invalid JSON body`                       | Request body is not valid JSON                   |
| 400    | `[normalization error]`                   | Export data could not be normalized              |
| 401    | `Missing or invalid Authorization header` | Missing `Bearer` prefix                          |
| 401    | `Invalid API key`                         | Wrong or missing app secret                      |
| 403    | `Connection does not belong to this app`  | Connection exists but belongs to a different app |
| 404    | `App not found`                           | App ID doesn't exist                             |
| 404    | `Connection not found`                    | Connection ID doesn't exist                      |
| 405    | `Method not allowed`                      | Must use `POST`                                  |
| 409    | `Connection is revoked`                   | Connection was deleted                           |