Ingest API

The calls a device app makes to hand captured conversations to the server, and the messages only those calls use.

This page is made from the API contract, contract/schema/namjai/v1/ingest.proto, so it always says what the server really accepts. How to reach the server and what a failure looks like are on Server API.

IngestService

IngestService is how a device app hands captured conversations to the server. Every call is safe to repeat: a device app that is not sure a call landed sends it again, and nothing is stored twice.

Full name: namjai.v1.IngestService.

SendBatch

Path: POST /namjai.v1.IngestService/SendBatch

Request: SendBatchRequest. Response: SendBatchResponse.

SendBatch stores a batch of events.

Idempotency (ING-2): an event is stored under its event_id, and an event_id that is already stored is counted as a duplicate and changes nothing. Sending the same batch again therefore creates zero new events, whether the first attempt succeeded, failed half way or timed out. The batch_id adds a fast path and an audit trail; correctness rests on the event IDs alone, so a retry may also regroup events into new batches.

The whole batch is validated before anything is stored. One invalid event fails the call with INVALID_ARGUMENT naming its index, and the device app must fix or drop that event before sending again.

RegisterMedia

Path: POST /namjai.v1.IngestService/RegisterMedia

Request: RegisterMediaRequest. Response: RegisterMediaResponse.

RegisterMedia attaches a file that was already uploaded through the resumable upload endpoint (tus, plain HTTP, outside this contract) to an event. Media is keyed by its content hash: registering the same hash again stores nothing new, and attaching it again to the same event changes nothing. One event may carry several media files. The event may arrive before or after its media; the server links them either way.

Messages

Each message is a JSON object, or protobuf. A field's JSON name is the name to use in JSON; the server also accepts the field name. A field left out reads as empty, zero or false.

CollectorInfo

CollectorInfo identifies the program that sent a call.

NumberFieldJSON nameTypeKindWhat it is
1versionversionstringsingleThe device app's release version in semantic versioning (1.4.2). The server compares it with its minimum supported version and, once ING-6 is in force, refuses an older device app with FAILED_PRECONDITION and a message that names both versions.
2device_iddeviceIdstringsingleA stable ID for the installed device app, chosen at enrolment. It tells two devices of the same agent apart.

SendBatchRequest

SendBatchRequest carries the events one device app captured since its last batch.

NumberFieldJSON nameTypeKindWhat it is
1batch_idbatchIdstringsingleA unique ID the device app chooses for the batch (a UUID) and reuses on every retry of the same batch.
2collectorcollectorCollectorInfosingleWho is sending, including the version for the handshake.
3sent_at_unix_mssentAtUnixMsint64singleWhen the device app sent the batch, by its own clock, in UTC milliseconds. The server compares it with its receipt time to measure the device app's clock offset, and stores both with the batch.
4time_zonetimeZonestringsingleThe device's time zone as an IANA name (Asia/Bangkok), never an offset.
5eventseventsEventrepeatedThe events, in any order. At most 1,000 per batch.

SendBatchResponse

SendBatchResponse reports what the batch changed.

NumberFieldJSON nameTypeKindWhat it is
1batch_idbatchIdstringsingleThe batch_id from the request.
2created_countcreatedCountint32singleHow many events were new and are now stored.
3duplicate_countduplicateCountint32singleHow many events were already stored and were left as they were. On a repeated batch this equals the number of events sent.
4received_at_unix_msreceivedAtUnixMsint64singleWhen the server received the batch, in UTC milliseconds.
5minimum_collector_versionminimumCollectorVersionstringsingleThe oldest device app version the server accepts, so a device app can update before it is refused. Empty until ING-6 is in force.

RegisterMediaRequest

RegisterMediaRequest names an uploaded file and the event it belongs to.

NumberFieldJSON nameTypeKindWhat it is
1collectorcollectorCollectorInfosingleWho is sending, including the version for the handshake.
2sha256sha256stringsingleThe SHA-256 of the file's bytes as 64 lower-case hex characters. It is the media's ID. The server checks it against the uploaded bytes.
3upload_urluploadUrlstringsingleThe URL the resumable upload endpoint returned for the finished upload.
4size_bytessizeBytesint64singleThe file's size in bytes.
5mime_typemimeTypestringsingleThe media type, such as audio/ogg; codecs=opus.
6event_ideventIdstringsingleThe event_id of the event the file belongs to.

RegisterMediaResponse

RegisterMediaResponse reports whether the registration changed anything.

NumberFieldJSON nameTypeKindWhat it is
1sha256sha256stringsingleThe media's ID: the sha256 from the request.
2createdcreatedboolsingleTrue when this call stored the file for the first time; false when the same content was already registered.
3in_raw_storeinRawStoreboolsingleTrue when the file is stored where it will be kept, so the device may delete its copy (CAP-14). False when the server cannot confirm that yet: the device keeps the file in its outbox and registers it again later.