Project Registry API: schemas
The request and response bodies of the operations in this API.
BootstrapAnalyzeDto
| Property | Type | Required | Description |
|---|
options | object | no | Run configuration options |
prompt | string | yes | The user prompt describing the project or change |
BootstrapDecisionDto
BootstrapDecisionDtoDataEnvelope
BootstrapOptionDto
| Property | Type | Required | Description |
|---|
default | boolean | no | |
description | string | yes | |
key | string | yes | |
label | string | yes | |
BootstrapProjectDto
| Property | Type | Required | Description |
|---|
options | object | no | |
CreateProjectBindingDto
| Property | Type | Required | Description |
|---|
kind | ProjectBindingKind | yes | |
label | string | no | |
targetId | string | yes | Identifier of the upstream target. - KB_SPACE -> KB space slug (validated against knowledge-base-api) - EXTERNAL_PROJECT -> Project id in the same org (validated locally) |
CreateProjectDto
| Property | Type | Required | Description |
|---|
description | string | no | |
managedKey | string | no | Optional caller-chosen natural key, unique per organisation. When present the create is GET-OR-CREATE on (org, managedKey): the first call creates the project (201, created: true); every later call — a retry, a resumed provisioning, or a concurrent duplicate — returns the SAME project unchanged (200, created: false), whatever name, description or repo it carries. Attributes are changed with PATCH, never by re-posting. A match that is ARCHIVED is refused with 409 PROJECT_MANAGED_KEY_ARCHIVED. Grammar <namespace>:<id>, where the namespace names a domain noun, never a service. A keyed project is SERVICE-MANAGED: it is created by the managing workload, presenting the person's context or with its own token, and the person is NOT seeded as a member or administrator. A person sending a managedKey directly is refused with 403 PROJECT_MANAGED_KEY_WORKLOAD_REQUIRED. Absent: an ordinary create, exactly as before. |
name | string | yes | |
repo | CreateProjectRepoDto | no | |
CreateProjectRepoDto
| Property | Type | Required | Description |
|---|
defaultBranch | string | no | |
installationId | string | no | |
provider | string | yes | |
repoFullName | string | yes | |
CreateProjectResponseDto
| Property | Type | Required | Description |
|---|
connections | array of ProjectConnectionResponseDto | yes | |
created | boolean | yes | True when this call created the project (HTTP 201). False when a managedKey matched an existing project, which is returned unchanged (HTTP 200). Always true without a managedKey. |
createdAt | string | yes | |
createdBy | string | yes | |
description | string | no | |
hardDeletable | boolean | yes | Whether DELETE /projects/:projectId would be accepted — read-only and server-derived. False means a producer owns this project and would recreate it; archive it instead, or retire the source that declares it. |
id | string | yes | |
managedBy | one of "ui", "iac", "seeder", "biome_contributed", "runtime_registered", "system", "deployment" or null | yes | Provisioning ownership marker. iac = managed by the declarative control plane; seeder = resolved by a managed-key producer; ui = hand-managed (or adopted from seeder by an edit or an archive); system = platform-shipped; null = unmanaged/legacy. |
managedKey | string or null | yes | The caller-chosen natural key <namespace>:<id> the project was created with, unique per organisation; null when it has none. |
name | string | yes | |
orgId | string | yes | |
orgMemberAccess | one of "none", "viewer", "editor" | yes | What every member of the organisation holds on this project without a membership seat: none (private), viewer (read) or editor (read and write). New projects are private; an organisation or project administrator changes it with PATCH /projects/:projectId. |
repos | array of ProjectRepoResponseDto | yes | |
settings | ProjectSettingsResponseDto | no | |
status | string | yes | |
CreateProjectResponseDtoDataEnvelope
CreateVariableDto
| Property | Type | Required | Description |
|---|
description | string | no | Human-readable description |
isSecret | boolean | no | Whether this variable is a secret (encrypted at rest, write-only). Defaults to false. |
key | string | yes | Variable name (uppercase + underscores). Unique within the wallet. |
value | string | yes | Variable value (plaintext or secret) |
CreateWalletDto
| Property | Type | Required | Description |
|---|
description | string | no | Human-readable description shown in the settings UI. |
name | string | yes | Wallet name unique within the wallet's (org, project) scope. Lowercase kebab-case. |
ExistingAssetsDto
| Property | Type | Required | Description |
|---|
artifacts | number | yes | |
kbPages | number | yes | |
GrantProjectRoleDto
| Property | Type | Required | Description |
|---|
role | ProjectRole | yes | The role to add. CLOSED set (ProjectRole) — an unrecognised value is REFUSED at the wire with 400, never stored. Storing one was the defect this closes: role was a bare string, so 'adminn' was accepted, persisted, and then failed the authority check for the lifetime of the row while reading in the UI as a granted role. RevokeProjectRoleDto.role is intentionally NOT closed the same way — see the class doc above before changing either field. |
userId | string | yes | |
ManifestDiffResponseDto
| Property | Type | Required | Description |
|---|
diff | array of string | yes | RFC 6902 JSON Patch operations |
fromVersion | number | yes | |
toVersion | number | yes | |
ManifestDiffResponseDtoDataEnvelope
ManifestHistoryEntryDto
| Property | Type | Required | Description |
|---|
changePhase | string | no | |
changeReason | string | no | |
changedBy | string | yes | |
createdAt | string | yes | |
diff | object | no | |
id | string | yes | |
pipelineRunId | string | no | Pipeline run that produced this change |
snapshotJson | object | yes | |
version | number | yes | |
ManifestHistoryEntryDtoDataEnvelope
ManifestHistoryEntryDtoPaginatedEnvelope
ManifestResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
id | string | yes | |
lastUpdatedBy | string | yes | |
lastUpdatedPhase | string | no | |
manifest | object | yes | |
projectId | string | yes | |
schemaVersion | string | yes | |
updatedAt | string | yes | |
version | number | yes | |
ManifestResponseDtoDataEnvelope
ManifestSectionListResponseDto
| Property | Type | Required | Description |
|---|
entries | object | yes | Map of section entry names to their objects |
ManifestSectionListResponseDtoDataArrayEnvelope
ManifestValidationResponseDto
| Property | Type | Required | Description |
|---|
errors | array of string | yes | |
valid | boolean | yes | |
ManifestValidationResponseDtoDataEnvelope
| Property | Type | Required | Description |
|---|
hasMore | boolean | no | |
limit | number | no | |
nextCursor | string or null | no | |
page | number | no | |
previousCursor | string or null | no | |
total | number | no | |
totalPages | number | no | |
PatchManifestDto
| Property | Type | Required | Description |
|---|
changeReason | string | no | Reason for this change (for audit trail) |
patch | object | yes | JSON merge-patch object to apply to current manifest |
PatchSectionEntryDto
| Property | Type | Required | Description |
|---|
changeReason | string | no | Reason for this change (for audit trail) |
patch | object | yes | JSON merge-patch to apply to section entry |
PreferredImageVariantResponseDto
| Property | Type | Required | Description |
|---|
preferredImageVariantSlug | string or null | no | The workspace-image variant slug preferred for this project. Null means no project-level preference; the resolver cascades to the org default. |
projectId | string | yes | Project identifier. |
PreferredImageVariantResponseDtoDataEnvelope
PriorRunSummaryDto
| Property | Type | Required | Description |
|---|
completedPhases | array of string | yes | |
id | string | yes | |
prompt | string | yes | |
status | string | yes | |
stoppedAtPhase | string | no | |
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"
ProjectBindingKind
Type: one of "KB_SPACE", "EXTERNAL_PROJECT"
ProjectBindingResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
createdBy | string | yes | |
id | string | yes | |
kind | ProjectBindingKind | yes | |
label | string | no | |
projectId | string | yes | |
targetId | string | yes | |
updatedAt | string | yes | |
ProjectBindingResponseDtoDataArrayEnvelope
ProjectBindingResponseDtoDataEnvelope
ProjectConnectionResponseDto
| Property | Type | Required | Description |
|---|
config | object | no | |
credentialsPointer | string | no | |
enabled | boolean | yes | |
type | string | yes | |
ProjectDeletionCascadeDto
| Property | Type | Required | Description |
|---|
count | number | yes | How many rows of this class the cascade will remove. Authoritative: these rows are in this service’s database and go in the same statement. |
key | string | yes | Stable key for the record class, for clients that group or order. |
label | string | yes | User-facing name of the record class, already pluralised for display. |
ProjectDeletionImpactDto
| Property | Type | Required | Description |
|---|
archiveAvailable | boolean | yes | Whether ARCHIVE is available as a reversible alternative right now. False when the project is already archived. |
blockedReason | string | no | Why the delete would be refused. Present if and only if deletable is false. |
cascades | array of ProjectDeletionCascadeDto | yes | Every record class the cascade removes, INCLUDING the ones that are currently empty — a zero is information ("this project has no wallets"), and omitting it would make the list look like the whole story only when it happens to be non-empty. |
deletable | boolean | yes | Whether DELETE would be accepted right now. This is the SAME predicate the delete route enforces, re-evaluated at delete time — a preview is never the authority. |
downstreamCleanupSignalled | boolean | yes | True when deleting publishes the platform-wide cascade signal that other services use to remove their own project-keyed records. No count is offered: this service cannot enumerate rows it does not own. |
managedBy | one of "ui", "iac", "seeder", "biome_contributed", "runtime_registered", "system", "deployment" or null | yes | Which producer owns this project’s declaration, or null when a person created it. A project a producer would recreate is refused. |
projectId | string | yes | |
projectName | string | yes | |
totalRecords | number | yes | Sum of cascades[].count, for a one-line summary. |
ProjectDeletionImpactDtoDataEnvelope
ProjectMembershipResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | ISO-8601 creation timestamp. |
id | string | yes | Membership row id. |
orgId | string | yes | Organization that owns the project. |
projectId | string | yes | Project the membership grants access to. |
roles | array of string | yes | Roles held on this project, sorted and deduped. NOT guaranteed to be a subset of ProjectRole: the write side refuses anything outside that closed set, but the underlying column is unconstrained, so a stored value outside it is returned as-is rather than silently dropped. Only ProjectRole members carry role-management authority. |
updatedAt | string | yes | ISO-8601 last-modification timestamp. |
userId | string | yes | Subject id of the member — the canonical acting subject id (JWT sub). |
ProjectMembershipResponseDtoDataArrayEnvelope
ProjectMembershipResponseDtoDataEnvelope
ProjectRepoResponseDto
| Property | Type | Required | Description |
|---|
defaultBranch | string | no | |
installationId | string | no | |
provider | string | yes | |
repoFullName | string | yes | |
ProjectResponseDto
| Property | Type | Required | Description |
|---|
connections | array of ProjectConnectionResponseDto | yes | |
createdAt | string | yes | |
createdBy | string | yes | |
description | string | no | |
hardDeletable | boolean | yes | Whether DELETE /projects/:projectId would be accepted — read-only and server-derived. False means a producer owns this project and would recreate it; archive it instead, or retire the source that declares it. |
id | string | yes | |
managedBy | one of "ui", "iac", "seeder", "biome_contributed", "runtime_registered", "system", "deployment" or null | yes | Provisioning ownership marker. iac = managed by the declarative control plane; seeder = resolved by a managed-key producer; ui = hand-managed (or adopted from seeder by an edit or an archive); system = platform-shipped; null = unmanaged/legacy. |
managedKey | string or null | yes | The caller-chosen natural key <namespace>:<id> the project was created with, unique per organisation; null when it has none. |
name | string | yes | |
orgId | string | yes | |
orgMemberAccess | one of "none", "viewer", "editor" | yes | What every member of the organisation holds on this project without a membership seat: none (private), viewer (read) or editor (read and write). New projects are private; an organisation or project administrator changes it with PATCH /projects/:projectId. |
repos | array of ProjectRepoResponseDto | yes | |
settings | ProjectSettingsResponseDto | no | |
status | string | yes | |
ProjectResponseDtoDataEnvelope
ProjectRole
The role to add. CLOSED set (ProjectRole) — an unrecognised value is
REFUSED at the wire with 400, never stored. Storing one was the defect
this closes: role was a bare string, so 'adminn' was accepted,
persisted, and then failed the authority check for the lifetime of the row
while reading in the UI as a granted role.
RevokeProjectRoleDto.role is intentionally NOT closed the same way — see
the class doc above before changing either field.
Type: one of "admin", "lead"
ProjectSettingsResponseDto
| Property | Type | Required | Description |
|---|
cloudDetails | object | no | Cloud-specific configuration details |
cloudProvider | one of "auto", "azure", "aws", "gcp", "self_hosted", "hybrid", "undecided" | no | Target cloud provider |
outputLanguage | string | no | ISO 639-1 language code or "auto" |
targetBranch | string | no | Default target branch for merges |
ProjectSummaryResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
createdBy | string | yes | |
description | string | no | |
hardDeletable | boolean | yes | Whether DELETE /projects/:projectId would be accepted — read-only and server-derived. False means a producer owns this project and would recreate it; archive it instead, or retire the source that declares it. |
id | string | yes | |
managedBy | one of "ui", "iac", "seeder", "biome_contributed", "runtime_registered", "system", "deployment" or null | yes | Provisioning ownership marker. iac = managed by the declarative control plane; seeder = resolved by a managed-key producer; ui = hand-managed (or adopted from seeder by an edit or an archive); system = platform-shipped; null = unmanaged/legacy. |
managedKey | string or null | yes | The caller-chosen natural key <namespace>:<id> the project was created with, unique per organisation; null when it has none. |
name | string | yes | |
orgId | string | yes | |
status | string | yes | |
ProjectSummaryResponseDtoDataArrayEnvelope
PromptClassificationDto
| Property | Type | Required | Description |
|---|
classification | one of "same_scope", "evolution", "new_direction" | yes | |
similarity | number | yes | Jaccard similarity score 0-1 |
ProvisionOnboardingRequestDto
| Property | Type | Required | Description |
|---|
alwaysAllowResourceCreation | boolean | yes | When true, persists "Don't ask again before creating platform-managed resources" as the durable org preference. Source of truth lives in OrgOnboardingPreferences; localStorage is best-effort UX state. |
orgId | string | yes | Org the wizard is provisioning for. Must match the JWT context. |
packagesProviderId | string | no | Catalog provider id for the packages resource (e.g. NPMJS). Must map to category packages. Omit when the project has no packages provider — absent means none, never a default. |
projectId | string | yes | Project the wizard is provisioning for. Must exist within orgId. |
sourceCodeProviderId | string | no | Catalog provider id for the source-code resource (e.g. GITHUB). Must map to category source-code. Omit when the project has no source-code provider — absent means none, never a default. |
ProvisionOnboardingResponseDto
| Property | Type | Required | Description |
|---|
orgId | string | yes | Org the wizard provisioned for. |
packagesConnectionId | string | no | Active OrgConnection.id for the chosen packages provider. Omitted when none was chosen or the provider is system-shareable (no per-org row). |
projectId | string | yes | Project the wizard provisioned for. |
sourceCodeConnectionId | string | no | Active OrgConnection.id for the chosen source-code provider. Omitted when none was chosen or the provider is system-shareable (no per-org row). |
ProvisionOnboardingResponseDtoDataEnvelope
PutManifestDto
| Property | Type | Required | Description |
|---|
changeReason | string | no | Reason for this change (for audit trail) |
manifest | object | yes | Full manifest JSON object conforming to ProjectManifest schema |
PutResourceShareDto
| Property | Type | Required | Description |
|---|
expiresAt | string (date-time) | no | When the share lapses. |
level | string | yes | The level to grant — one of the type's share relations. |
subjectId | string | yes | |
subjectKind | ShareGranteeKind | yes | A user grantee is bound to that user's current membership of the org (422 when not a member). |
ResolveWalletsRequestDto
| Property | Type | Required | Description |
|---|
names | array of string | yes | Wallet names to resolve. Must all exist within the project/org scope; missing names fail-fast with WORKFLOW_WALLET_NOT_FOUND. |
ResolvedWalletsResponseDto
| Property | Type | Required | Description |
|---|
secrets | map of string | yes | Secret variables resolved from the requested wallets, decrypted. Treat as sensitive — consumers must redact in logs. |
vars | map of string | yes | Non-secret variables resolved from the requested wallets. Project-scoped wallets override org-scoped wallets sharing the same key. |
walletKeyMap | map of string | yes | Provenance map: variable key → wallet name that contributed the value. Lets the engine/audit show which wallet served each key. |
ResolvedWalletsResponseDtoDataEnvelope
ResourceShareDto
| Property | Type | Required | Description |
|---|
expiresAt | string (date-time) or null | yes | |
grantedBy | string | yes | <kind>:<id> of the principal who granted it. |
level | string | yes | The relation the share grants (a level of the type). |
membershipActive | boolean or null | yes | For a membership share, whether it is still the user's current membership of the org; false means the user left and the share grants nothing (it can still be removed). Null for every other kind. |
refusalCode | string or null | yes | The typed refusal code (tenant_mismatch, subject_unresolvable, ...) when state is refused, else null. |
state | ShareState | yes | Whether the share is in force. refused: the authorization plane refused its facts for good, so it grants nothing; re-put it with a valid subject, or remove it. |
subjectId | string | yes | For a membership share, the membership id (one stay of the user in the org). |
subjectKind | ShareSubjectKind | yes | |
userId | string or null | yes | The user of a membership share; null for every other kind. |
ResourceSharesDto
| Property | Type | Required | Description |
|---|
canManage | boolean | yes | Whether the caller may share or unshare this resource. |
expirable | boolean | yes | Whether a share of this type may carry an expiry; when false an expiry is refused. |
levels | array of string | yes | The levels a share of this type may grant, lowest first. A sharer may grant only a level it holds. |
shares | array of ResourceShareDto | yes | |
ResourceSharesDtoDataEnvelope
RevokeProjectRoleDto
| Property | Type | Required | Description |
|---|
role | string | yes | Role to remove from the membership. NOT limited to ProjectRole: the grant side refuses anything outside that closed set, but the stored column is unconstrained, so a value that got in by another route must still be removable here. Removing a role the membership does not hold is a successful no-op, so the call is safe to retry. |
userId | string | yes | |
SetPreferredImageVariantDto
| Property | Type | Required | Description |
|---|
preferredImageVariantSlug | string or null | no | Workspace-image variant slug to prefer for this project. Set null to clear the preference and let the resolver cascade to the org default. |
ShareGranteeKind
A user grantee is bound to that user's current membership of the org (422 when not a member).
Type: one of "user", "agent", "external-subject", "team", "role"
ShareState
Whether the share is in force. refused: the authorization plane refused its facts for good, so it grants nothing; re-put it with a valid subject, or remove it.
Type: one of "active", "refused"
ShareSubjectKind
Type: one of "membership", "agent", "external-subject", "team", "role"
UpdateProjectConnectionDto
| Property | Type | Required | Description |
|---|
config | object | no | |
credentialsPointer | string | no | |
enabled | boolean | yes | |
UpdateProjectDto
| Property | Type | Required | Description |
|---|
description | string or null | no | Optional project description. Set null to clear the existing description. |
name | string | no | Human-readable project name. |
orgMemberAccess | one of "none", "viewer", "editor" | no | Set what every member of the organisation holds on this project without a membership seat: none (private), viewer or editor. Requires project administration (xema_admin), unlike the other fields. |
UpdateProjectSettingsDto
| Property | Type | Required | Description |
|---|
cloudDetails | object | no | Additional cloud-specific configuration details. |
cloudProvider | one of "auto", "azure", "aws", "gcp", "self_hosted", "hybrid", "undecided" | no | Target cloud provider for architecture decisions. "auto" = LLM infers from project context. |
outputLanguage | string | no | ISO 639-1 language code for all pipeline output. "auto" = LLM auto-detects from context. |
settings | object | yes | |
targetBranch | string | no | Target branch for pipeline merges. Defaults to repository defaultBranch if not set. |
UpdateVariableDto
| Property | Type | Required | Description |
|---|
description | string | no | |
value | string | no | New value (required for secrets, optional for non-secrets) |
UpdateWalletDto
| Property | Type | Required | Description |
|---|
description | string | no | |
UpsertSectionEntryDto
| Property | Type | Required | Description |
|---|
changeReason | string | no | Reason for this change (for audit trail) |
entry | object | yes | Full section entry object |
ValidateManifestDto
| Property | Type | Required | Description |
|---|
manifest | object | yes | Manifest JSON to validate without saving |
VariableResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
createdBy | string | yes | |
description | string or null | no | |
id | string | yes | |
isSecret | boolean | yes | |
key | string | yes | |
orgId | string | yes | |
projectId | string or null | no | |
updatedAt | string | yes | |
updatedBy | string or null | no | |
value | string or null | no | Value (null for secrets — write-only) |
walletId | string | yes | |
VariableResponseDtoDataArrayEnvelope
VariableResponseDtoDataEnvelope
WalletEntryDto
| Property | Type | Required | Description |
|---|
isSecret | boolean | yes | |
key | string | yes | |
WalletResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
createdBy | string | yes | |
description | string or null | no | |
id | string | yes | |
name | string | yes | |
orgId | string | yes | |
projectId | string or null | no | |
updatedAt | string | yes | |
updatedBy | string or null | no | |
WalletResponseDtoDataArrayEnvelope
WalletResponseDtoDataEnvelope
WalletWithEntriesResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
createdBy | string | yes | |
description | string or null | no | |
entries | array of WalletEntryDto | yes | |
id | string | yes | |
name | string | yes | |
orgId | string | yes | |
projectId | string or null | no | |
updatedAt | string | yes | |
updatedBy | string or null | no | |
WalletWithEntriesResponseDtoDataEnvelope