# 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.