Deliverable Specs

Operations of the Deliverable Specs API. Paths are relative to your deployment's API host.

GET /api/deliverable-specs-api/deliverable-specs

List active deliverable specs visible to the caller org.

Returns org-scoped custom specs plus every active system spec. Org overrides do NOT hide the system entry — authors see both. Biome-contributed specs are filtered through @xemahq/biome-governance-client against the caller org's OrgBiomeEnablement view; disabled biomes' specs are omitted.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/deliverable-specs-api/deliverable-specs

Publish a caller-owned deliverable spec.

Creates or reactivates a stable caller-owned identity and writes one immutable, server-numbered revision. MARKDOWN_DOCUMENT rejects inline HOW content and may select an explicit templateBinding; other kinds enforce their schema/fetch body. The exact revision is submitted to Resource Governance and projected to skill-registry only after the governed release commits.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateDeliverableSpecDto

GET /api/deliverable-specs-api/deliverable-specs/by-id/{id}

Resolve a caller-owned deliverable spec by stable id.

Resolves an org identity when no authenticated project is active, or an identity in the authenticated project otherwise. The control plane uses the stable id from a prior create to diff desired state. Biome and foreign-scope identities return 404.

Authentication: bearer token (Authorization: Bearer <token>)

PUT /api/deliverable-specs-api/deliverable-specs/by-id/{id}

Publish a revision of a caller-owned deliverable spec.

Publishes a new immutable revision for a caller-owned org/project identity. The stable owner and slug cannot change; version is a compatibility label, not revision identity. The exact revision is submitted to Resource Governance and projected to skill-registry only after the governed release commits.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateDeliverableSpecDto

DELETE /api/deliverable-specs-api/deliverable-specs/by-id/{id}

Retire a caller-owned deliverable spec by stable id.

Archives a caller-owned org/project identity and submits a governed retirement. Immutable revisions remain auditable; the downstream skill projection is retired only after Resource Governance commits the channel transition.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/deliverable-specs-api/deliverable-specs/facets

Distinct facets over the active system deliverable-spec catalog.

Returns the distinct categories, complexities, phases, workTypes, and tags values present across every active system spec. Drives authoring UIs that populate widgets (select, tag chips) from real catalog state rather than hardcoded client-side lists.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/deliverable-specs-api/deliverable-specs/preview-content

Preview kind-aware shape validation for a draft spec body.

Stateless companion to POST /deliverable-specs — runs the kind handler's assertCreateBody without persisting. MARKDOWN_DOCUMENT rejects inline content because HOW is a separately governed Template. Returns one fail-fast SHAPE_INVALID issue; metadata is validated at create time.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json PreviewContentRequestDto

POST /api/deliverable-specs-api/deliverable-specs/validate

Validate a deliverable candidate against a deliverable spec.

Checks the candidate (files and/or final response) against the spec output contract and kind content rules. At live and checkpoint, required content that is not there yet yields incomplete; at final it is an error. Content errors and excess are errors at every phase. strictness: lenient downgrades issues to warnings.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json ValidateDeliverableRequestDto

POST /api/deliverable-specs-api/deliverable-specs/{id}/validator-delegations

Authorize the validators of a caller-owned deliverable spec.

Originates, from the calling member's own authority, the durable delegation each executeAs subject of the spec's CURRENT revision runs its validators under. Takes no body. Until authorized, the spec's validatorDelegation is unresolved and its validators fail closed. Saving the spec as a member does the same. Refused (422) when the request carries no member context or authorization-api refuses to originate.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/deliverable-specs-api/deliverable-specs/{ref}

Resolve a deliverable spec by ref.

Ref is <slug>[@<version>]. Authenticated owner precedence is project → org → biome; Resource Governance resolves the selected identity's exact live revision. An explicit version is a compatibility assertion. 404 when no matching governed release exists.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/deliverable-specs-api/deliverable-specs/{ref}/bundle

Bundle a deliverable spec into mountable files.

Returns the governed exact revision as { relPath, bytesBase64 } files. The workspace mount resolver places them under /workspace/deliverable-specs/<ref>/. Resolution uses the same authenticated project → org → biome identity precedence as getByRef.

Authentication: bearer token (Authorization: Bearer <token>)

PUT /api/deliverable-specs-api/deliverable-specs/{slug}/canvas-annotations

Persist canvas annotations for a deliverable-spec version

Replaces editor annotations for the selected org/project identity and compatibility label. Biome-shipped identities require a fork. Editor state lives outside immutable revisions and never affects validation or release. Pass annotations: [] to clear every note.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json UpdateSpecCanvasAnnotationsDto