Deliverable Specs API: schemas

The request and response bodies of the operations in this API.

ArtifactVersioningMode

Default ArtifactVersioningMode the harvester uses when emitting instances of this spec. null = no spec-level default; the producer-kind fallback in WorkflowArtifactEmitter applies. Workflow YAMLs can override per-job via with.versioning.

Type: one of "append", "new", "replace"

CreateDeliverableSpecDto

Property	Type	Required	Description
`category`	string	yes
`complexity`	string	no
`content`	string or null	no	Authoritative body for JSON_SCHEMA (JSON text), STRUCTURED_JSON (JSON text), CUSTOM, or RESPONSE_ONLY. Rejected for MARKDOWN_DOCUMENT, whose HOW guidance is selected by `templateBinding`.
`description`	string or null	no
`fetchSpec`	object or null	no	Endpoint-fetch declaration. Required when kind=ENDPOINT_FETCH. Shape: `{ schemaVersion: 1, entries: EndpointFetchEntry[], maxConcurrency: number\|null, timeoutMs: number }`.
`forkedFromId`	string	no	Id of the spec this row was forked from (biome/system origin). Set once at fork time. Lets the platform detect upgrade conflicts when the source biome re-seeds, and lets the UI render a "forked from" breadcrumb on org/project copies.
`kind`	one of `"MARKDOWN_DOCUMENT"`, `"JSON_SCHEMA"`, `"ENDPOINT_FETCH"`, `"STRUCTURED_JSON"`, `"CUSTOM"`, `"RESPONSE_ONLY"`	yes
`minArtifactCount`	number	no
`multiPage`	boolean	no
`pages`	array of SpecPageDto	no
`phases`	array of string	no
`rules`	object or null	no	Rules bag (shared with the validator). Optional; defaults come from the kind-specific validator.
`slug`	string	yes
`tags`	array of string	no
`targetSlot`	TargetSlotDto	no	Slot the deliverable lands in after harvest. Defaults to `deliverables/`. Set `kind: Repos` + `repo: <slug>` for code-changing specs that should land in `repos/<slug>/`. Validated against project bound-repos at apply time.
`templateBinding`	object	no	Explicit owner-qualified Template revision selection for HOW guidance. No project/org/biome fallback is inferred.
`title`	string	yes
`version`	string	yes
`versioningMode`	ArtifactVersioningMode	no	Default `ArtifactVersioningMode` the harvester uses when emitting instances of this spec. Omit to inherit the producer-kind default at emit time. Workflow YAMLs can still override per-job via `with.versioning`.
`workTypes`	array of string	no

DeliverableCandidateDto

Property	Type	Required	Description
`files`	array of DeliverableCandidateFileDto	yes
`response`	string	no	The agent final response, for response-only deliverables. JSON text when the spec declares a schema.

DeliverableCandidateFileDto

Property	Type	Required	Description
`content`	string	yes	UTF-8 file content.
`contentKind`	one of `"json"`, `"markdown"`, `"text"`	yes
`path`	string	yes

DeliverableContentKind

How the harvester decodes the file: json runs JSON.parse + spec content-shape validation, markdown/text reads raw bytes and uploads as a single-page artifact.

Type: one of "json", "markdown", "text"

DeliverableOutputContractDto

Property	Type	Required	Description
`files`	array of DeliverableOutputContractFileDto	no
`mode`	DeliverableOutputContractMode	yes
`multiPage`	DeliverableOutputContractMultiPageDto	no
`notes`	string	no
`targetSlot`	DeliverableTargetSlotDescriptorDto	no	Required when mode='workspace-files'; absent for other modes. Structured pointer to the workspace slot the deliverable lands in.
`title`	string	yes

DeliverableOutputContractFileDto

Property	Type	Required	Description
`canonicalPath`	string	yes
`contentKind`	DeliverableContentKind	yes	How the harvester decodes the file: `json` runs JSON.parse + spec content-shape validation, `markdown`/`text` reads raw bytes and uploads as a single-page artifact.
`fallbackPaths`	array of string	no
`purpose`	string	yes
`required`	boolean	yes
`schemaRef`	string	no

