API Reference

The API is how you fetch receipts, not how you decide trust. Use it to retrieve Evidence Envelopes, monitor run status, and resolve artifact bytes—then validate offline.

What this page can (and cannot) claim

✓
Mechanical claims

• Envelope retrieval: You can fetch a finalized Evidence Envelope by #evidenceId.
• Artifact resolution: You can fetch artifact bytes via content_uri or location_hint.
• Run status: You can query current run state (informational, not authoritative).
• SSE signals: You can subscribe to transient runtime events (hints only).

✗
No-claims

• No trust from API: The API delivers data; trust comes from validating the envelope offline.
• No guaranteed ordering: SSE events may arrive out of sequence.
• No exactly-once delivery: SSE streams can have gaps or duplicates.
• No determinism: Run outcomes depend on the code and environment, not the API.

The Golden Path for Consumers

A disciplined consumer workflow: fetch, validate, trust only the sealed envelope.

1. Subscribe to SSE (optional, hint only)

Subscribe to the events stream for progress signals. Treat all SSE data as informational hints, not authoritative records.

2. Wait for finalization signal

When SSE emits a run_finalized event (or status poll indicates completion), the envelope is ready. If no signal arrives, poll the run status endpoint.

3. Fetch the finalized envelope

Retrieve the envelope JSON by #evidenceId. This is the authoritative record—everything else was a hint.

4. Validate offline

Canonicalize (JCS), recompute hashes, walk integrity.hash_chain. If head_entry_hash matches your calculation, the envelope is intact.

5. Resolve and verify artifacts

Fetch artifact bytes via content_uri or location_hint. Recompute sha256 and compare to the envelope record. If they match, the artifact is authentic.

Endpoint Overview

Illustrative only. See OpenAPI/Swagger for the full endpoint list.

Runtime Surfaces (Informational)

These endpoints provide hints and status; they are not authoritative evidence.

GET /events— SSE stream for real-time run signals

GET /status— Current run status (pending, running, finalized, etc.)

GET /health— Server liveness check

Authoritative Record Surfaces (Evidence)

These endpoints deliver the sealed envelope and artifact bytes.

GET /evidence/#evidenceId— Fetch the finalized Evidence Envelope

GET /artifacts/#artifactId— Fetch raw artifact bytes by ID

Full API surface (OpenAPI/Swagger)

The server serves OpenAPI/Swagger documentation as the source of truth for all available endpoints, request/response schemas, and authentication requirements.

Interactive docs: Available at #apiBaseUrlFromConfig/docs (Swagger UI)
OpenAPI JSON: Available at #apiBaseUrlFromConfig/openapi.json
Client generation: Use the OpenAPI spec to generate typed clients for your language/framework.

Consumer Rules for API Discipline

SSE is a hint: Treat all stream events as informational; finalize trust only after fetching the envelope.
Envelope is authoritative: The finalized JSON with integrity.hash_chain is the receipt. Everything else led you here.
Verify artifacts: Retrieve raw bytes via artifact ID or pointer; always verify sha256 matches the envelope record.
Observations need basis: If an observation has no basis_artifact_ids present in the pack, treat it as informational only.
Idempotent handling: Expect SSE duplicates/gaps; use run_id and step_id for deduplication.

Essential Field Map

Field	Purpose
`evidence_id`	UUID identifier for this envelope
`subject.id`	Immutable anchor (prefer `#commitSha`)
`integrity.hash_chain`	Tamper-evident seal; walk to validate
`artifacts[].sha256`	Content identity of artifact bytes
`artifacts[].content_uri`	URN-based identifier (`urn:sha256:...`)
`artifacts[].location_hint`	Best-effort pointer to fetch bytes
`observations[].basis_artifact_ids`	Traceability links for verifiable claims

Troubleshooting

Envelope not found (404)

The run may not be finalized yet. Poll status or wait for SSE run_finalized event.

Artifact bytes unavailable

The location_hint may have expired or storage is unreachable. The envelope still records the sha256 identity.

SSE stream disconnects

Auto-reconnect and resume by querying current run status. SSE is transient; the envelope is authoritative.

hash_chain missing

The run is not finalized. Wait for finalization or check server logs for errors.

Integrity validation fails

Likely causes: Envelope was modified post-finalization, wrong canonicalization method, or partial/corrupted download.
Checks: Verify integrity.canonicalization == "rfc8785-jcs", re-download the envelope, and recompute hashes locally.

Next steps

Events (SSE) — real-time signals (transient, not authoritative)
Concepts — identity, traceability, canonicalization, integrity
First Job — complete walkthrough from intent to sealed envelope
Policies — redaction rules, allowlists, public vs internal
Auth & Secrets — authentication, redaction receipts, deny-by-default