Policy Engine API Reference

Operations

GET /

Responses:

GET /.well-known/risk-profile-schema

Get the JSON Schema for risk profile definitions.

Serve the canonical JSON Schema for risk profile documents at the well-known discovery URL, including ETag and cache-control headers for efficient polling. Returns 304 Not Modified when the schema version matches the client’s cached ETag.

Responses:

GET /api/cvss/policies

List available CVSS policies configured on this host.

List all CVSS scoring policies registered on this host, including their identifiers, algorithm configurations, and deterministic hash values, enabling clients to select the appropriate policy when creating CVSS receipts.

Responses:

POST /api/cvss/receipts

Create a CVSS v4.0 receipt with deterministic hashing and optional DSSE attestation.

Create a CVSS v4.0 score receipt for a vulnerability, computing a deterministic hash over the base, threat, environmental, and supplemental metrics using the specified scoring policy. Optionally wraps the receipt in a DSSE attestation envelope if a signing key is provided.

Responses:

GET /api/cvss/receipts/{receiptId}

Retrieve a CVSS v4.0 receipt by ID.

Retrieve a stored CVSS v4.0 score receipt by its identifier, returning the full metric values, computed score vector, deterministic hash, and DSSE attestation envelope if present.

Parameters:

Responses:

PUT /api/cvss/receipts/{receiptId}/amend

Append an amendment entry to a CVSS receipt history and optionally re-sign.

Append an immutable amendment record to a CVSS receipt’s history, recording the changed field, previous and new values, reason, and optional reference URI. Optionally re-signs the updated receipt with a new DSSE envelope to chain attestation integrity.

Parameters:

Responses:

GET /api/cvss/receipts/{receiptId}/history

Return the ordered amendment history for a CVSS receipt.

Retrieve the chronologically ordered amendment history for a CVSS score receipt, listing each recorded field change with actor, timestamp, reason, and reference URI for audit and compliance review.

Parameters:

Responses:

GET /api/policy/compliance/cra/technical-documentation/provenance/{tenantId}

Get the latest tenant CRA technical-documentation export provenance.

Returns the latest Policy-owned CRA technical-documentation provenance projection for the authenticated tenant. Missing rows return status missing; rows whose fields all lack sourceRef return status unprovenanced.

Parameters:

Responses:

POST /api/policy/compliance/cra/technical-documentation/provenance/{tenantId}

Store a tenant CRA technical-documentation export provenance projection.

Stores the Policy-owned projection supplied by the CRA export workflow. The endpoint preserves null provenance values and does not derive values from unrelated Policy exports.

Parameters:

Responses:

GET /api/policy/conflicts

List open policy conflicts sorted by severity.

List all open policy rule conflicts for the authenticated tenant, sorted by severity. Conflicts arise when two or more policy rules produce contradictory verdicts for the same advisory or component scope. Supports pagination via limit and offset parameters.

Parameters:

Responses:

POST /api/policy/conflicts

Report a new policy conflict.

Report a newly detected policy rule conflict, recording the conflicting rule identifiers, conflict type, severity, affected scope, and a human-readable description. The conflict is created in open status and queued for resolution or dismissal.

Responses:

GET /api/policy/conflicts/by-type/{conflictType}

Get conflicts filtered by type.

Retrieve policy conflicts filtered to a specific conflict type (e.g., severity-mismatch, applicability-overlap), with optional status filtering and pagination. Used by the conflict management console to focus on a specific category of rule contradictions.

Parameters:

Responses:

GET /api/policy/conflicts/stats/by-severity

Get open conflict counts grouped by severity.

Retrieve a count of currently open policy conflicts grouped by severity level for the authenticated tenant. Used by compliance dashboards to render conflict health indicators and track remediation progress.

Responses:

GET /api/policy/conflicts/{conflictId}

Get a specific policy conflict by ID.

Retrieve the full record of a specific policy conflict by its UUID, including the conflicting rule identifiers, affected scope, severity, status, and description explaining the nature of the contradiction.

Parameters:

Responses:

POST /api/policy/conflicts/{conflictId}:dismiss

Dismiss an open conflict without resolution.

Dismiss an open policy conflict without providing a resolution, recording the dismissing actor. Dismissed conflicts are closed without a resolution record and excluded from open conflict counts.

Parameters:

Responses:

POST /api/policy/conflicts/{conflictId}:resolve

Resolve an open conflict with a resolution description.

Mark an open policy conflict as resolved by providing a resolution description explaining how the contradiction was addressed, recording the resolving actor. Only conflicts in open status can be resolved.

Parameters:

Responses:

GET /api/policy/control-register/frameworks/{frameworkId}

List a tenant-scoped Assurance control register by framework id.

Returns a framework-aware Assurance control-register projection. NIS2 is currently served as the first adapter over Policy-owned control-register rows; unknown frameworks fail closed.

Parameters:

Responses:

GET /api/policy/control-register/nis2

List the tenant-scoped NIS2 control register.