DeliverableOutputContractMode

Type: one of "workspace-files", "response-only", "endpoint-fetch", "no-output"

DeliverableOutputContractMultiPageDto

Property	Type	Required
`manifestPath`	string	yes
`pagePathTemplate`	string	yes
`pages`	array of DeliverableOutputContractMultiPagePageDto	yes

DeliverableOutputContractMultiPagePageDto

Property	Type	Required	Description
`slug`	string	yes
`title`	string	yes

DeliverableSpecBundleFileDto

Property	Type	Required	Description
`bytesBase64`	string	yes	File contents, base64-encoded UTF-8.
`relPath`	string	yes	Path within the spec bundle.

DeliverableSpecBundleResponseDto

Property	Type	Required	Description
`files`	array of DeliverableSpecBundleFileDto	yes

DeliverableSpecBundleResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	DeliverableSpecBundleResponseDto	yes

DeliverableSpecFacetsDto

Property	Type	Required	Description
`categories`	array of string	yes	Every distinct `category` present on active system specs.
`complexities`	array of string	yes	Every distinct `complexity` present on active system specs. Stable set today (`simple`, `standard`, `complex`, `enterprise`) but returned dynamically so the UI reflects reality.
`phases`	array of string	yes	Every distinct phase key used in any active system spec `phases[]`.
`tags`	array of string	yes	Every distinct free-form tag used across active system specs. Returned as a suggestion pool; the create endpoint accepts any new tag not yet present.
`workTypes`	array of string	yes	Every distinct work-type key used in any active system spec `workTypes[]`. Mirrors `RUN_TYPES` in `@xemahq/kernel-contracts/workflow` in practice.

DeliverableSpecFacetsDtoDataEnvelope

Property	Type	Required	Description
`data`	DeliverableSpecFacetsDto	yes

DeliverableSpecResponseDto

