API and data contracts

Gateway versus standalone services

The gateway imports selected APIRoute objects from the service applications. It is not a general-purpose reverse proxy and does not forward arbitrary paths.

Method and path	Gateway	Standalone owner
`GET /`	UI	Web UI
`GET /healthz`	Gateway health	Each standalone service has its own health route
`GET /health`	Agent health	Edge Agent
`GET /readyz`	Synthetic readiness	Evidence API
`GET /api/v1/artifacts`	Yes; optional `state` filter	Evidence API
`GET /api/v1/artifacts/{artifact_id}`	Yes; unknown ID returns 404	Evidence API
`GET /api/v1/receipts`	Yes	Evidence API
`GET /api/v1/receipts/{receipt_id}`	Yes; unknown ID returns 404	Evidence API
`POST /api/v1/inspect`	Yes; classifies supplied JSON	Edge Agent
`POST /api/v1/demo/reset`	No: 404	Evidence API only; resets its disposable demo store
`/static/*`	UI assets	Web UI

FastAPI’s generated /docs, /redoc and /openapi.json are also present by default; the table above describes application routes, not a claim that these framework routes are disabled.

HTTP POST does not necessarily mean persistent mutation. /api/v1/inspect accepts an artifact payload and returns a classification; it does not process or replicate evidence. Conversely, do not describe every standalone route as read-only: the API’s local demo-reset route changes the disposable projection store.

ArtifactProjection

The Pydantic models reject extra fields. An artifact includes:

Field	Contract
`artifact_id`	`art_` followed by 8–64 lowercase letters/digits
`state`	`prepared`, `processing`, `complete`, `deferred` or `failed`
`digest`	`sha256:` followed by 64 lowercase hexadecimal characters
`created_at`	Date/time
`source`	Must be `synthetic`
`snapshot_eligible`	Boolean
`labels`	String-to-string map; defaults to an empty map

Five states are supported by the model, but the supplied UI demonstration contains only three fixed examples. A schema-valid record is not an independent verification of its claimed bytes.

Inspection response

AgentInspection contains artifact_id, classification, explanation, optional proposal, mutation_authorized (default false) and requires_human_approval (default false).

The deterministic rules leave mutation_authorized false. A proposal is data, not an executed command. Invalid inspection payloads receive FastAPI/Pydantic validation errors (normally HTTP 422).

Receipts and JSON schemas

EvidenceReceipt combines a receipt/artifact identity, status, issue time, Processor and Replication summaries, and provenance strings. Here those are synthetic projections, not a worker execution attestation.

The repository also supplies artifact JSON Schema and receipt JSON Schema. They are not interchangeable with the runtime model: the artifact JSON Schema requires source and labels, whereas Pydantic supplies defaults when they are omitted. An input accepted by the runtime can therefore fail standalone JSON Schema validation. This distinction is recorded, not silently repaired upstream.

Origins and authority

Compose configures explicit backend origins and CORS allowlists. Gateway requests are same-origin. The existing test checks that an unauthorized inspection preflight is not granted; this is not an authentication system or a general authorization guarantee. See the enforced boundary.

Source and provenance

Curated adaptation of pinned public source; not a current hosted-deployment attestation.

Seemorghdev/edge-evidence-reference-platform-public @ 37e8a8f · source review recorded 2026-10-15T06:52:47Z UTC

Adapted from Apache-2.0 source by Seemorghdev. Changes are explanatory and do not amend the engineering source. Source license · NOTICE · Third-party notices · Source manifest