Returns Policy-owned NIS2 control-register mappings for the resolved tenant, including thirteen thematic area summaries, responsible roles, review status, evidence references, tenant override references, lifecycle event ids, and deterministic cursor pagination.

Parameters:

Responses:

POST /api/policy/deltas/compute

Compute a security state delta between a baseline snapshot and a target snapshot for a given artifact digest. Selects the baseline automatically using the configured strategy (last-approved, previous-build, production-deployed, or branch-base) unless an explicit baseline snapshot ID is provided. Returns a delta summary and driver count for downstream evaluation.

Responses:

GET /api/policy/deltas/{deltaId}

Retrieve a previously computed security state delta by its ID from the in-memory cache. Deltas are retained for 30 minutes after computation. Returns the full driver list, baseline and target snapshot IDs, and risk summary.

Parameters:

Responses:

GET /api/policy/deltas/{deltaId}/attestation

Retrieve a signed attestation envelope for a delta verdict, combining the security state delta with its evaluated verdict and producing a cryptographically signed in-toto statement. Requires that the delta has been evaluated via POST /{deltaId}/evaluate before an attestation can be generated.

Parameters:

Responses:

POST /api/policy/deltas/{deltaId}/evaluate

Evaluate a previously computed delta and produce a gate verdict. Classifies each driver as blocking or advisory based on severity and type (new-reachable-cve, lost-vex-coverage, new-policy-violation), applies any supplied exception IDs, and returns a recommended gate action with risk points and remediation recommendations.

Parameters:

Responses:

GET /api/policy/exceptions

List policy exceptions with optional filtering by status, type, vulnerability ID, PURL pattern, environment, or owner. Returns paginated results including per-item status, scope, and lifecycle timestamps for exception management dashboards and compliance reporting.

Parameters:

Responses:

POST /api/policy/exceptions

Create a new policy exception in the proposed state. Validates that the expiry is in the future and does not exceed one year, captures the requesting actor from the authenticated identity, and records the scope (artifact digest, PURL pattern, vulnerability ID, or policy rule), reason code, rationale, and compensating controls.

Responses:

GET /api/policy/exceptions/counts

Return aggregate counts of exceptions by lifecycle status (proposed, approved, active, expired, revoked) plus an expiring-soon indicator. Used by governance dashboards to give operators a quick view of the exception portfolio health without fetching the full list.

Responses:

GET /api/policy/exceptions/expiring

List active exceptions that will expire within the specified number of days (default 7). Used by notification and alerting workflows to proactively alert owners before exceptions lapse and cause unexpected policy failures.

Parameters:

Responses:

GET /api/policy/exceptions/{id}

Retrieve the full details of a single exception by its identifier, including scope, rationale, evidence references, compensating controls, and lifecycle timestamps.

Parameters:

Responses:

PUT /api/policy/exceptions/{id}

Update the mutable fields of an existing exception (rationale, evidence references, compensating controls, ticket reference, and metadata). Cannot update expired or revoked exceptions. Version is incremented and the updated-at timestamp is refreshed on every successful update.

Parameters:

Responses:

DELETE /api/policy/exceptions/{id}

Revoke an exception before its natural expiry, recording an optional revocation reason and transitioning the exception to the revoked terminal state. Cannot revoke exceptions that are already expired or revoked.

Parameters:

Responses:

POST /api/policy/exceptions/{id}/activate

Transition an approved exception to the active state, making it eligible for use in policy evaluation. Only exceptions in the approved state may be activated.

Parameters:

Responses:

POST /api/policy/exceptions/{id}/approve

Approve a proposed exception and transition it to the approved state. Enforces separation-of-duty by rejecting self-approval (approver must differ from the requester). Multiple approvers may be recorded before the exception is activated.

Parameters:

Responses:

POST /api/policy/exceptions/{id}/extend

Extend the expiry date of an active exception. The new expiry must be later than the current expiry. Used when a scheduled fix or mitigation requires additional time beyond the original exception window.

Parameters:

Responses:

GET /api/policy/exceptions/{id}/history

Retrieve the ordered audit history of an exception, including every status transition, the actor who performed each action, and descriptive event entries. Supports compliance reviews and traceability of the full exception lifecycle from proposal through resolution.

Parameters:

Responses:

GET /api/policy/packs

List policy packs for the current tenant.

List all policy pack containers for the authenticated tenant, returning summaries of each pack including available revision versions and their current activation status.

Responses:

POST /api/policy/packs

Create a new policy pack container.

Create a new policy pack container with an optional display name, establishing the versioned identity under which subsequent policy revisions and compiled bundles will be registered.

Responses:

POST /api/policy/packs/{packId}/revisions

Create or update policy revision metadata.

Create or upsert a policy revision entry under a given pack, setting initial status (Draft or Approved) and two-person approval requirements that govern the activation workflow for that revision.

Parameters:

Responses:

POST /api/policy/packs/{packId}/revisions/{version}/bundle

Compile and sign a policy revision bundle for distribution.

Compile a policy DSL source attached to a revision into a signed, immutable bundle ready for distribution and evaluation. Returns the bundle digest and compilation statistics; fails fast if the DSL contains syntax errors or rule conflicts.

