git.stella-ops.org/docs/policy/api.md

Policy API Reference (runtime endpoints)

Imposed rule: Policy API calls must include tenant context and operate on frozen inputs; mutating endpoints require Authority scopes and audit events.

Base

/api/v1/policies

Endpoints

• GET /policies – list policies (with filters: tenant, status, name, tags); paginated.
• GET /policies/{id} – fetch metadata and versions.
• GET /policies/{id}/versions/{v} – fetch IR, hash, status, shadow flag, attestation refs.
• POST /policies/{id}/simulate – run simulate; body: { inputs: { sbom_digest, advisory_snapshot, vex_set, reachability_hash, signals_digest }, settings: { shadow: bool } }. Returns runId, findings, explain summary; full explain via run endpoint.
• POST /policies/{id}/run – full run with frozen cursors; same body as simulate plus mode (full|incremental).
• GET /policy-runs/{runId} – returns findings, explain trace refs, hashes, shadow flag, status.
• POST /policies/{id}/submit – attach lint/simulate/coverage artefacts; transitions to submitted.
• POST /policies/{id}/approve – requires policy:approve; records approval note.
• POST /policies/{id}/publish – requires policy:publish; body includes reason, ticket, sign=true|false; returns attestation ref.
• POST /policies/{id}/activate – requires policy:activate; activates version.
• POST /policies/{id}/archive – archive version; reason required.

Headers

• X-Stella-Tenant (required)
• X-Stella-Shadow (optional; simulate)
• If-None-Match (IR cache)

Auth & scopes

• Read: policy:read
• Simulate: policy:simulate
• Submit: policy:author
• Approve: policy:approve
• Publish/Promote: policy:publish/policy:promote
• Activate/Run: policy:operate

Errors (Problem+JSON)

• policy_inputs_unfrozen (409) – missing cursors.
• policy_ir_hash_mismatch (409) – IR hash differs from attested value.
• policy_shadow_required (412) – shadow gate not satisfied.
• policy_attestation_required (412) – publish without attestation metadata.
• Standard auth/tenant errors.

Pagination & determinism

• limit/cursor; stable ordering by policyId then version.
• All list endpoints return ETag and Content-SHA256 headers.

Offline

• API supports file:// bundle handler when running in sealed mode; simulate/run accept bundle path instead of remote cursors.

Observability

• Metrics: policy_api_requests_total{endpoint,status}, policy_simulate_latency_seconds, policy_run_latency_seconds.
• Logs: include policyId, version, runId, tenant, shadow, cursors hashes.