v1

latestOpenAPI 3.1.02026-08-04134182237.9 KB
On-Prem Telemetry

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. `cmp_` API keys are rejected; mint an `opm_` credential
in the dashboard under Settings -> On-Prem first.

**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).
post/api/v1/telemetry/batch

Headers

x-instance-idstring nullable

On-prem instance ID

On-prem instance ID

x-compresr-signaturestring nullable

HMAC signature

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_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