Parameters:

Responses:

POST /api/policy/packs/{packId}/revisions/{version}/evaluate

Evaluate a policy revision deterministically with in-memory caching.

Evaluate a compiled policy revision bundle against a provided advisory/VEX/SBOM context, returning a deterministic verdict with per-rule outcomes. Results are cached in-memory for subsequent identical evaluations to reduce compute overhead during iterative authoring.

Evaluation evidence matches[] includes matchClass: denylist for presence-based CVE-id rule citations and reachability for callability-backed citations once the reachability evaluator path is wired.

Parameters:

Responses:

POST /api/policy/packs/{packId}/revisions/{version}:activate

Activate an approved policy revision, enforcing two-person approval when required.

Promote an approved policy revision to active status, recording the activating actor and enforcing two-person approval workflows when configured. Returns 202 Accepted when a second approval is still pending, or 200 OK when the revision is fully activated.

Parameters:

Responses:

POST /api/policy/policies/{policyId}/versions/{version}:compile

Compile and lint a policy DSL document.

Compiles a stella-dsl@1 policy document and returns deterministic digest and statistics.

Parameters:

Responses:

GET /api/policy/quota

Responses:

GET /api/policy/snapshots

List policy evaluation snapshots for the specified tenant, returning snapshot identifiers, creation timestamps, and summary component counts for use in batch evaluation workflows. Supports cursor-based pagination.

Parameters:

Responses:

POST /api/policy/snapshots

Create a new policy evaluation snapshot from a component manifest, capturing PURL set, advisory signals, and applicable policy bundles at a point in time for subsequent policy decision evaluation.

Responses:

GET /api/policy/snapshots/{snapshotId}

Retrieve a specific policy evaluation snapshot by identifier, including its full component graph, resolved advisory signals, and any cached partial evaluation state.

Parameters:

Responses:

GET /api/policy/violations

List policy violations with optional filters.

List persisted policy violation events for the authenticated tenant, with optional filtering by policy ID, severity level, and occurrence timestamp. Defaults to returning critical violations when no filter is specified. Supports pagination via limit and offset parameters.

Parameters:

Responses:

POST /api/policy/violations

Append a new policy violation event (immutable).

Append a single immutable policy violation event to the append-only audit log, recording the triggering policy, rule, severity, subject identifier, and occurrence timestamp. Violation records cannot be modified or deleted after creation.

Responses:

POST /api/policy/violations/batch

Append multiple policy violation events in a batch.

Atomically append a batch of immutable policy violation events to the audit log in a single request, reducing per-event overhead during high-throughput evaluation runs. Returns the count of successfully appended records.

Responses:

GET /api/policy/violations/by-policy/{policyId}

Get violations for a specific policy.

Retrieve all policy violation events associated with a specific policy UUID, supporting optional time-range filtering and offset-based pagination for audit trail review of a single policy’s violation history.

Parameters:

Responses:

GET /api/policy/violations/by-purl/{purl}

Get violations for a specific package (by PURL).

Retrieve all policy violation events for a specific package identified by its URL-encoded Package URL (PURL), enabling component-centric compliance queries and remediation tracking across all policies that flagged the component.

Parameters:

Responses:

GET /api/policy/violations/by-severity/{severity}

Get violations filtered by severity level.

Retrieve policy violation events filtered to a specific severity level (critical, high, medium, low), optionally bounded by a start timestamp, enabling targeted monitoring dashboards and severity-specific alert pipelines.

Parameters:

Responses:

GET /api/policy/violations/stats/by-severity

Get violation counts grouped by severity.

Compute aggregated violation counts grouped by severity level (critical, high, medium, low, none) for a specified time window. Used by compliance dashboards to render severity distribution charts and trend indicators.

Parameters:

Responses:

GET /api/policy/violations/{violationId}

Get a specific policy violation by ID.

Retrieve the full immutable record of a specific policy violation event by its UUID, including the triggering rule, severity, subject PURL or CVE, details payload, and occurrence timestamp.

Parameters:

Responses:

GET /api/risk/events

Get recent profile lifecycle events.

Retrieve the most recent risk profile lifecycle events across all profiles, ordered by descending timestamp, up to the specified limit. Events include profile creation, activation, deprecation, archival, and override changes.

Parameters:

Responses:

GET /api/risk/events/filter

Get profile events with optional filtering.

Retrieve risk profile lifecycle events filtered by event type, profile ID, and a start timestamp, enabling targeted event streams for monitoring pipelines and compliance queries that need only a subset of event types.

Parameters:

Responses:

POST /api/risk/events/subscribe

Subscribe to profile lifecycle events.

Create a named subscription to one or more profile lifecycle event types, optionally filtered by profile ID. Subscriptions can optionally specify a webhook URL for push delivery; otherwise, events are accumulated for polling via the poll endpoint.

Responses:

DELETE /api/risk/events/subscribe/{subscriptionId}

Unsubscribe from profile lifecycle events.

