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

{
  "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

{
  "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