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_id is 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 starts 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_count must equal records.length.
  • batch_digest binds the body to its content. See the recipe below; a digest mismatch is rejected with 400 before any record is processed.
  • rollups are 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.
  • records are sealed records exactly as the SDK produces them: { fields, erasable, integrity }, where integrity holds 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, with batch_version "1.1") is the emitter's signature over the hash of every record in the batch: { statement, signature }, where statement is { seal_version: 2, collector_id, batch_seq, created_at, record_count, record_hashes: [hex...], rollups_digest } and signature is base64 ECDSA P-256 (SHA-256, DER) over the canonical JSON of statement. It sits inside the envelope body, so the batch signature covers it. See The emitter proof.
  • signature is the base64-encoded detached ECDSA signature over the canonical JSON of the envelope without the signature field.

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_at to the hashed object.
  • Omitting rollups from 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.stringify does.
  • Arrays keep their order.
  • null is kept; undefined is 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 rollups missing 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.