Remove a profile lifecycle event subscription by its identifier, stopping future event delivery and releasing any buffered events associated with the subscription.

Parameters:

Responses:

GET /api/risk/events/subscribe/{subscriptionId}/poll

Poll for events from a subscription.

Poll a profile lifecycle event subscription for accumulated events since the last poll, returning up to the specified limit. Returns an empty list if no new events are available; the subscription state is not modified by polling.

Parameters:

Responses:

POST /api/risk/overrides

Create a new override with audit metadata.

Create a risk profile override to alter severity, action, or signal values for a specific advisory or component pattern, recording the rationale, author, and expiry for the audit log. Automatically validates for conflicts with existing overrides before persisting.

Responses:

GET /api/risk/overrides/profile/{profileId}

List all overrides for a risk profile.

List all overrides registered for a specific risk profile, optionally including inactive overrides. Returns each override’s type, target, value, approval status, and audit metadata for management and review.

Parameters:

Responses:

POST /api/risk/overrides/validate

Validate an override for conflicts before creating.

Validate a proposed override definition against existing overrides to detect conflicts, returning conflict descriptions and advisory warnings. Call this before creating an override to surface issues without committing the override.

Responses:

GET /api/risk/overrides/{overrideId}

Get an override by ID.

Retrieve the full definition of a risk override by its identifier, including the override type, target pattern, value, approval status, author, and audit trail metadata.

Parameters:

Responses:

DELETE /api/risk/overrides/{overrideId}

Delete an override.

Permanently remove a risk override by its identifier. The override will no longer be applied in subsequent evaluations for the affected risk profile.

Parameters:

Responses:

GET /api/risk/overrides/{overrideId}/history

Get application history for an override.

Retrieve the chronological application history for a specific override, showing each time the override was applied during an evaluation run, the matching finding, and the resulting value change.

Parameters:

Responses:

POST /api/risk/overrides/{overrideId}:approve

Approve an override that requires review.

Approve a pending override that was created with a review requirement, recording the approving actor and transitioning the override to active status. Fails if the override has already been approved by the same actor or is not in a pending state.

Parameters:

Responses:

POST /api/risk/overrides/{overrideId}:disable

Disable an active override.

Disable an active override without deleting it, recording the disabling actor and an optional reason. Disabled overrides are preserved in the audit log and can be queried by history endpoints but are excluded from active evaluations.

Parameters:

Responses:

GET /api/risk/profiles

List all available risk profiles.

List all registered risk profiles for the current tenant, returning each profile’s identifier, current version, and description. Used by the policy console and advisory pipeline to discover which profiles are available for evaluation binding.

Responses:

POST /api/risk/profiles

Create a new risk profile version in draft status.

Register a new risk profile version in Draft lifecycle status, recording the authoring actor and creation timestamp. The profile must be activated before it can be used in live policy evaluations.

Responses:

POST /api/risk/profiles/compare

Compare two risk profile versions and list differences.

Compute a structured diff between two risk profile versions, listing added, removed, and modified signal weights and override rules. Used by policy authors to validate the impact of profile changes before promoting to active.

Responses:

POST /api/risk/profiles/export

Export risk profiles as a signed bundle.

Export one or more risk profiles into a cryptographically signed bundle suitable for distribution across air-gap boundaries or cross-environment synchronization. Returns the full bundle structure including the content hash and signing metadata.

Responses:

POST /api/risk/profiles/export/download

Export and download risk profiles as a JSON file.

Export one or more risk profiles into a signed bundle and return it as a downloadable JSON file attachment, enabling operators to transfer profiles to disconnected environments without API client tooling.

Responses:

POST /api/risk/profiles/import

Import risk profiles from a signed bundle.

Import risk profiles from a previously exported signed bundle, verifying the bundle signature and registering each included profile in the local store. Replaces existing profiles with matching IDs if permitted by the import options.

Responses:

POST /api/risk/profiles/verify

Verify the signature of a profile bundle without importing.

Verify the cryptographic signature and content hash of a risk profile bundle without importing any profiles, allowing operators to validate bundle integrity before committing to an import operation.

Responses:

GET /api/risk/profiles/{profileId}

Get a risk profile by ID.

Retrieve the full definition of a risk profile by identifier, including signal weights, severity override rules, and the deterministic profile hash used for reproducible evaluation runs.

Parameters:

Responses:

GET /api/risk/profiles/{profileId}/events

Get lifecycle events for a risk profile.

Retrieve the ordered lifecycle event log for a risk profile, including creation, activation, deprecation, and archival events with actor and timestamp information, supporting compliance reporting and change history review.

Parameters:

Responses:

GET /api/risk/profiles/{profileId}/hash

Get the deterministic hash of a risk profile.

Compute and return the deterministic hash of a risk profile, optionally restricted to content-only hashing (excluding metadata). Used to verify profile identity across environments and ensure reproducible evaluation inputs.

Parameters:

Responses:

GET /api/risk/profiles/{profileId}/metadata

Export risk profile metadata for notification enrichment (POLICY-RISK-40-002).

