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.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | version | version | string | single | The 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. |
| 2 | device_id | deviceId | string | single | A 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.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | batch_id | batchId | string | single | A unique ID the device app chooses for the batch (a UUID) and reuses on every retry of the same batch. |
| 2 | collector | collector | CollectorInfo | single | Who is sending, including the version for the handshake. |
| 3 | sent_at_unix_ms | sentAtUnixMs | int64 | single | When 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. |
| 4 | time_zone | timeZone | string | single | The device's time zone as an IANA name (Asia/Bangkok), never an offset. |
| 5 | events | events | Event | repeated | The events, in any order. At most 1,000 per batch. |
SendBatchResponse
SendBatchResponse reports what the batch changed.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | batch_id | batchId | string | single | The batch_id from the request. |
| 2 | created_count | createdCount | int32 | single | How many events were new and are now stored. |
| 3 | duplicate_count | duplicateCount | int32 | single | How many events were already stored and were left as they were. On a repeated batch this equals the number of events sent. |
| 4 | received_at_unix_ms | receivedAtUnixMs | int64 | single | When the server received the batch, in UTC milliseconds. |
| 5 | minimum_collector_version | minimumCollectorVersion | string | single | The 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.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | collector | collector | CollectorInfo | single | Who is sending, including the version for the handshake. |
| 2 | sha256 | sha256 | string | single | The 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. |
| 3 | upload_url | uploadUrl | string | single | The URL the resumable upload endpoint returned for the finished upload. |
| 4 | size_bytes | sizeBytes | int64 | single | The file's size in bytes. |
| 5 | mime_type | mimeType | string | single | The media type, such as audio/ogg; codecs=opus. |
| 6 | event_id | eventId | string | single | The event_id of the event the file belongs to. |
RegisterMediaResponse
RegisterMediaResponse reports whether the registration changed anything.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | sha256 | sha256 | string | single | The media's ID: the sha256 from the request. |
| 2 | created | created | bool | single | True when this call stored the file for the first time; false when the same content was already registered. |
| 3 | in_raw_store | inRawStore | bool | single | True 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. |