Ingest telemetry batch from on-prem instance

Receive and store a batch of telemetry events from an on-prem Compresr instance.

**Required Headers:**
- `X-API-Key`: Compresr API key (authentication)
- `X-Compresr-Signature`: HMAC signature (integrity)

**Optional Headers:**
- `X-Instance-ID`: On-prem instance identifier

**First Request (auto-registration):**
Include `signing_secret` (`opm_xxx`) in the body - it will be registered
automatically. The on-prem image generates this credential itself; `cmp_`
API keys are rejected.

**Signature Format:**
```
t=timestamp,v1=HMAC-SHA256(timestamp + "." + JSON(payload), signing_secret)
```

**Event Types:**
- `compression`: Counted for billing
- `error`: Logged only
- `startup`/`shutdown`: Operational

**Idempotency:**
Same batch_id within 24h returns success without reprocessing. A batch
with failed events stays replayable: retry it and already-billed events
are returned as status "duplicate" (never billed twice).

x-instance-idstring nullable

On-prem instance ID

x-compresr-signaturestring nullable

HMAC signature

X-API-Keystring required

Request body

batch_idstring required

Unique batch ID (UUID)

instance_idstring required

On-prem instance ID (UUID)

signing_secretstring nullable

Signing secret for HMAC verification (include on first request only)

Response

Successful Response

successboolean required

Whether batch was accepted

batch_idstring required

Echo of batch ID

events_receivedinteger required

Number of events received

events_storedinteger required

Number of events stored

messagestring nullable

Additional message

events_rejectedinteger

Events outside the reporting window; will never be billed

rejected_reasonsobject

Rejection reason -> count

signing_secret_registeredboolean nullable

Whether the signing_secret in this request is now stored. Cache 'registered' only on an explicit true - null also means an older server that predates this field, so treating null as success is the very bug this field exists to fix. Anything else means keep sending the secret on subsequent batches, because the server has nothing to verify future uploads against and they will 401.

signing_secret_errorstring nullable

Machine-readable reason registration did not happen. 'hash_owned_by_other_account': this deployment is using a signing secret belonging to a different account - usually a cloned data volume - and only an operator can clear it, so do not retry on it. 'not_attempted_duplicate_batch': idempotent replay, the next batch will register. 'registration_failed': transient, retry.

events_billedinteger

Compression events charged through the billing pipeline

events_unbilledinteger

Compression events recorded but not charged

events_duplicateinteger

Compression events skipped because an earlier delivery of this batch already billed them (replay protection)

events_failedinteger

Compression events that were not recorded; the batch is left replayable so a retry reprocesses exactly these events

Ingest telemetry batch from on-prem instance

Headers

Request body

Response

Changes