Export a compact metadata summary of a risk profile including signal names, severity thresholds, active version info, and custom metadata fields. Used by the notification enrichment pipeline to annotate policy-triggered alerts with human-readable risk context.

Parameters:

Responses:

GET /api/risk/profiles/{profileId}/versions

List all versions of a risk profile.

List the full version history of a risk profile, including lifecycle status (Draft, Active, Deprecated, Archived), activation timestamps, and actor identities for each version, supporting compliance audit trails.

Parameters:

Responses:

GET /api/risk/profiles/{profileId}/versions/{version}

Get a specific version of a risk profile.

Retrieve the complete definition and lifecycle metadata for a specific versioned risk profile, including its deterministic hash and version info record, enabling exact-version lookups during policy replay and audit verification.

Parameters:

Responses:

POST /api/risk/profiles/{profileId}/versions/{version}:activate

Activate a draft risk profile, making it available for use.

Transition a Draft risk profile version to Active status, making it available for binding to policy evaluation runs. Records the activating actor and timestamps the transition for the lifecycle audit log.

Parameters:

Responses:

POST /api/risk/profiles/{profileId}/versions/{version}:archive

Archive a risk profile, removing it from active use.

Transition a risk profile version to Archived status, permanently removing it from active evaluation use while preserving the definition and lifecycle record for historical audit queries.

Parameters:

Responses:

POST /api/risk/profiles/{profileId}/versions/{version}:deprecate

Deprecate an active risk profile.

Mark an active risk profile version as Deprecated, optionally specifying a successor version and a human-readable reason. Deprecated profiles remain queryable for audit but are excluded from new evaluation bindings.

Parameters:

Responses:

POST /api/risk/schema/validate

Validate a risk profile document against the schema.

Validate a submitted risk profile JSON document against the canonical schema, returning a structured list of validation issues including the instance path, error keyword, and human-readable message for each violation. Used by editors and CI pipelines to pre-flight profile authoring before submission.

Responses:

GET /api/risk/scopes/attachments

List scope attachments with optional filtering.

List risk profile scope attachments with optional filtering by scope type, scope ID, profile ID, and expiry status. Supports pagination via the limit parameter. Used by the console and scope resolution pipeline to discover active bindings.

Parameters:

Responses:

POST /api/risk/scopes/attachments

Attach a risk profile to a scope (organization, project, environment, or component).

Create a scope attachment that binds a risk profile to a specific organizational scope (organization, project, environment, or component), optionally with an expiry time. The attached profile is used for policy evaluation within that scope during the attachment’s active lifetime.

Responses:

GET /api/risk/scopes/attachments/{attachmentId}

Get a scope attachment by ID.

Retrieve the details of a specific scope attachment by its identifier, including the bound risk profile, target scope type and ID, and the attachment’s active and expiry timestamps.

Parameters:

Responses:

DELETE /api/risk/scopes/attachments/{attachmentId}

Delete a scope attachment.

Permanently remove a risk profile scope attachment by its identifier. The associated risk profile will no longer be applied to evaluations within the previously bound scope after deletion.

Parameters:

Responses:

POST /api/risk/scopes/attachments/{attachmentId}:expire

Expire a scope attachment immediately.

Immediately expire a risk profile scope attachment, recording the expiry actor and timestamp without deleting the attachment record. Expired attachments are excluded from scope resolution but remain queryable for audit purposes.

Parameters:

Responses:

POST /api/risk/scopes/resolve

Resolve the effective risk profile for a given scope selector.

Resolve the highest-priority active risk profile attachment for a given scope selector, walking the scope hierarchy (component -> environment -> project -> organization) until an active attachment is found. Used by the evaluation pipeline to determine which profile governs a specific component.

Responses:

GET /api/risk/scopes/{scopeType}/{scopeId}/attachments

Get all attachments for a specific scope.

Retrieve all risk profile attachments bound to a specific scope identified by type and ID, including both active and expired attachments, for use in scope management UIs and audit reviews.

Parameters:

Responses:

POST /api/risk/simulation

Run a risk simulation with score distributions and contribution breakdowns.

Evaluate a set of advisory findings against a specified risk profile, returning per-finding normalized scores, severity assignments, recommended actions, aggregate metrics, and an optional score distribution histogram. Used by policy authors and CI pipelines to validate risk posture against a profile.

Responses:

POST /api/risk/simulation/compare

Compare risk scoring between two profile configurations.

Simulate the same set of findings against two different risk profiles and compute delta metrics showing how mean score, median score, and severity distribution counts differ between the baseline and comparison profiles. Used by policy authors to evaluate the impact of profile changes before promoting.

Responses:

POST /api/risk/simulation/quick

Run a quick risk simulation without detailed breakdowns.

Run a lightweight risk simulation returning only aggregate metrics and score distribution without per-finding contribution details. Optimized for high-frequency calls where summary statistics are sufficient and per-finding breakdown overhead is not justified.

Responses:

POST /api/risk/simulation/studio/analyze

Run a detailed analysis for Policy Studio with full breakdown analytics.

