Using the Chunk API

Audience: integrators submitting VEX evidence chunks to Excititor.

The Chunk API ingests VEX evidence as a newline-delimited JSON (NDJSON) stream and queues it for processing. The server recomputes a deterministic digest over each chunk so callers can confirm exactly what was accepted.

Endpoint

POST /vex/evidence/chunks
Content-Type: application/x-ndjson

• Request schema: vex-chunk-api.yaml
• Sample payload: chunk-sample.ndjson

Response — 202 Accepted:

{ "chunk_digest": "sha256:…", "queue_id": "uuid" }

Operational notes

• Deterministic hashing: the server recomputes chunk_digest from canonical JSON; a mismatch returns 400.
• Limits: 500 items per chunk by default, 2000 maximum (aligned with the Program.cs guard).
• Telemetry: metrics are emitted under the StellaOps.Excititor.Chunks meter — see Chunk Telemetry. Broader Excititor evidence metrics are documented in the Observability guide.
• Correlation: trace/correlation headers are echoed back (X-StellaOps-TraceId, X-Stella-CorrelationId).

Example

curl -X POST https://excitor.local/vex/evidence/chunks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @docs/modules/excititor/samples/chunk-sample.ndjson