Policy Queries and Draft Operations

These application programming interface (API) operations inspect and save policy work. Use POLICY_API and the protected POLICY_AUTH_HEADER file from authentication. Saved drafts, governed revisions, and protection states remain independent. Response examples show relevant fields, not every optional property.

Use the policy identifier in {policy_id} paths, including draft commands. Set POLICY_ID to that identifier before running examples for an existing policy. The separate draftPolicyId identifies the stable Draft Policy, not a replacement path identifier. The draft summary’s cycleNumber identifies its authoring cycle. Each save records a draft snapshot. Repeated saves do not create new proposed major revisions. Approval establishes a governed revision. A compilation minor identifies output within that approved revision. Neither snapshot identifiers nor revision numbers replace server-issued validators.

GET /policies

List visible policy summaries and aggregate counters. The backend permits optional identity for this compatibility read. Gateway access rules still apply. Accept no body or path parameters.

The following table lists supported query parameters and their types and behavior:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies?limit=20&offset=0&view=latest"

Return 200 with total, dataCount, aiCount, approvedCount, draftCount, and a policies array. Each summary identifies id, compatibility status, source, and independent policyState, draftState, and enforcementState values. Additional fields describe names, scope, method, validation, and available actions.

governedRevision identifies the approved major revision. governedMinorVersion identifies compilation output within that revision. draftPolicyId, draftCycleNumber, and proposedRevisionNumber identify open draft work. hasOpenDraft distinguishes an approved policy with a replacement proposal. validationStatus describes authoritative, unavailable, or stale saved validation. operationIssue summarizes delayed or failed delivery. availableActions lists actions offered to the caller. A command can still fail if permissions or policy content change after the read.

Counters use the search-filtered set before the status filter. For bounded reads, send limit and offset explicitly and retain the same filters and view on later pages. Do not use aggregate counters as page lengths. includeProtection=true queries the integrations for current protection observations and can take longer than a stored-state read. Gateway failures can return 401 or 403. Malformed query values return 422. Dependency failures can return 503. Server failures can return 500.

GET /policies/{policy_id}

Inspect one policy’s full content and independent state projections. Require the policy_id path string. Accept no body. Support the same includeProtection and view query options as listing. The backend permits optional identity. Gateway access rules still apply.

curl --fail-with-body -i -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}?view=latest"

Return 200 with a policy object. The object includes id, readableName, version, status, authored fields, trusted actor attribution, validation findings, and independent state projections. Imported external records can expose origin, displayOnly, and editable. includeProtection=true can populate protectionConfirmation. The response supplies the policy ETag and, when available, Draft-ETag. Draft commands require the latter. Use view=latest to inspect current proposal content before a draft command. Use view=governed to inspect approved content while a replacement draft remains open. A policy’s approved governance state does not make its open draft approved.

{
  "policy": {
    "id": "policy-1",
    "status": "approved",
    "policyState": "approved",
    "governedRevision": 3,
    "governedMinorVersion": 1,
    "hasOpenDraft": true,
    "draftState": "in_review",
    "enforcementState": "enforced"
  }
}

Return 404 for an unknown policy. Gateway failures can return 401 or 403. Invalid query values return 422. Live integration failures can return 503. Server failures can return 500.

POST /policies

Create a new policy identity and its first saved draft. Require policy:edit. Accept no path or query parameters. Creation grants policy ownership to the authenticated creator. No prior validator or idempotency key applies.

The application/json body rejects extra fields:

Policy recomputes validation from compileRequest. Client conflict lists and client lifecycle states cannot bypass those checks. Do not send status, createdBy, or another actor. Refer to worked example for a complete create payload.

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @create-policy.json \
  "${POLICY_API}/policies"

Return 201 with the full policy object and policy/draft validator headers. Save can retain incomplete work and findings. It does not guarantee submission eligibility. Return 401 or 403 for identity or edit failures, 422 for invalid input, or 500 for server failures. After a timeout, list policies and check the matching policy’s detail and history before creating another policy.

PUT /policies/{policy_id}

Save, open, or restore draft work. Require the policy_id path string and current Draft-ETag through If-Match. Accept no query parameters. Normal editing requires policy:edit plus an active owner/editor grant. Rollback requires policy:rollback plus that grant. Authorized recovery overrides remain audited.

The application/json body supports three forms:

sourceVersion is an integer governed revision number, at least one. reason accepts 1–512 characters. confirmDraftVersionId identifies the exact current snapshot that rollback replaces. Obtain that identifier from the current draft summary’s currentVersionId or saved validation’s draftVersionId. It differs from sourceVersion, which selects the governed revision to restore. Never send compileRequest alongside sourceVersion. Rollback restores server-held governed content into a new in-review draft. It does not immediately replace the currently governed revision. The body rejects unknown fields, including direct lifecycle-state changes.

Before running this normal-save example, prepare update-policy.json with the complete current compileRequest. Use the worked payload construction for its shape, and retain the authored fields you intend to save. Obtain DRAFT_ETAG from a current policy read before sending the request.

curl --fail-with-body -X PUT \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${DRAFT_ETAG}" \
  --data-binary @update-policy.json \
  "${POLICY_API}/policies/${POLICY_ID}"

Return 200 with the full policy and latest policy/draft validators. Saving replacement work preserves the existing governed revision and delivery. Return the following error codes:

• 400 for the wrong token type.
• 401 or 403 for authority failures.
• 404 for missing context.
• 409 for a changed head or illegal state.
• 412 for persistence races.
• 422 for invalid input.
• 428 for a missing token.

GET /policies/{policy_id}/validation

Revalidate the exact saved draft snapshot. Require policy:review, not merely authorship or an owner/editor grant. Require the policy_id path string. Accept no body or query parameters. This read requires no If-Match.

curl --fail-with-body -i -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/validation"

Return 200 with:

The Draft-ETag header identifies the same saved head. Policy excludes archived policies from cross-policy conflict snapshots. Return the following error codes:

• 401 or 403 for identity or review failures.
• 404 without a draft.
• 409 without a current saved snapshot or after a concurrent head change.
• 422 for invalid saved compile input.

Server failures can return 500. After a changed-head response, reread and review before deciding.

DELETE /policies/{policy_id}

Cancel the open draft cycle without deleting retained history. Require policy:edit and an active owner/editor grant, or an audited recovery override. Require the policy_id path string and current draft token through If-Match. Accept no body or query parameters.

curl --fail-with-body -X DELETE \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "If-Match: ${DRAFT_ETAG}" \
  "${POLICY_API}/policies/${POLICY_ID}"

Return 200 with the restored full policy. An existing governed revision remains current. Previous draft snapshots remain in history. This operation does not archive governed protection or erase audit evidence. Return 400, 401, 403, 404, 409, 412, or 428 for token, authority, missing-context, state, or concurrency failures.