Direct HTTP API
If the Node SDK doesn't fit (a Python service, a shell script, a gateway), ship batches directly to POST /v1/batches. The endpoint authenticates by ECDSA signature, so your request carries no bearer token.
Why most teams still use the SDK
The SDK handles the parts that are easy to get wrong: canonical serialization for signing, batch sequence numbers, per-day chaining, spool-and-retry offline queueing. With raw HTTP you own all of that. If a runtime can run Node, installing @provantix/agent-sdk is the safer path. A Python SDK is on the roadmap.
The 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": "sha256 over canonical { records, rollups }",
"rollups": [],
"records": [ "sealed records: { fields, erasable, integrity }" ],
"signature": "base64-detached-ECDSA-signature"
}
collector_id: 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_seq: strictly increasing per emitter, starting at 1. Gaps are detected and reported; reuse is rejected.records: sealed records as the SDK produces them (see Agent Action Record schema for the source shape). The digest covers exactly{ records, rollups }, nothing else.signature: ECDSA P-256 (SHA-256) over the canonical bytes of the envelope without thesignaturefield, base64-encoded.
The exact construction, the canonicalization rules and a captured example envelope you can test against are on the batches endpoint reference. The reference implementation is public in the SDK repository under src/vendor/batch.mjs.
Endpoint and errors
POST https://app.provantix.tech/v1/batches
content-type: application/json
| Status | Meaning |
|---|---|
| 200 | Batch accepted; response includes accepted/rejected record counts |
| 400 | Envelope malformed or schema-invalid records |
| 401 | Unknown emitter id |
| 403 | Emitter revoked or signature invalid |
| 409 | batch_seq out of order (duplicate or gap) |
| 413 | Batch over the 10 MB limit |
Schema-invalid records inside an otherwise valid batch are rejected individually and counted; valid records in the same batch are still stored.
A note on integrity
The platform's promise is that verification starts on your side: payloads are signed at capture, the control plane verifies that signature before storage, and exports re-verify offline and carry a Provantix signature you can check against our published keys. A hand-rolled HTTP client preserves that promise only if it signs at the point of capture and never reuses a sequence number. If you build one, mirror the SDK's envelope construction exactly and test against a sandbox emitter before pointing it at production agents.