Bulk import

Backfill history you already have.

Send us the conversations you already have, so a score has history behind it from the first day.

The request

A file upload, not a JSON body. Send it as a form, with an ingest key.

http

POST /ingest/v1/import
Authorization: Bearer ak_live_...
Content-Type: multipart/form-data

file	The export itself. One JSON document, or one JSON record per line.
adapter	Which contract to read the file with. Use generic for a file you built yourself.
client_id	Optional. Which client the history belongs to.

A key limited to one client may name only that client. Naming another gets 403. A key with no limit may name any client of the workspace, and an id we cannot find gets 404.

How it differs from sending events

The file is stored first and read by a background job, so the answer comes back before any of it is parsed.
The ceiling is 200 MiB per file, against 8 MiB for a live batch.
A line we cannot read is skipped and counted, so one bad record does not cost you the export. A file where no line parses at all fails outright, because that is the wrong file rather than a partial one.

What we send back

202, with an import id and the key the file was stored under.

json

{ "status": "accepted", "import_id": "...", "object_key": "..." }

202	Stored and queued.
401	The key is missing, revoked, or does not carry the ingest scope.
403	The key is limited to a client other than the one named.
404	The client named is not one of this workspace's.
413	The file is above 200 MiB. Split it.
422	A form field is missing, or the client id is not an id.