Policy API Reference — Pack Lifecycle
Audience: engineers and operators calling the registered Policy Engine pack/revision API.
Verified against source:
00f64ca4d165fc54e7c291795b65326869b7627d(2026-08-31),Program.MapPolicyPacks,PolicyPackEndpointsandPostgresPolicyPackRepository. Full Policy tests passed1916/1916; this is not live acceptance. See the lifecycle source re-verification commands.
Registered owner API
Paths below are owner-service paths. Derive any gateway prefix from its registered routes; do not prepend the former /api/v1/policies design base.
| Method and path | Scope | Contract |
|---|---|---|
POST /api/policy/packs | policy:edit | packId, optional displayName; creates the tenant pack container. |
GET /api/policy/packs | policy:read | Pack summaries and revision numbers; not a paginated full-review history. |
POST /api/policy/packs/{packId}/revisions | policy:edit | Explicit positive version, initialStatus (Draft or Approved), requiresTwoPersonApproval. |
POST /api/policy/packs/{packId}/revisions/{version}/bundle | policy:edit | Compile/store dsl: { syntax, source }, optional signingKeyId and provenance. |
POST /api/policy/packs/{packId}/revisions/{version}/evaluate | policy:read | Matching body packId, version, and intended subject; explicit bundle evaluation. |
POST /api/policy/packs/{packId}/revisions/{version}:activate | policy:activate | Body with optional comment; Approved state and persisted actor threshold checked. |
GET /policy/capabilities | policy:read | simulation.available, shadowMode.available; source defaults false. |
Use explicit Draft metadata before storing a bundle; omitting initialStatus defaults to Approved. Creating metadata first also resolves the configured activation requirement; upserting an existing revision does not change its stored two-person setting. Follow the lifecycle procedure, including independent governance evidence.
Tenant context comes from validated identity. A caller-supplied tenant header does not grant tenant access. Use actual authenticated activation identities; do not synthesize approvers. Native HTTP and Router dispatch must both populate Policy’s request-local context; the pack group applies RequireTenantContext() for the latter. Missing context is rejected rather than selecting public, and pack reads carry an explicit tenant predicate even when the database role bypasses RLS. Summary visibility does not prove a revision’s activation state.
The related POST /policy/eval/batch route requires policy:read and the same validated tenant context. Its body tenantId must match that identity exactly: omitted/blank values return 400, mismatches return 403 before evaluation or cache access. An operator project claim of * means no project refinement on both HTTP and Router; it never changes tenant.
Responses and limits
- Revision metadata rejects states other than Draft/Approved with HTTP 400.
- Bundle compilation failure returns HTTP 400 with diagnostics. Successful compilation does not approve the revision.
- Evaluation rejects path/body mismatch (400) and missing bundle (404). It does not require Active status and does not establish shadow acceptance.
- Activation returns 202
pending_second_approval, 200activatedor 200already_active. Draft/duplicate actor attempts return 400; missing pack/revision returns 404. - Response revision DTOs carry actual status, activation requirement and approvals. A response
Locationdoes not establish a mapped single-pack/revision GET endpoint. - Activation does not check shadow, coverage, reviewer quorum or bundle presence. It neither schedules a run nor promotes a consumer environment.
- The compile response’s signature is an offline-testing stub, not trusted DSSE publication or reviewer evidence. Metadata/bundle fields are updateable; preserve the reviewed digest.
Unavailable Registry workflow and retained requirements
The former /policies/{id}/submit, /approve, /publish, /archive lifecycle listing was a design description, not this host’s registered API. The separate Registry review and publication services are not registered. The Engine’s /policy/shadow/*, /policy/simulations* and promotion-gate compatibility routes return 501.
Reviewer separation, coverage, shadow/determinism evidence and trusted governed publication remain requirements. Do not report invented policy_shadow_required or attestation-gate responses as implemented checks; do not use Approved metadata to waive those obligations. If an approved procedure cannot supply required evidence, hold the governed operation.
Other run/evaluation APIs must be verified against their own mapped owner endpoints; this reference does not claim the former generic run routes, universal ETags, pagination, file:// handlers or automatic Offline Kit approval exports.