Property	Type	Required	Description
`assets`	array of object or null	no
`biomeId`	string or null	no	Biome id when source='biome'.
`canvasAnnotations`	array of object or null	no	Sticky-note annotations overlaid on the spec canvas. Null when none have ever been saved; `[]` after the user has explicitly cleared every note. Same shape as `WorkflowDefinitionVersionResponseDto.canvasAnnotations`.
`category`	string	yes
`complexity`	string	yes
`content`	string or null	no
`contentHash`	string	yes	SHA-256 of the immutable validation contract.
`contractVersion`	string	yes	Compatibility label; not revision identity or live-selection authority.
`createdAt`	string	yes
`deliverableContract`	DeliverableOutputContractDto	yes	Run-time output contract derived from the spec's kind handler — what the agent must produce, where, and which schema files to consult. Validated against `DeliverableOutputContractSchema` before being returned, so a misconfigured handler fails the GET request fast rather than confusing an agent at runtime. Composer + harvester read the contract by shape; new kinds plug in via a handler without touching either of them.
`description`	string or null	no
`editorStateRevision`	number or null	no
`fetchSpec`	object or null	no
`forceAppliedOverlayRefs`	array of string	yes	Overlay refs force-bound to this spec via `DeliverableSpecOverlayBinding`. Each ref is `<overlay.source>/<overlay.slug>@<overlay.id-prefix>` so the run-context renderer can resolve and apply the overlay deterministically. Tag-driven overlays (matched at render time on `context.tags[]`) are NOT included here — only explicit bindings — so the audit field reflects "operator-locked" composition, not the dynamic match list. Empty when no explicit bindings exist.
`forkedFromId`	string or null	no	Id of the spec this row was forked from (biome/system origin). Null when authored from scratch or when the origin has been deleted.
`id`	string	yes
`isSystem`	boolean	yes
`kind`	one of `"MARKDOWN_DOCUMENT"`, `"JSON_SCHEMA"`, `"ENDPOINT_FETCH"`, `"STRUCTURED_JSON"`, `"CUSTOM"`, `"RESPONSE_ONLY"`	yes
`managedBy`	ResourceManagedBy or null	yes	Provisioning ownership marker (iac/seeder/ui/system, or null when unmanaged). Lets a console badge an IaC-owned spec and offer "export as code". Declared specs are immutable (fork-first), so this stays `iac` for a reconciled spec.
`multiPage`	boolean	yes
`orgId`	string or null	no
`pageAllocationHints`	object or null	no
`pages`	array of object or null	no
`phases`	array of string	yes
`projectId`	string or null	no
`publishedAt`	string	yes
`reviewDimensions`	array of object or null	no
`revisionId`	string (uuid)	yes
`revisionNumber`	number	yes
`rules`	object or null	no
`scope`	object or null	no
`sectionGuidance`	object or null	no
`slug`	string	yes
`source`	DeliverableSpecSpaceKind	yes	The Space tier that owns this spec — five of the kernel's seven `SpaceKind` values. The backend currently PERSISTS only `biome`, `org` and `project`; the wider addressable set keeps the platform-wide ownership model uniform, but `system` and `user` never appear here today.
`standards`	array of object or null	no
`tags`	array of string	yes
`targetSlot`	string	yes	Canonical slot path the deliverable lands in. `deliverables/` for default agent outputs; `repos/<repo>/` for code-changing specs. Validated against the closed slot allowlist; `repos/<repo>/` is further validated against the project bound repos at apply time.
`templateBinding`	object or null	no	Explicit owner-qualified Template revision selection for HOW guidance.
`title`	string	yes
`topologySchema`	object or null	no
`updatedAt`	string	yes
`validatorDelegation`	ValidatorDelegation	yes	Whether the delegations the current revision's validators run under are held: `resolved` (declares none, or every executeAs subject's delegation is held) or `unresolved` (a member must re-save the spec to originate it; until then its validators fail closed with `validator-delegation-unresolved`).
`version`	string	yes
`versioningMode`	ArtifactVersioningMode or null	no	Default `ArtifactVersioningMode` the harvester uses when emitting instances of this spec. `null` = no spec-level default; the producer-kind fallback in `WorkflowArtifactEmitter` applies. Workflow YAMLs can override per-job via `with.versioning`.
`workTypes`	array of string	yes

DeliverableSpecResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of DeliverableSpecResponseDto	yes

DeliverableSpecResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	DeliverableSpecResponseDto	yes

DeliverableSpecSpaceKind

The Space tier that owns this spec — five of the kernel's seven SpaceKind values. The backend currently PERSISTS only biome, org and project; the wider addressable set keeps the platform-wide ownership model uniform, but system and user never appear here today.

Type: one of "system", "biome", "org", "project", "user"

DeliverableTargetSlotDescriptorDto

Property	Type	Required	Description
`kind`	DeliverableTargetSlotKind	yes
`repoSlug`	string	no	Required when kind='repos'; absent otherwise.

DeliverableTargetSlotKind

Type: one of "deliverables", "repos"

PreviewContentRequestDto

Property	Type	Required	Description
`content`	string or null	no	Authoritative body for JSON_SCHEMA, STRUCTURED_JSON, CUSTOM, or RESPONSE_ONLY. Rejected for MARKDOWN_DOCUMENT.
`fetchSpec`	object or null	no	Endpoint-fetch declaration. Required when kind=ENDPOINT_FETCH.
`kind`	one of `"MARKDOWN_DOCUMENT"`, `"JSON_SCHEMA"`, `"ENDPOINT_FETCH"`, `"STRUCTURED_JSON"`, `"CUSTOM"`, `"RESPONSE_ONLY"`	yes
`multiPage`	boolean	no
`pages`	array of SpecPageDto	no
`rules`	object or null	no

PreviewContentResponseDto

Property	Type	Required	Description
`issues`	array of ValidationIssueDto	yes
`valid`	boolean	yes	True when the kind handler would accept the body at create time. Read alongside `issues[]` — a `valid: false` response always carries at least one issue describing why.

PreviewContentResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	PreviewContentResponseDto	yes

ProblemActionableBy

Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.

Type: one of "user", "org-admin", "platform", "none"

ProblemDetailsDto

RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	string	yes	SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ProblemFieldIssueDto

Property	Type	Required	Description
`code`	string	no	SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem.
`detail`	string	yes	Prose for logs and developers. A frontend localises from `code` + `params` instead.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for this issue's `code`.
`pointer`	string	yes	RFC 6901 JSON Pointer into the request body. Root is "/".

ProblemRetry

What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.

Type: one of "transient", "after-change", "never"

ResourceManagedBy

Provisioning ownership marker (iac/seeder/ui/system, or null when unmanaged). Lets a console badge an IaC-owned spec and offer "export as code". Declared specs are immutable (fork-first), so this stays iac for a reconciled spec.

Type: one of "ui", "iac", "seeder", "biome_contributed", "runtime_registered", "system", "deployment"

SpecCanvasAnnotationDto

Property	Type	Required	Description
`height`	number	yes
`id`	string	yes
`text`	string	yes	Free-form text, capped to 4 KiB on write.
`width`	number	yes
`x`	number	yes
`y`	number	yes

SpecPageDto

Property	Type	Required
`parentSlug`	string or null	no
`slug`	string	yes
`title`	string	yes

TargetSlotDto

Property	Type	Required	Description
`kind`	one of `"deliverables"`, `"repos"`	yes
`repo`	string or null	no	Bound-repo slug. Required when `kind === Repos`; rejected otherwise.

UpdateSpecCanvasAnnotationsDto

Property	Type	Required	Description
`annotations`	array of SpecCanvasAnnotationDto	yes
`version`	string	yes	Version of the spec to update.

ValidateDeliverableRequestDto

Property	Type	Required	Description
`candidate`	DeliverableCandidateDto	yes
`deliverableSpecRef`	string	yes	Spec ref — `<slug>[@<version>]`. Resolved server-side (org override > system fallback).
`jobRunId`	string	no	Job run that issued the validation call (audit).
`phase`	one of `"live"`, `"checkpoint"`, `"final"`	yes	`live` and `checkpoint` report missing required content as `incomplete`; `final` reports it as an error.
`strictness`	one of `"lenient"`, `"standard"`, `"strict"`	no	Downgrades errors to warnings at `lenient`; defaults to `standard`.
`workflowRunId`	string	no	Workflow run that owns the validation call (audit).

ValidateDeliverableResponseDto

Property	Type	Required	Description
`checkedAt`	string	yes
`issues`	array of ValidationIssueDto	yes
`kind`	one of `"MARKDOWN_DOCUMENT"`, `"JSON_SCHEMA"`, `"ENDPOINT_FETCH"`, `"STRUCTURED_JSON"`, `"CUSTOM"`, `"RESPONSE_ONLY"`	yes
`specVersion`	string	yes
`status`	one of `"invalid"`, `"incomplete"`, `"complete"`, `"pending"`	yes
`validatorPins`	array of ValidatorPinDto	yes	The capability descriptor each declared validator that ran was pinned to for this validation. Empty when the spec declares no validator for the phase.

ValidateDeliverableResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	ValidateDeliverableResponseDto	yes

ValidationIssueDto

Property	Type	Required
`code`	string	yes
`message`	string	yes
`path`	string or null	yes
`severity`	one of `"warning"`, `"error"`	yes

ValidatorDelegation

Whether the delegations the current revision's validators run under are held: resolved (declares none, or every executeAs subject's delegation is held) or unresolved (a member must re-save the spec to originate it; until then its validators fail closed with validator-delegation-unresolved).

Type: one of "resolved", "unresolved"

ValidatorPinDto

Property	Type	Required	Description
`descriptorHash`	string	yes	The exact descriptor hash the validator was pinned to for this validation.
`ref`	string	yes	The validator capability.