Provides comprehensive breakdown including signal analysis, override tracking, score distributions, and component breakdowns for policy authoring.

Responses:

POST /api/risk/simulation/studio/compare

Compare profiles with full breakdown analytics and trend analysis.

Compare two risk profiles using full breakdown analytics, returning per-signal contribution deltas, override tracking, and severity distribution shifts between baseline and comparison. Used by Policy Studio to render side-by-side profile comparison views with detailed analytical overlays.

Responses:

POST /api/risk/simulation/studio/preview

Preview impact of profile changes before committing.

Simulates findings against both current and proposed profile to show impact.

Responses:

POST /api/risk/simulation/whatif

Run a what-if simulation with hypothetical signal changes.

Run a baseline simulation and then re-run with hypothetical signal value overrides applied to specified findings, returning both results and an impact summary counting improved, worsened, and unchanged findings. Supports pre-remediation planning and remediation impact assessment.

Responses:

GET /api/v1/advisory-sources/{sourceId}/conflicts

Get active/resolved advisory conflicts for a source.

Parameters:

Responses:

GET /api/v1/advisory-sources/{sourceId}/impact

Get policy impact facts for an advisory source.

Parameters:

Responses:

GET /api/v1/airgap/bundles

List all policy pack bundles registered for a tenant, including their import status, source metadata, and processing timestamps, for use by air-gap operation consoles monitoring bundle delivery pipelines.

Responses:

POST /api/v1/airgap/bundles

Register a policy pack bundle for air-gap import, validating the bundle structure and enforcing sealed-mode preconditions. Returns 412 Precondition Failed when sealed-mode blocks the import and 403 Forbidden when the bundle origin is not trusted.

Responses:

GET /api/v1/airgap/bundles/{bundleId}

Retrieve the import status of a registered policy pack bundle by its import ID, including processing state, any validation errors, and metadata extracted from the bundle manifest.

Parameters:

Responses:

POST /api/v1/airgap/risk-profiles/export

Export risk profiles as an air-gap compatible bundle with signatures.

Export one or more risk profiles into an air-gap compatible bundle format with optional cryptographic signing and Merkle tree integrity protection, ready for transfer to a disconnected environment per CONTRACT-MIRROR-BUNDLE-003.

Responses:

POST /api/v1/airgap/risk-profiles/export/download

Export and download risk profiles as an air-gap compatible JSON file.

Export risk profiles into an air-gap bundle and return it as a downloadable JSON file attachment, enabling operators to transfer profiles to offline environments without additional tooling beyond a standard HTTP client.

Responses:

POST /api/v1/airgap/risk-profiles/import

Import risk profiles from an air-gap bundle with sealed-mode enforcement.

Import risk profiles from an air-gap bundle with configurable signature verification, Merkle integrity checking, and sealed-mode enforcement. Returns 412 Precondition Failed when sealed-mode prevents the import, and records the import attempt for the air-gap audit log.

Parameters:

Responses:

POST /api/v1/airgap/risk-profiles/verify

Verify the integrity of an air-gap bundle without importing.

Verify the cryptographic signature and Merkle tree integrity of an air-gap risk profile bundle without performing an import, enabling pre-flight validation before committing to the import operation in sealed environments.

Responses:

GET /api/v1/attestor/policies

List verification policies

List all registered attestation verification policies, optionally filtered by tenant scope. Used by the attestor service and policy console to discover available verification constraints for each tenant context.

Parameters:

Responses:

POST /api/v1/attestor/policies

Create a new verification policy

Create a new attestation verification policy specifying accepted predicate types, signer requirements, validity windows, and tenant scope. Returns the created policy record with its assigned identifier for use in attestation verification workflows.

Responses:

POST /api/v1/attestor/policies/editor/clone

Clone a verification policy

Create a new verification policy by cloning an existing policy, preserving the source definition while assigning a new identifier and optionally overriding the version string. Useful for creating policy variants without manual duplication.

Responses:

POST /api/v1/attestor/policies/editor/compare

Compare two verification policies

Compute a field-level diff between two verification policies, listing added, removed, and modified predicate types, signer requirements, key fingerprints, and validity window settings. Used by the policy editor and review workflows to highlight changes before promotion.

Responses:

GET /api/v1/attestor/policies/editor/metadata

Get editor metadata for verification policy forms

Retrieve static metadata used to populate verification policy editor forms, including available predicate types, signer algorithm options, and validation rule documentation. Used by the UI to render dynamic form fields without hardcoding policy schema knowledge.

Responses:

POST /api/v1/attestor/policies/editor/validate

Validate a verification policy without persisting

Validate a verification policy definition against all structural and semantic rules without persisting it to the store. Returns errors, warnings, and authoring suggestions so policy authors can correct issues in the editor before saving.

Responses:

GET /api/v1/attestor/policies/editor/{policyId}

Get a verification policy with editor metadata

Retrieve a verification policy combined with its current validation state, authoring suggestions, and editor permissions (such as whether the policy can be deleted). Used by the UI editor to render the policy form in its current persisted state.

Parameters:

Responses:

