Policy API Reference (runtime endpoints)

Audience: engineers and CI integrators calling the Policy runtime APIs to list, simulate, run, and promote policies.

This page lists the runtime HTTP endpoints, required headers, Authority scopes, error codes, and observability signals. For the policy lifecycle and authoring model, start with the Policy System Overview.

Invariants: every Policy API call must carry tenant context and operate on frozen inputs. Mutating endpoints require Authority scopes and emit 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-StellaOps-TenantId (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, and cursors hashes.

Related

• Policy System Overview — language, lifecycle, and evidence inputs.
• Policy lifecycle — draft → submit → approve → publish → activate gates.
• Policy runs — simulate/run mechanics and explain traces.