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 the signature field, 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.