GET /api/v1/attestor/policies/{policyId}

Get a verification policy by ID

Retrieve a specific attestation verification policy by its identifier, returning the full policy definition including predicate type filters, signer requirements, and validity window configuration.

Parameters:

Responses:

PUT /api/v1/attestor/policies/{policyId}

Update a verification policy

Update the mutable fields of an existing attestation verification policy, including predicate types, signer requirements, validity window, and custom metadata. Preserves the policy identifier and creation timestamp while updating the modification timestamp.

Parameters:

Responses:

DELETE /api/v1/attestor/policies/{policyId}

Delete a verification policy

Permanently remove an attestation verification policy by identifier. Deleted policies are no longer applied in verification runs; existing attestation records that referenced this policy are not retroactively affected.

Parameters:

Responses:

DELETE /api/v1/attestor/reports/expired

Purge expired attestation reports

Remove all attestation reports that have exceeded their configured time-to-live from the report store. Returns the count of purged records; intended for scheduled maintenance to bound storage growth over time.

Responses:

POST /api/v1/attestor/reports/query

Query attestation reports

Query the attestation report store with flexible filters including artifact digests, URI patterns, policy IDs, predicate types, status, and time range. Supports paginated retrieval of report summaries or full detail records for audit and compliance review.

Responses:

GET /api/v1/attestor/reports/statistics

Get aggregated attestation statistics

Retrieve aggregated attestation statistics across the report store, including pass/fail counts per policy and predicate type, optionally filtered by time range. Used by the console dashboard to render attestation health metrics.

Parameters:

Responses:

POST /api/v1/attestor/reports/store

Store an attestation report

Persist a pre-computed attestation report into the report store with an optional time-to-live, making it available for subsequent retrieval and statistics aggregation. Used by the attestor pipeline after completing artifact verification.

Responses:

POST /api/v1/attestor/reports/verify

Generate attestation report for an artifact

Generate a fresh attestation verification report for an artifact by evaluating its attestations against all applicable verification policies. Returns pass/fail status per policy, signer details, and any validation errors encountered during verification.

Responses:

GET /api/v1/attestor/reports/{artifactDigest}

Get attestation report for an artifact

Retrieve the stored attestation report for a specific artifact identified by its digest, including verification status against applicable policies, predicate types present, and signer identity records.

Parameters:

Responses:

GET /api/v1/authority/effective-policies

List effective policies with optional filtering.

List effective policy bindings with optional filtering by tenant, policy ID, enabled-only flag, and expiry inclusion. Returns bindings in priority order, used by the resolution engine and console to display active policy governance assignments.

Parameters:

Responses:

POST /api/v1/authority/effective-policies

Create a new effective policy with subject pattern and priority.

Create a new effective policy binding that associates a policy pack revision with a subject pattern and priority rank, controlling which policy governs releases for matching subjects. Changes are audited per CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008.

Responses:

GET /api/v1/authority/effective-policies/{effectivePolicyId}

Get an effective policy by ID.

Retrieve a specific effective policy binding by its identifier, including the subject pattern, priority, pack reference, and any scope attachments that further restrict the policy’s applicability.

Parameters:

Responses:

PUT /api/v1/authority/effective-policies/{effectivePolicyId}

Update an effective policy’s priority, expiration, or scopes.

Update the mutable fields of an effective policy binding, including priority, expiration date, and scope constraints, without changing the subject pattern or pack reference. All changes are audited per CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008.

Parameters:

Responses:

DELETE /api/v1/authority/effective-policies/{effectivePolicyId}

Delete an effective policy.

Remove an effective policy binding by identifier, stopping the associated policy from governing matching subjects. The deletion is audited and the binding identifier cannot be reused.

Parameters:

Responses:

GET /api/v1/authority/resolve

Resolve the effective policy for a subject.

Resolve the highest-priority enabled effective policy that governs a given subject string, respecting tenant scoping and priority ordering. Returns the resolved policy binding with the matching pack reference, used by the gate and evaluation pipeline at decision time.

Parameters:

Responses:

POST /api/v1/authority/scope-attachments

Attach an authorization scope to an effective policy.

Attach an authorization scope restriction to an effective policy, narrowing its applicability to requests carrying the specified scope claim. Audited per CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008.

Responses:

GET /api/v1/authority/scope-attachments/policy/{effectivePolicyId}

Get all scope attachments for an effective policy.

Retrieve all authorization scope restriction attachments for a specific effective policy, showing which scope claims are required for the policy to apply in each binding context.

Parameters:

Responses:

DELETE /api/v1/authority/scope-attachments/{attachmentId}

Detach an authorization scope.

Remove a scope restriction attachment from an effective policy, allowing the policy to apply to a broader set of authorization scopes. Audited per CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008.

Parameters:

Responses:

GET /api/v1/buildinfo

API alias for /buildinfo.json (same payload).

Responses:

GET /api/v1/export/bundles/{bundleId}

Retrieve the manifest of a completed export bundle including its format, content type, size, and creation timestamp, enabling clients to inspect bundle metadata before initiating a download.

