POST /v1/batches
The signed ingest endpoint. Every SDK flush and direct HTTP integration lands here.
POST https://app.provantix.tech/v1/batches
content-type: application/json
Authentication
None of the usual kind. The batch envelope carries collector_id (emitter id) and an ECDSA P-256 signature. The platform resolves the emitter to your organization, verifies the signature against the registered public key, and routes the batch to your organization's database. A revoked or unknown emitter is rejected before any body processing.
Envelope
A batch is a JSON envelope:
{
"batch_version": "1.0",
"collector_id": "emi_01m…",
"batch_seq": 17,
"created_at": "2026-10-21T09:41:03Z",
"record_count": 1,
"batch_digest": "41f377d41d1c82fa7e784a77a6289b9f6907a20ef407853fe6e7674f7707484d",
"rollups": [],
"records": [ "sealed records, see below" ],
"signature": "MEUCIQD…"
}
Field rules:
collector_idis your emitter id. Routing is signature-based: the platform looks up the organization that owns this emitter id and delivers the batch to that organization's database.batch_seqstarts at 1 and increments by 1 per emitter. Duplicates and gaps are rejected with 409. Persist the counter across restarts (the SDK does this via its spool directory); a restart that reuses sequence numbers is rejected as a forked chain.record_countmust equalrecords.length.batch_digestbinds the body to its content. See the recipe below; a digest mismatch is rejected with 400 before any record is processed.rollupsare hourly aggregate counts the emitter sends in place of individual records for human activity it chose not to record one by one, a privacy rule applied before data leaves your side. An agent emitter normally has none, and an empty batch still carries"rollups": []; a missing field is treated as[]by the server, but sign and hash the explicit empty array.recordsare sealed records exactly as the SDK produces them:{ fields, erasable, integrity }, whereintegrityholds the per-field salted commitments and the record hash. See Agent Action Record for the source shape and the record anatomy page for the sealing layout.seal(optional, from SDK 0.2.0, withbatch_version"1.1") is the emitter's signature over the hash of every record in the batch:{ statement, signature }, wherestatementis{ seal_version: 2, collector_id, batch_seq, created_at, record_count, record_hashes: [hex...], rollups_digest }andsignatureis base64 ECDSA P-256 (SHA-256, DER) over the canonical JSON ofstatement. It sits inside the envelope body, so the batchsignaturecovers it. See The emitter proof.signatureis the base64-encoded detached ECDSA signature over the canonical JSON of the envelope without thesignaturefield.
Batch digest recipe
The digest covers exactly two fields, nothing else:
batch_digest = lowercaseHex(sha256(utf8Bytes(canonicalize({ records, rollups }))))
Common mistakes that all produce 400 batch digest does not match contents:
- Hashing the whole envelope, or adding
collector_id/batch_seq/created_atto the hashed object. - Omitting
rollupsfrom the hashed object (it must be present, as[]if empty). - Serializing with whitespace or unsorted keys.
Canonicalization rules (the same rules every hash in the ledger uses):
- Object keys sorted at every depth, ASCII order.
- No insignificant whitespace.
- Strings escaped exactly as
JSON.stringifydoes. - Arrays keep their order.
nullis kept;undefinedis rejected (absence must be explicit); non-finite numbers are rejected.
Signature recipe
const body = { batch_version, collector_id, batch_seq, created_at, record_count, batch_digest, rollups, records };
const signature = sign('sha256', Buffer.from(canonicalize(body), 'utf8'), privateKeyPem).toString('base64');
ECDSA P-256 (prime256v1), PKCS8 private key, node crypto.sign('sha256', …), DER output, base64. The verification side re-canonicalizes the received envelope minus signature and verifies against your registered public key.
Captured example
One AAR record sealed and shipped, captured from @provantix/agent-sdk 0.1.1. Signing key is throwaway and the ids are examples; use it to verify your envelope construction, not to POST anywhere.
{
"batch_version": "1.0",
"collector_id": "emi_example",
"batch_seq": 1,
"created_at": "2026-10-22T00:00:00.000Z",
"record_count": 1,
"batch_digest": "41f377d41d1c82fa7e784a77a6289b9f6907a20ef407853fe6e7674f7707484d",
"rollups": [],
"records": [
{
"fields": {
"tenant_id": "ten_example",
"observed_at": "2026-10-22T00:00:00.000Z",
"gate_class": "full",
"source": {
"connector_instance": "otel:emi_example",
"system": "cruz-backend",
"event_id": "evt_example_0001",
"event_type": "AgentAction",
"vantage": "inside"
},
"principal": { "kind": "agent", "id": "cruz-agent-1" },
"agent_hint": {
"vendor": "cruz",
"vendor_agent_id": "cruz-agent-1",
"agent_version": "1.0.0",
"client_id": null,
"token_actor": null
},
"action": {
"action_type": "execute",
"target_system": "internal",
"target_entity_type": null,
"target_entity_id": null,
"operation": null,
"tool_name": "echo",
"field_names": [],
"record_count": null,
"external_recipient": null,
"data_classes": []
},
"resources_touched": [],
"correlation": {
"trace_id": "trc_example_0001",
"span_id": "spn_example_0001",
"parent_span_id": null,
"session_id": null,
"conversation_id": null
},
"model": {
"provider": "cruz",
"model_id": "cruz-llm-1",
"model_version": null,
"tokens_in": 5,
"tokens_out": 1,
"latency_ms": 42
},
"quality": null,
"redaction": { "profile": "default-v1", "counts": {} }
},
"erasable": {
"on_behalf_of": { "value": [], "salt": "d809a46b7152b8e85f1e3355a3045caa" },
"delegation_chain": { "value": [], "salt": "929bac6e2f7869722ba37652e1e32df3" },
"input_summary": { "value": "hello", "salt": "385e130b9b1a5c10c03c05c7e5118c76" },
"output_summary": { "value": "world", "salt": "5e5c734f99da7b2b4ab94bffb213daad" },
"attribution_evidence": { "value": null, "salt": "5a5b1cf42b4ee630e0ff98850d56c996" },
"ext": { "value": null, "salt": "04d954f0369df2175942b1f4a5b42ef4" },
"user_agent": { "value": null, "salt": "802c3b4f828e8ff4337c0b840fffa77c" }
},
"integrity": {
"record_hash": "f0077f31df3981179c79bd9d3ce50866859bfaa017ccdf43ea609c773036e3cb",
"commitments": {
"on_behalf_of": "93cd7347c765eaf068e98ddc894769a6c3876048cdbc6b610a637c57ad3ffaba",
"delegation_chain": "39f775e463f4be4eb08834aba5721214edc7664482e14ddd27c01bf7ce371f43",
"input_summary": "99f212a9eadce2c4d404a2331186843f613f4767ff87df44db0c2553891c0945",
"output_summary": "7510c205fba1f3651aed1c2e898c85922cfac334793f3cb3527d3a95da856dac",
"attribution_evidence": "c32d46588d85afcde21119b62786490d45f4ec0d2c961ec87f1d310b7eb793b3",
"ext": "3e3ed17815f83a802fccf46ae29c4e9c026638465abcbadb0690d5bffa3242b8",
"user_agent": "7ea68e1a78a2fd606bafafc464a7963e2c8f705a5bf8960fd22f2d79b42ed44a"
}
}
}
],
"signature": "MEUCIQDSN2gNxKfVjKM8ZNgkSYaXdMnIns6UVdyy4oPmmCZmAgIgGjQ2GPydXp4qKOaHvOut82X5HbNXWTZ+r0XnT1m1aWQ="
}
To check your implementation, recompute sha256(canonicalize({ records, rollups })) over the records and rollups above: you must get 41f377d4…7484d.
Response
Success (200):
{ "accepted": 42, "rejected": 1, "batch_seq": 17 }
Per-record rejections are counted, not fatal: valid records in a rejected-record batch are still stored and chained.
| Status | When |
|---|---|
| 400 | Malformed JSON, digest mismatch, invalid sealed record |
| 401 | collector_id unknown |
| 403 | Signature mismatch, or emitter revoked |
| 400 | seal_invalid: the seal does not match the batch it came in, or does not verify with the emitter key. The whole batch is refused |
| 409 | batch_seq duplicate or out of order |
| 426 | seal_required: the sealing deadline has passed and the batch was created without a seal. The emitter's telemetry pauses until its SDK is upgraded; pilot and trial sources are exempt |
| 413 | Body over 10 MB |
Errors worth handling specially
- 400 batch digest does not match contents: the hashed bytes differ from the recipe above. Nearly always
rollupsmissing from the hashed object, whitespace, or unsorted keys. Verify against the captured example. - 403 on a working integration: the emitter was revoked, or the private key was rotated and the service still signs with the old one.
- 409 with expected seq: another process is shipping under the same emitter id (a copied key or a duplicated pod). Emitters are one-per-service for this reason.
- 426 seal_required: the sealing deadline has passed. Upgrade the SDK to 0.2.0 (sealing is on by default); batches already queued are sealed when it sends them. See Sealing deadline, paused telemetry and lost seals.
- 429: you are shipping faster than the ingest window; the SDK backs off automatically.