Console Exceptions API Schema

This document defines the request/response shape for the StellaOps Console exceptions surface — the /exceptions CRUD and workflow endpoints proxied by the gateway. It is the contract the Angular Console SDK is generated against.

Audience: Console and SDK developers. For the conceptual overview and the full set of exception API surfaces, see Exceptions API.

Status: interim contract shipped to unblock SDK and UI work. Align to the authoritative Policy/Events schema once it is published.

Scope

• /exceptions CRUD and workflow (create, propose, approve/reject, revoke, list, history), proxied by the gateway.
• Deterministic pagination (continuationToken), stable sorting, and explicit audit trails.

Headers

• X-StellaOps-TenantId (required; legacy aliases: X-StellaOps-Tenant, X-Stella-Tenant)
• X-StellaOps-Project (optional; legacy alias X-Stella-Project is accepted only when the gateway is started with EnableLegacyHeaders=true)
• X-StellaOps-TraceId (required)
• X-StellaOps-RequestId (required; defaults to trace ID)

Scopes

• Read: exceptions:read
• Create/edit: policy:author (the Policy Engine exception create and update routes enforce it; the Console checks it before a create)
• Approve/reject/revoke: exceptions:approve

Endpoints

• GET /exceptions?status=&severity=&search=&sortBy=&sortOrder=&limit=&continuationToken=
• GET /exceptions/{exceptionId}
• POST /exceptions
• PATCH /exceptions/{exceptionId}
• DELETE /exceptions/{exceptionId}
• POST /exceptions/{exceptionId}/transition
• GET /exceptions/stats

Entity shape

This doc mirrors the web contract used by the Angular SDK (src/Web/StellaOps.Web/src/app/core/api/exception.contract.models.ts).

• Sample exception: docs/api/console/samples/exception-schema-sample.json

Status transitions (baseline)

• draft → pending_review (submit)
• pending_review → approved | rejected
• approved → revoked
• approved → expired (timebox lapse; system-driven)

Create request

The Console does not send the entity shape above on create. It maps the draft to the Policy Engine create contract: type, scope (one vulnerability, package URL, artifact digest or policy rule, plus environments), ownerId (the signed-in user), reasonCode, rationale (at least 50 characters), expiresAt and optional metadata, and refuses a draft that contract cannot hold. The mapping is described in Explorer exception draft controls.