Parameters:

Responses:

GET /api/v1/export/bundles/{bundleId}/download

Download the content of a completed export bundle as a file attachment, with the appropriate content type (JSON or NDJSON) and a timestamped filename. Used by operators to retrieve export data for offline processing or air-gap transfer.

Parameters:

Responses:

GET /api/v1/export/jobs

List console export jobs for the tenant, returning job configuration summaries, current status, and last execution timestamps to support export management dashboards and automation pipelines.

Responses:

POST /api/v1/export/jobs

Create a new console export job defining the data scope, destination, format, and optional schedule. The job is created in a pending state and can be triggered immediately or executed on the configured schedule.

Responses:

GET /api/v1/export/jobs/{jobId}

Retrieve the full configuration and current status of a specific console export job by its identifier, including destination settings, schedule, and format parameters.

Parameters:

Responses:

PUT /api/v1/export/jobs/{jobId}

Update the configuration of an existing console export job, allowing changes to destination, schedule, or format settings while preserving the job’s execution history.

Parameters:

Responses:

DELETE /api/v1/export/jobs/{jobId}

Permanently delete a console export job and release any associated resources. Scheduled future executions will be cancelled; completed execution records and bundles are retained until their configured retention period expires.

Parameters:

Responses:

GET /api/v1/export/jobs/{jobId}/executions/{executionId}

Retrieve the status and metadata of a specific export job execution, including start and end timestamps, byte count, destination path, and any error messages encountered during the export run.

Parameters:

Responses:

POST /api/v1/export/jobs/{jobId}/run

Trigger an immediate execution of a console export job outside its normal schedule, returning an execution ID that can be polled for status. Useful for ad-hoc exports and manual retries after a previous execution failure.

Parameters:

Responses:

POST /api/v1/gate/evaluate

Evaluate a score-based CI/CD release gate for a single security finding using the Evidence Weighted Score (EWS) formula. Computes a composite risk score from CVSS, EPSS, reachability, exploit maturity, patch proof, and VEX status inputs, applies the gate policy thresholds to produce a pass/warn/block action, signs the verdict bundle, and optionally anchors it to a Rekor transparency log. Returns HTTP 403 when the gate action is block.

Responses:

POST /api/v1/gate/evaluate-batch

Batch evaluate score-based CI/CD gates for up to 500 findings in a single request using configurable parallelism. Applies the EWS formula to each finding, produces a per-finding action (pass/warn/block), and returns an aggregate summary with overall action, exit code, and optional per-finding verdict bundles. Supports fail-fast mode to stop processing on the first blocked finding.

Responses:

GET /api/v1/gate/health

Health check for the score-based gate evaluation service

Responses:

GET /api/v1/gates/decisions/{decisionId}

Get a specific gate decision by ID

Retrieve full details of a specific gate decision by its UUID, including BOM reference, image digest, gate status, verdict hash, policy bundle ID and hash, CI/CD context, actor, blocking unknowns, and warnings.

Parameters:

Responses:

GET /api/v1/gates/decisions/{decisionId}/export

Export gate decision in CI/CD format

Export a gate decision in JUnit XML, SARIF 2.1.0, or JSON format for integration with CI/CD pipelines. The JUnit format is compatible with Jenkins, GitHub Actions, and GitLab CI; SARIF is compatible with GitHub Code Scanning and VS Code; JSON provides the full structured decision for custom integrations.

Parameters:

Responses:

GET /api/v1/gates/{bomRef}

Get gate check result for a component

Retrieve the current unknowns state and gate decision for a BOM reference. Returns the aggregate state across all unknowns (resolved, pending, under_review, or escalated), per-unknown band and SLA details, and a cached gate decision. Results are cached for 30 seconds to reduce database load under CI/CD polling.

Parameters:

Responses:

POST /api/v1/gates/{bomRef}/check

Perform gate check for a component

Perform a fresh gate check for a BOM reference with an optional proposed VEX verdict. Returns a pass, warn, or block decision with the list of blocking unknown IDs and the reason for the decision. Returns HTTP 403 when the gate is blocked.

Parameters:

Responses:

POST /api/v1/gates/{bomRef}/exception

Request an exception to bypass the gate

Submit an exception request to bypass blocking unknowns for a BOM reference. Requires a justification and a list of unknown IDs to exempt. Returns an exception record with granted status, expiry, and optional denial reason when auto-approval is not available.

Parameters:

Responses:

GET /api/v1/gates/{gateId}/decisions

Get historical gate decisions

Retrieve a paginated list of historical gate decisions for a gate identifier, with optional filtering by BOM reference, status, actor, and date range. Returns verdict hashes and policy bundle IDs for replay verification and compliance audit.

Parameters:

Responses:

GET /api/v1/governance/audit/events

Return governance audit events, sourced from Timeline’s unified audit store filtered to modules=policy.

Responses:

GET /api/v1/governance/audit/events/{eventId}

Return a governance audit event by id, sourced from Timeline’s unified audit store.

Parameters:

Responses:

GET /api/v1/governance/conflicts