Projects, Entities & Data Model

Manage project CI/CD pipelines, logical environments, project templates, entities and entity types, entity media, entity relationships and relationship types, entity permission grants, and saved views.

72 endpoints. Generated from the OpenAPI 3.1 specification.

GET /v1/entities/{entityId}

Get an entity

Returns a single entity by identifier. Requires `project.view` permission. An entity the caller cannot see is reported as `NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Responses

Status	Description
`200`	The entity record.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks read access on the entity.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`org_id`	string<uuid>
`project_id`	string<uuid>
`entity_type_id`	string<uuid>
`parent_id`	string<uuid>
`name`	string
`status`	string
`metadata`	object	Arbitrary field bag (top-level key merge on update).
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`
`owner_id`	string<uuid>
`state_uuid`	string<uuid>	Current workflow state (null when no workflow assigned).
`created_by_user_id`	string<uuid>
`created_at`	string<date-time>
`updated_at`	string<date-time>

PUT /v1/entities/{entityId}

Update an entity

Updates one or more fields of an entity. Requires `project.view` (the SP enforces the five-right EDIT gate, including grants). The `metadata` bag uses a top-level key merge: supplied keys set/overwrite; a `null` value removes a key; omitted keys are preserved. Supply `expected_updated_at` for optimistic-concurrency control.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`name`	string	no
`data`	object	no	Alias for `metadata`.
`metadata`	object	no	Field bag, top-level key merge. Send a key as `null` to delete it.
`status`	string	no
`parent_id`	string<uuid>	no	Send `null` to detach from parent.
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`	no
`owner_id`	string<uuid>	no
`expected_updated_at`	string<date-time>	no	Optimistic-concurrency precondition. When provided the update fails with `CONFLICT` if the row was modified since this timestamp.

Responses

Status	Description
`200`	Entity updated.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (no fields supplied, or SP validation refusal).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks EDIT right, or a field-level edit is denied. The message contains the offending field key for field-level denials.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	`CONFLICT` — optimistic-concurrency: the entity was modified by another session since `expected_updated_at`.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`updated`	boolean

DELETE /v1/entities/{entityId}

Soft-delete an entity

Soft-deletes an entity (sets `deleted_at`). Requires `project.view` (SP enforces five-right DELETE gate). The entity is hidden from list/get responses after deletion.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Responses

Status	Description
`200`	Entity deleted.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`deleted`	boolean

GET /v1/entities/{entityId}/comments

List entity comments

Returns the comments on an entity with offset pagination. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).
`limit`	query	integer	no	Maximum number of comments to return (1–200).
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	List of comments.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/entities/{entityId}/comments

Create an entity comment

Adds a comment to an entity. Requires `project.update` permission. Supports threaded replies via `parent_comment_id`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`content`	string	yes	Comment text (max 16 384 chars).
`parent_comment_id`	string<uuid>	no	Optional parent comment for threaded replies.

Responses

Status	Description
`201`	Comment created.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	`NOT_FOUND` — entity or `parent_comment_id` does not exist.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>
`entity_id`	string<uuid>
`parent_comment_id`	string<uuid>
`user_id`	string<uuid>
`content`	string
`created_at`	string<date-time>
`updated_at`	string<date-time>

GET /v1/entities/{entityId}/effective-permissions

Get effective permissions on an entity

Returns the computed five-right effective permissions for the caller (or a specified in-org user) on the entity, with contributing grant sources. Self-view is available to any caller with entity visibility; inspecting another user's rights (`?user_id=`) is SP-gated to org admins and resource creators, and is audit-logged.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).
`user_id`	query	string<uuid>	no	Inspect effective permissions for another in-org user. Restricted to org admins and resource creators.

Responses

Status	Description
`200`	Effective permission set.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`can_visibility`	boolean
`can_read`	boolean
`can_edit`	boolean
`can_delete`	boolean
`can_purge`	boolean
`sources`	array of object	List of contributing grants that produced the effective rights.

POST /v1/entities/{entityId}/media

Upload entity media

Uploads a binary media asset and attaches it to a named field on the entity. Accepts either `multipart/form-data` (with a `file` part + `field_key` field) or a raw body with `?field_key=&filename=&content_type=` query parameters. The server performs magic-byte validation to determine the authoritative content type; the declared content type must also be on the allowlist (images, audio, video, common documents). Maximum 100 MiB. Returns the media descriptor `id` that the entity field stores.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).
`field_key`	query	string	no	Entity field key to attach the media to (required when using a raw body upload; 1–128 chars matching `^[A-Za-z0-9_.-]+$`).
`filename`	query	string	no	Original filename for display purposes (raw body upload only).
`content_type`	query	string	no	Declared MIME type (raw body upload only). Must be from the allowlist.

Responses

Status	Description
`201`	Media uploaded and descriptor created.
`400`	`VALIDATION_ERROR` (bad field_key, missing content type, invalid UUID), `UNSUPPORTED_FILE_TYPE` (content type not allowlisted or bytes mismatch declared type), or `UPLOAD_SUPPRESSED` (file on deny list).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks EDIT right on the entity.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`413`	`PAYLOAD_TOO_LARGE` — the uploaded file exceeds the 100 MiB limit.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.
`503`	`SERVICE_UNAVAILABLE` — media storage is not configured or temporarily unavailable.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>	Media descriptor identifier. This is the reference the entity field stores.
`entity_id`	string<uuid>
`field_key`	string	Entity field key the media is attached to.
`content_type`	string	Server-determined MIME type (from magic-byte sniff).
`byte_size`	integer	Binary payload size in bytes.
`file_name`	string	Sanitized display filename.
`checksum_sha256`	string	SHA-256 hex digest of the binary content.
`created_at`	string<date-time>

GET /v1/entities/{entityId}/media/{mediaId}

Get entity media (authenticated delivery)

Streams the binary payload of an entity media asset. The caller's `can_read` right on the owning entity is re-validated on every request. Returns the binary with appropriate `Content-Type`, `Cache-Control: private`, `X-Content-Type-Options: nosniff`, and a restrictive `Content-Security-Policy: default-src 'none'; sandbox`. Browser-renderable media (image/audio/video) is served `inline`; all other types force `Content-Disposition: attachment`. Content-addressed binaries support conditional GET with `If-None-Match`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).
`mediaId`	path	string<uuid>	yes	Media descriptor identifier (UUIDv7).

Responses

Status	Description
`200`	Binary payload with appropriate media content-type headers.
`304`	Not Modified — content unchanged since the ETag supplied in `If-None-Match`.
`400`	`VALIDATION_ERROR` — one or both path UUIDs are malformed.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`404`	`NOT_FOUND` — media or owning entity not found, or caller lacks read access (anti-enumeration: no access collapses to 404).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.
`503`	`SERVICE_UNAVAILABLE` — media storage is not configured or unavailable.

POST /v1/entities/{entityId}/purge

Hard-purge an entity

Permanently deletes an entity and all associated data. Requires the five-right `can_purge` right (SP-enforced). This operation is irreversible.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Responses

Status	Description
`200`	Entity permanently deleted.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/entities/{entityId}/transition

Transition entity workflow state

Moves an entity to a new workflow state. Requires `project.view` (SP enforces the five-right EDIT gate plus step role/group requirements). An illegal workflow edge returns `CONFLICT`; an unknown state returns `VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityId`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`to_state_id`	string<uuid>	yes	Target workflow-state identifier.
`expected_updated_at`	string<date-time>	no	Optimistic-concurrency precondition (same contract as entity update).

Responses

Status	Description
`200`	Entity transitioned to the new workflow state.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (unknown `to_state_id`).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks edit access or does not meet the step's role/group requirement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	`CONFLICT` — illegal workflow edge (no transition defined from the current state to `to_state_id`), or optimistic-concurrency mismatch.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/entities/{type}/{id}/pin

Pin an entity

Pins (bookmarks) an entity to the authenticated user's sidebar. The caller must have view access on the entity (`project.view` permission). Per-user cap of 20 pins per entity type; exceeding the cap returns `CONFLICT`. 403 and 404 responses collapse to a uniform `NOT_FOUND` (anti-enumeration).

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`type`	path	string	yes	Entity type key (e.g. `project`). Unknown types return `400 INVALID_PARAMETER`.
`id`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`position`	integer	no	Optional display position in the pinned list.

Responses

Status	Description
`201`	Entity pinned.
`400`	`INVALID_PARAMETER` (unknown type), `INVALID_ID_FORMAT` (bad entity UUID), `INVALID_JSON` (malformed body), or `VALIDATION_ERROR` (invalid `position`).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`404`	`NOT_FOUND` — entity does not exist, is not visible to the caller, or the caller lacks view access (anti-enumeration: 403 collapses to 404).
`409`	`CONFLICT` — per-user pin cap (20) for this entity type has been reached.
`429`	429 Too Many Requests — a rate limit or usage quota was exceeded. Retry after the indicated window.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>
`user_id`	string<uuid>
`entity_type`	string
`entity_id`	string<uuid>
`position`	integer
`created_at`	string<date-time>

DELETE /v1/entities/{type}/{id}/pin

Unpin an entity

Removes an entity pin for the authenticated user. As with pin creation, 403 and 404 responses collapse to `NOT_FOUND` (anti-enumeration). The DELETE body must be empty.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`type`	path	string	yes	Entity type key.
`id`	path	string<uuid>	yes	Entity identifier (UUIDv7).

Responses

Status	Description
`200`	Entity unpinned.
`400`	`INVALID_PARAMETER` (unknown type), `INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (non-empty body).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`404`	`NOT_FOUND` — pin or entity not found, or caller lacks view access (anti-enumeration).
`429`	429 Too Many Requests — a rate limit or usage quota was exceeded. Retry after the indicated window.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/entity-permissions

List entity permission grants

Returns entity permission grants for the caller's organization. Supports filtering by resource type and resource id. Paginated. Access is SP-gated to resource owners and org admins.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`resource_type`	query	string (enum)	no	Filter by resource type.
`resource_id`	query	string<uuid>	no	Filter to a specific resource (UUIDv7).
`include_revoked`	query	boolean	no	When `true`, include revoked grants.
`page`	query	integer	no	1-based page number.
`page_size`	query	integer	no	Records per page (max 200).

Responses

Status	Description
`200`	List of permission grants.
`400`	`INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/entity-permissions

Create an entity permission grant

Creates a five-right permission grant on an entity or entity type. Exactly one of `resource_id` or `criteria` must be provided. Criteria-based grants are restricted to org admins. Requires `project.view` (the SP gates to resource owner or org admin).

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`resource_type`	string (enum) `entityentity_type`	yes
`resource_id`	string<uuid>	no	Specific resource identifier. Mutually exclusive with `criteria`.
`criteria`	object	no	JSONB criteria for a rule-based grant (org admin only). Mutually exclusive with `resource_id`.
`subject_scope`	string (enum) `userprojectgroupdepartmentorg`	yes
`subject_id`	string<uuid>	no
`can_visibility`	boolean	no
`can_read`	boolean	no
`can_edit`	boolean	no
`can_delete`	boolean	no
`can_purge`	boolean	no
`permission_flag`	string	no	Optional named custom permission flag (must match `^[a-z][a-z0-9_]{0,63}$`).

Responses

Status	Description
`201`	Grant created.
`400`	`INVALID_JSON` or `VALIDATION_ERROR` (missing `resource_id`/`criteria`, both supplied, invalid permission flag name).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>
`org_id`	string<uuid>
`resource_type`	string (enum) `entityentity_type`
`resource_id`	string<uuid>
`criteria`	object
`subject_scope`	string (enum) `userprojectgroupdepartmentorg`
`subject_id`	string<uuid>
`can_visibility`	boolean
`can_read`	boolean
`can_edit`	boolean
`can_delete`	boolean
`can_purge`	boolean
`permission_flag`	string
`revoked_at`	string<date-time>
`created_at`	string<date-time>

DELETE /v1/entity-permissions/{permissionId}

Revoke an entity permission grant

Revokes an entity or entity-type permission grant. Authorization and ownership are resolved SP-side from the grant within the caller's organization. Requires `project.view` (the SP gates to resource owner or org admin).

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`permissionId`	path	string<uuid>	yes	Permission grant identifier (UUIDv7).

Responses

Status	Description
`200`	Grant revoked.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/entity-types

List entity types

Returns the entity types visible to the caller's organization. Optionally filtered by project. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`project_id`	query	string<uuid>	no	Filter to entity types associated with a specific project.
`limit`	query	integer	no	Maximum number of records to return. Default and ceiling are endpoint-specific (commonly default 25–50, max 100).
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	List of entity types.
`400`	`INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/entity-types

Create an entity type

Creates a new entity type schema in the caller's organization. Requires `entity_type.create` permission. Permission-flag configuration is validated by the stored procedure; invalid flag grammar returns `VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`name`	string	yes
`slug`	string	no	URL-safe identifier. Auto-generated from `name` when omitted.
`description`	string	no
`icon`	string	no
`color`	string	no
`parent_uuid`	string<uuid>	no
`category`	string	no
`fields`	array of object	no
`ai_instructions`	object	no
`relationship_mode`	string (enum) `openrestricted`	no
`html_template`	string	no
`css_styles`	string	no
`sample_data`	string	no
`render_template_full`	string	no
`render_template_full_styles`	string	no
`render_template_icon`	string	no
`render_template_icon_styles`	string	no
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`	no
`owner_id`	string<uuid>	no
`default_entity_owner_scope`	string (enum) `creatorprojectgroupdepartmentorg`	no
`permission_flags`	object	no
`settings`	object	no

Responses

Status	Description
`201`	Entity type created.
`400`	`INVALID_JSON`, `VALIDATION_ERROR` (field constraints or SP permission-flag validation).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`409`	`CONFLICT` — an entity type with that name or slug already exists.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>
`org_id`	string<uuid>
`name`	string
`slug`	string
`description`	string
`icon`	string
`color`	string	Hex color code.
`parent_uuid`	string<uuid>
`category`	string
`fields`	array of object
`ai_instructions`	object
`relationship_mode`	string (enum) `openrestricted`
`html_template`	string
`css_styles`	string
`sample_data`	string
`render_template_full`	string	Full-card Handlebars/HTML render template (max 256 KiB).
`render_template_full_styles`	string	CSS for the full-card template (max 64 KiB).
`render_template_icon`	string	Icon-size render template (max 256 KiB).
`render_template_icon_styles`	string
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`
`owner_id`	string<uuid>
`default_entity_owner_scope`	string (enum) `creatorprojectgroupdepartmentorg`
`permission_flags`	object
`settings`	object
`adopted_source_version`	integer
`source_current_version`	integer	Non-null when this type is a subscriber clone; compare with `adopted_source_version` to detect available updates.
`created_at`	string<date-time>
`updated_at`	string<date-time>

GET /v1/entity-types/{entityTypeId}

Get an entity type

Returns a single entity type by identifier including render templates. Requires `project.view` permission. An invisible or non-existent entity type returns `NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityTypeId`	path	string<uuid>	yes	Entity type identifier (UUIDv7).

Responses

Status	Description
`200`	The entity type record.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`org_id`	string<uuid>
`name`	string
`slug`	string
`description`	string
`icon`	string
`color`	string	Hex color code.
`parent_uuid`	string<uuid>
`category`	string
`fields`	array of object
`ai_instructions`	object
`relationship_mode`	string (enum) `openrestricted`
`html_template`	string
`css_styles`	string
`sample_data`	string
`render_template_full`	string	Full-card Handlebars/HTML render template (max 256 KiB).
`render_template_full_styles`	string	CSS for the full-card template (max 64 KiB).
`render_template_icon`	string	Icon-size render template (max 256 KiB).
`render_template_icon_styles`	string
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`
`owner_id`	string<uuid>
`default_entity_owner_scope`	string (enum) `creatorprojectgroupdepartmentorg`
`permission_flags`	object
`settings`	object
`adopted_source_version`	integer
`source_current_version`	integer	Non-null when this type is a subscriber clone; compare with `adopted_source_version` to detect available updates.
`created_at`	string<date-time>
`updated_at`	string<date-time>

PUT /v1/entity-types/{entityTypeId}

Update an entity type

Updates an entity type schema. Requires `entity_type.update` permission. Changing `fields` on an entity type with live entities is validated by the stored procedure; a conflict is returned if the change would break existing data.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityTypeId`	path	string<uuid>	yes	Entity type identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`name`	string	no
`description`	string	no
`icon`	string	no
`color`	string	no
`parent_uuid`	string<uuid>	no
`category`	string	no
`fields`	array of object	no
`ai_instructions`	object	no
`relationship_mode`	string (enum) `openrestricted`	no
`html_template`	string	no
`css_styles`	string	no
`sample_data`	string	no
`render_template_full`	string	no
`render_template_full_styles`	string	no
`render_template_icon`	string	no
`render_template_icon_styles`	string	no
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`	no
`owner_id`	string<uuid>	no
`default_entity_owner_scope`	string (enum) `creatorprojectgroupdepartmentorg`	no
`permission_flags`	object	no
`changelog`	string	no	Optional human-readable change note.

Responses

Status	Description
`200`	Updated entity type.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (no fields provided or SP validation).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	`CONFLICT` — a field change is blocked because downstream entities are using the affected field; the response `details` contains which field and how many entities are affected.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`org_id`	string<uuid>
`name`	string
`slug`	string
`description`	string
`icon`	string
`color`	string	Hex color code.
`parent_uuid`	string<uuid>
`category`	string
`fields`	array of object
`ai_instructions`	object
`relationship_mode`	string (enum) `openrestricted`
`html_template`	string
`css_styles`	string
`sample_data`	string
`render_template_full`	string	Full-card Handlebars/HTML render template (max 256 KiB).
`render_template_full_styles`	string	CSS for the full-card template (max 64 KiB).
`render_template_icon`	string	Icon-size render template (max 256 KiB).
`render_template_icon_styles`	string
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`
`owner_id`	string<uuid>
`default_entity_owner_scope`	string (enum) `creatorprojectgroupdepartmentorg`
`permission_flags`	object
`settings`	object
`adopted_source_version`	integer
`source_current_version`	integer	Non-null when this type is a subscriber clone; compare with `adopted_source_version` to detect available updates.
`created_at`	string<date-time>
`updated_at`	string<date-time>

DELETE /v1/entity-types/{entityTypeId}

Soft-delete an entity type

Soft-deletes an entity type. Requires `entity_type.delete` permission. An entity type that has already been deleted returns `NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityTypeId`	path	string<uuid>	yes	Entity type identifier (UUIDv7).

Responses

Status	Description
`200`	Entity type deleted.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/entity-types/{entityTypeId}/adopt-package-update

Adopt a publisher package update for an entity type

Pulls the latest publisher package update into a subscriber clone entity type. Useful when auto-propagation was skipped because the subscriber had locally diverged. Check `adopted_source_version` versus `source_current_version` on the entity type to detect whether an update is available. Requires `entity_type.update` permission.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityTypeId`	path	string<uuid>	yes	Entity type identifier (UUIDv7) of the subscriber clone.

Responses

Status	Description
`200`	Package update adopted.
`400`	`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	`NOT_FOUND` — the packaged entity type clone was not found.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`org_id`	string<uuid>
`name`	string
`slug`	string
`description`	string
`icon`	string
`color`	string	Hex color code.
`parent_uuid`	string<uuid>
`category`	string
`fields`	array of object
`ai_instructions`	object
`relationship_mode`	string (enum) `openrestricted`
`html_template`	string
`css_styles`	string
`sample_data`	string
`render_template_full`	string	Full-card Handlebars/HTML render template (max 256 KiB).
`render_template_full_styles`	string	CSS for the full-card template (max 64 KiB).
`render_template_icon`	string	Icon-size render template (max 256 KiB).
`render_template_icon_styles`	string
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`
`owner_id`	string<uuid>
`default_entity_owner_scope`	string (enum) `creatorprojectgroupdepartmentorg`
`permission_flags`	object
`settings`	object
`adopted_source_version`	integer
`source_current_version`	integer	Non-null when this type is a subscriber clone; compare with `adopted_source_version` to detect available updates.
`created_at`	string<date-time>
`updated_at`	string<date-time>

GET /v1/entity-types/{entityTypeId}/effective-permissions

Get effective permissions on an entity type

Returns computed five-right effective permissions for the caller (or a specified in-org user) on an entity type. Self-view for any caller with visibility; `?user_id=` is SP-gated to org admins and resource creators.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityTypeId`	path	string<uuid>	yes	Entity type identifier (UUIDv7).
`user_id`	query	string<uuid>	no	Inspect effective permissions for another in-org user (org admin / resource creator only).

Responses

Status	Description
`200`	Effective permission set.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`can_visibility`	boolean
`can_read`	boolean
`can_edit`	boolean
`can_delete`	boolean
`can_purge`	boolean
`sources`	array of object	List of contributing grants that produced the effective rights.

POST /v1/entity-types/{entityTypeId}/purge

Hard-purge an entity type

Permanently deletes an entity type and all entities of that type. Requires `entity_type.delete` permission plus the five-right `can_purge` right (SP-enforced). This operation is irreversible.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entityTypeId`	path	string<uuid>	yes	Entity type identifier (UUIDv7).

Responses

Status	Description
`200`	Entity type permanently deleted.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/environments

List environments

Returns the logical deployment environments (dev, staging, preprod, prod) that the authenticated user can access within their organization. The `multi-environment` feature flag must be enabled; the endpoint is gated server-side.

Auth Session JWT (Bearer)

Responses

Status	Description
`200`	Array of environment objects the caller can access.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks organization membership or the `multi-environment` feature is disabled.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/environments

Create an environment

Creates a new non-production logical environment (`dev`, `staging`, or `preprod`) for the caller's organization. Requires organization admin role and the `multi-environment` feature flag. The `prod` key is reserved and cannot be created via this route.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`env_key`	string (enum) `devstagingpreprod`	yes	The environment tier to create. `prod` cannot be created via this surface.
`display_name`	string	no	Optional human-readable label for the environment.

{
  "env_key": "staging",
  "display_name": "Staging"
}

Responses

Status	Description
`201`	Environment created.
`400`	`INVALID_JSON` (malformed body) or `VALIDATION_ERROR` (unknown `env_key`, extra fields).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `INSUFFICIENT_PERMISSIONS` — caller is not an org admin or the feature is disabled.
`409`	`CONFLICT` — an environment with that key already exists in this organization.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>	Environment identifier (UUIDv7).
`org_id`	string<uuid>	Owning organization identifier.
`env_key`	string (enum) `devstagingpreprodprod`	Canonical environment key.
`display_name`	string	Human-readable display name.
`is_default`	boolean	True for the production (default) environment.
`created_at`	string<date-time>
`updated_at`	string<date-time>

GET /v1/environments/{id}/grants

List environment grants

Returns the access grants for a specific environment. Requires organization admin role; the stored procedure enforces the authorization check.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	Environment identifier (UUIDv7).
`include_revoked`	query	boolean	no	When `true`, include revoked grants in the response. Defaults to `false`.

Responses

Status	Description
`200`	List of grants for the environment.
`400`	`INVALID_ID_FORMAT` — the `id` path parameter is not a valid UUID.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `INSUFFICIENT_PERMISSIONS` — caller is not an org admin.
`404`	`NOT_FOUND` — environment does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/environments/{id}/grants

Create an environment grant

Grants a user, group, department, or role access to an environment. Requires organization admin role.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	Environment identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`scope`	string (enum) `usergroupdepartmentrole`	yes	The principal scope being granted.
`target_id`	string	yes	Identifier of the principal within the given scope.
`capability`	string (enum) `membermanage`	no	Access level granted. Defaults to `member` when omitted.

Responses

Status	Description
`201`	Grant created.
`400`	`INVALID_ID_FORMAT` (bad path param), `INVALID_JSON` (malformed body), or `VALIDATION_ERROR` (invalid scope/capability).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `INSUFFICIENT_PERMISSIONS` — caller is not an org admin.
`409`	`CONFLICT` — a grant for this principal already exists on this environment.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>
`env_id`	string<uuid>
`scope`	string (enum) `usergroupdepartmentrole`
`target_id`	string	Principal identifier within the scope.
`capability`	string (enum) `membermanage`
`revoked_at`	string<date-time>
`created_at`	string<date-time>

DELETE /v1/environments/{id}/grants/{grantId}

Revoke an environment grant

Revokes an environment access grant. Idempotent — revoking an already-revoked grant is a no-op. The environment `id` is validated for format; authorization and ownership are resolved from the grant id within the caller's organization.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	Environment identifier (UUIDv7).
`grantId`	path	string<uuid>	yes	Grant identifier (UUIDv7).

Responses

Status	Description
`200`	Grant revoked (or was already revoked).
`400`	`INVALID_ID_FORMAT` — one or both path parameters is not a valid UUID.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller is not an org admin.
`404`	`NOT_FOUND` — grant does not exist within the caller's organization.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/org/{orgId}/templates

List project templates (org-scoped)

Org-scoped alias for `GET /v1/templates`. The `orgId` path parameter must match the authenticated session's organization; a mismatch returns `TENANT_ACCESS_DENIED`. Identical query parameters and response shape.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`orgId`	path	string<uuid>	yes	Organization identifier (UUIDv7).
`is_published`	query	boolean	no
`page`	query	integer	no
`page_size`	query	integer	no
`search`	query	string	no

Responses

Status	Description
`200`	List of templates.
`400`	`INVALID_ID_FORMAT` (bad orgId) or `INVALID_PARAMETER` (bad query).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN`, `TENANT_ACCESS_DENIED` (orgId mismatch).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`templates`	array of object

POST /v1/org/{orgId}/templates

Create a project template (org-scoped)

Org-scoped alias for `POST /v1/templates`. The `orgId` path parameter must match the authenticated session's organization.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`orgId`	path	string<uuid>	yes	Organization identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`name`	string	yes	Display name for the template.
`description`	string	no	Optional human-readable description. Content is screened by the platform content-safety gate; prohibited content returns `CONTENT_POLICY_VIOLATION`.
`config`	object	no	Arbitrary JSON configuration (project structure, entity types, etc.). Defaults to `{}`.
`source_project_id`	string<uuid>	no	Optional project to seed the template from.

Responses

Status	Description
`201`	Template created.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`, or `CONTENT_POLICY_VIOLATION`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED`.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`template`	object	A project template that can be used as a starting point when creating new projects.

GET /v1/org/{orgId}/templates/{id}

Get a project template (org-scoped)

Org-scoped alias for `GET /v1/templates/{id}`. The `orgId` must match the session organization.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`orgId`	path	string<uuid>	yes	Organization identifier (UUIDv7).
`id`	path	string<uuid>	yes	Template identifier (UUIDv7).

Responses

Status	Description
`200`	The template record.
`400`	`INVALID_ID_FORMAT` or `TENANT_ACCESS_DENIED`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`template`	object	A project template that can be used as a starting point when creating new projects.

PUT /v1/org/{orgId}/templates/{id}

Update a project template (org-scoped)

Org-scoped alias for `PUT /v1/templates/{id}`. The `orgId` must match the session organization.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`orgId`	path	string<uuid>	yes	Organization identifier (UUIDv7).
`id`	path	string<uuid>	yes	Template identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`name`	string	no
`description`	string	no	Set to `null` to clear. Content is screened by the platform content-safety gate.
`config`	object	no	Replaces the template configuration.
`changelog`	string	no	Optional human-readable change note for this version.

Responses

Status	Description
`200`	The updated template.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`, or `CONTENT_POLICY_VIOLATION`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`template`	object	A project template that can be used as a starting point when creating new projects.

DELETE /v1/org/{orgId}/templates/{id}

Delete a project template (org-scoped)

Org-scoped alias for `DELETE /v1/templates/{id}`. The `orgId` must match the session organization.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`orgId`	path	string<uuid>	yes	Organization identifier (UUIDv7).
`id`	path	string<uuid>	yes	Template identifier (UUIDv7).

Responses

Status	Description
`200`	Template deleted.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/org/{orgId}/templates/{templateId}/versions

List template versions (org-scoped)

Org-scoped alias for `GET /v1/templates/{templateId}/versions`. The `orgId` must match the session organization.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`orgId`	path	string<uuid>	yes	Organization identifier (UUIDv7).
`templateId`	path	string<uuid>	yes	Template identifier (UUIDv7).
`page`	query	integer	no
`page_size`	query	integer	no

Responses

Status	Description
`200`	Paginated version history.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`versions`	array of object
`meta`	object	Pagination metadata. Endpoints use either page/pageSize or limit/offset style; fields present depend on the endpoint.

GET /v1/projects/{projectId}/entities

List entities in a project

Returns entities within a project with offset pagination. Requires `project.view` permission. Supports filtering by entity type, parent, and status.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`entity_type_id`	query	string<uuid>	no	Filter to a specific entity type (UUIDv7).
`parent_id`	query	string<uuid>	no	Filter to direct children of a parent entity.
`status`	query	string	no	Filter by entity status string.
`limit`	query	integer	no	Maximum number of records to return. Default and ceiling are endpoint-specific (commonly default 25–50, max 100).
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	Paginated entity list.
`400`	`INVALID_ID_FORMAT` (bad projectId) or `INVALID_PARAMETER` (bad query).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/entities

Create an entity

Creates a new entity of the specified type within a project. Requires `project.update` permission. Returns the platform-assigned entity identifier.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`entity_type_id`	string<uuid>	yes	Entity type to instantiate.
`name`	string	yes	Display name for the entity.
`parent_id`	string<uuid>	no	Optional parent entity for tree nesting.
`data`	object	no	Field bag (alias: `metadata`). Only one need be supplied; they are merged.
`metadata`	object	no	Alias for `data`. Symmetric with the GET response field name.
`owner_scope`	string (enum) `userprojectgroupdepartmentorg`	no
`owner_id`	string<uuid>	no

Responses

Status	Description
`201`	Entity created. Returns the entity identifier.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (constraint or SP validation refusal).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	`NOT_FOUND` — the referenced `entity_type_id` or `parent_id` does not exist.
`409`	`CONFLICT` — a unique constraint was violated.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>

GET /v1/projects/{projectId}/entities/search

Search entities in a project

Full-text search over entities within a project. Requires `project.view` permission. The `query` parameter is required.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`query`	query	string	yes	Search terms (1–256 chars).
`entity_type_id`	query	string<uuid>	no	Restrict search to a specific entity type.
`limit`	query	integer	no	Maximum number of records to return. Default and ceiling are endpoint-specific (commonly default 25–50, max 100).
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	Search results.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/projects/{projectId}/entities/tree

Get entity tree

Returns the entity hierarchy for a project as a nested tree structure. Requires `project.view` permission. Optionally starts from a specific root entity and limits depth.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`root_entity_id`	query	string<uuid>	no	Start the tree from this entity (UUIDv7). Defaults to the project root.
`max_depth`	query	integer	no	Maximum tree depth to traverse (1–20, default 20).

Responses

Status	Description
`200`	Nested entity tree.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller is not a member of the project.
`404`	`NOT_FOUND` — project does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/projects/{projectId}/pipeline

Get project pipeline configuration

Returns the CI/CD pipeline configuration for a project. Requires `project.view`. The `project_deployments` and `containers` system feature flags must be enabled; if not, all pipeline endpoints return `FORBIDDEN`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).

Responses

Status	Description
`200`	Pipeline configuration.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks project view access, or required feature flags are disabled.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`project_id`	string<uuid>
`org_repo_id`	string<uuid>	Connected repository identifier.
`deploy_connection_id`	string<uuid>	Optional deployment connection override.
`default_backend`	string
`allow_free_form`	boolean
`is_active`	boolean
`environments`	array of object
`created_at`	string<date-time>
`updated_at`	string<date-time>

PUT /v1/projects/{projectId}/pipeline

Create or update project pipeline configuration

Creates or updates the CI/CD pipeline root configuration for a project. Requires `project.update`. The `org_repo_id` linking the project to a connected repository is required. Idempotent: repeated calls update in place.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`org_repo_id`	string<uuid>	yes	Connected repository identifier. Required.
`deploy_connection_id`	string<uuid>	no
`default_backend`	string	no
`allow_free_form`	boolean	no
`is_active`	boolean	no

Responses

Status	Description
`200`	Pipeline configuration upserted.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (missing `org_repo_id`, field bounds).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`project_id`	string<uuid>
`org_repo_id`	string<uuid>	Connected repository identifier.
`deploy_connection_id`	string<uuid>	Optional deployment connection override.
`default_backend`	string
`allow_free_form`	boolean
`is_active`	boolean
`environments`	array of object
`created_at`	string<date-time>
`updated_at`	string<date-time>

PUT /v1/projects/{projectId}/pipeline/environments

Create or update a pipeline environment

Creates or updates a single pipeline environment definition for a project. Requires `project.update`. If `id` is present in the body the matching environment row is updated; otherwise a new row is created. Call once per environment to build the full set.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`id`	string<uuid>	no	If provided, identifies an existing environment to update.
`name`	string	yes
`env_id`	string<uuid>	yes
`rank`	integer	yes
`branch`	string	yes
`working_dir`	string	no
`deploy_commands`	array of array	no
`container_size`	string	no
`backend`	string	no
`egress_allowlist`	array of string	no
`is_protected`	boolean	no
`auto_deploy_on_push`	boolean	no

Responses

Status	Description
`200`	Pipeline environments upserted.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (field bounds, duplicate rank, invalid commit SHA pattern).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

PUT /v1/projects/{projectId}/pipeline/environments/{envId}/approval-policy

Set pipeline environment approval policy

Creates or replaces the approval gate policy for a protected pipeline environment. Requires `project.update`. Protected environments require N-of-M approval before a promotion can start.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`envId`	path	string<uuid>	yes	Pipeline environment identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`rules`	any	no	Approval rule set. Shape is opaque to the API — validated SP-side.
`allow_self_approval`	boolean	no	When false, the user who triggered the run cannot approve it. Defaults to false.

Responses

Status	Description
`200`	Approval policy set.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (invalid rule grammar).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/pipeline/environments/{envId}/deploy

Trigger a deploy for a pipeline environment

Enqueues a deploy run for a specific pipeline environment. Requires `project.update`. An optional `commit_sha` (40 hex chars case-insensitive) pins the deploy to a specific commit; omitting it deploys the branch HEAD.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`envId`	path	string<uuid>	yes	Pipeline environment identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`commit_sha`	string	no	Optional full 40-hex-char commit SHA to deploy. Omit to deploy branch HEAD.

Responses

Status	Description
`200`	Deploy run enqueued.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (malformed commit SHA).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`project_id`	string<uuid>
`pipeline_env_id`	string<uuid>
`triggered_by`	string<uuid>
`run_type`	string (enum) `deploypromote`	Whether this is a direct deploy or a promotion.
`status`	string (enum) `queuedrunningsucceededfailedcancelledawaiting_approval`
`commit_sha`	string	The commit SHA being deployed.
`created_at`	string<date-time>
`started_at`	string<date-time>
`completed_at`	string<date-time>

PUT /v1/projects/{projectId}/pipeline/environments/{envId}/secrets/{itemId}

Set a pipeline environment secret

Creates or updates a secret override for a pipeline environment. Requires `project.update`. The `content_fp` is a content fingerprint of the secret value, not the value itself.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`envId`	path	string<uuid>	yes	Pipeline environment identifier (UUIDv7).
`itemId`	path	string<uuid>	yes	Secret item identifier (UUIDv7). Must match `item_id` in the body when provided.

Request Body

Field	Type	Required	Description
`item_id`	string<uuid>	no	Optional — if supplied, must match the path `itemId`.
`content_fp`	string	yes	Content fingerprint of the secret value.

Responses

Status	Description
`200`	Secret set.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (content_fp missing or too long).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/pipeline/environments/{envId}/vault

Bind a vault to a pipeline environment

Attaches a vault to a pipeline environment, making its secrets available during deploys. Requires `project.update`. The `members_fp` is a content fingerprint of the vault members list at bind time, used to detect drift.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`envId`	path	string<uuid>	yes	Pipeline environment identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`vault_id`	string<uuid>	yes	The vault to bind.
`members_fp`	string	yes	Content fingerprint of the vault members list at bind time.

Responses

Status	Description
`200`	Vault bound to pipeline environment.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

DELETE /v1/projects/{projectId}/pipeline/environments/{envId}/vault

Unbind a vault from a pipeline environment

Removes the vault binding from a pipeline environment. Requires `project.update`. The request body must be empty.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`envId`	path	string<uuid>	yes	Pipeline environment identifier (UUIDv7).

Responses

Status	Description
`200`	Vault binding removed.
`400`	`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (non-empty body).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/pipeline/promote/prepare

Prepare a pipeline promotion

Validates a promotion between pipeline environments and returns a run id. Requires `project.update`. Optional source and target commit SHAs and a `content_fp` content fingerprint allow specifying the exact artifact to promote.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`source_environment_id`	string<uuid>	yes	Source pipeline environment.
`target_environment_id`	string<uuid>	yes	Target pipeline environment.
`source_commit_sha`	string	no	Optional source commit SHA.
`target_base_commit_sha`	string	no	Optional target base commit SHA for diff calculation.
`content_fp`	string	no	Optional artifact content fingerprint.

Responses

Status	Description
`200`	Promotion validated. Returns a `run_id` to pass to `POST /promote/start`.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR` (malformed SHA, missing required fields).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	`CONFLICT` — a promotion is already in flight for the target environment.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`run_id`	string<uuid>

POST /v1/projects/{projectId}/pipeline/promote/start

Start a prepared pipeline promotion

Starts a previously prepared promotion run. Requires `project.update`. The `run_id` must refer to a run in `prepared` state from a prior `/promote/prepare` call.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`run_id`	string<uuid>	yes	The run_id returned by `/promote/prepare`.

Responses

Status	Description
`200`	Promotion started.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (run not in prepared state).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`project_id`	string<uuid>
`pipeline_env_id`	string<uuid>
`triggered_by`	string<uuid>
`run_type`	string (enum) `deploypromote`	Whether this is a direct deploy or a promotion.
`status`	string (enum) `queuedrunningsucceededfailedcancelledawaiting_approval`
`commit_sha`	string	The commit SHA being deployed.
`created_at`	string<date-time>
`started_at`	string<date-time>
`completed_at`	string<date-time>

GET /v1/projects/{projectId}/pipeline/runs

List pipeline runs

Returns pipeline deploy runs for a project with cursor-based pagination. Optionally filtered by `env_id`. Requires `project.view`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`env_id`	query	string<uuid>	no	Filter to runs for a specific pipeline environment.
`cursor`	query	string	no	Opaque cursor from the previous page's response for pagination.
`limit`	query	integer	no	Maximum runs to return per page.

Responses

Status	Description
`200`	Paginated list of pipeline runs.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/pipeline/runs/{runId}/approve

Approve or reject a pipeline run

Submits an approval or rejection decision on a pipeline run waiting at a protected environment gate. Requires `project.update`. Self-approval is blocked if `allow_self_approval=false` on the environment's approval policy.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`runId`	path	string<uuid>	yes	Pipeline run identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`action`	string (enum) `approvereject`	yes	Approval decision.

Responses

Status	Description
`200`	Approval decision recorded.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (unknown action, run not awaiting approval).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` — caller lacks permission, or `allow_self_approval=false` and the caller is the run initiator.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	`CONFLICT` — the run has already been approved/rejected by this user or has moved to a terminal state.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/pipeline/runs/{runId}/cancel

Cancel an active pipeline run

Requests cancellation of an in-progress pipeline run. Requires `project.update`. The run must be in a non-terminal state.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`runId`	path	string<uuid>	yes	Pipeline run identifier (UUIDv7).

Responses

Status	Description
`200`	Cancellation requested.
`400`	`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (run is already in a terminal state).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`409`	`CONFLICT` — the run has already transitioned to a terminal state.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/projects/{projectId}/pipeline/runs/{runId}/events

Get pipeline run events

Returns the event stream for a pipeline run (log lines, status changes, step boundaries). Supports tail-following via `after_seq`. Requires `project.view`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`runId`	path	string<uuid>	yes	Pipeline run identifier (UUIDv7).
`after_seq`	query	integer	no	Sequence number of the last event seen; returns only events after this sequence.
`limit`	query	integer	no	Maximum events to return.

Responses

Status	Description
`200`	List of pipeline run events.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/projects/{projectId}/pipeline/runs/{runId}/retry

Retry a failed pipeline run

Retries a failed or cancelled pipeline run, creating a new run from the same configuration. Requires `project.update`. The run must be in a terminal state. Request body must be empty.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`runId`	path	string<uuid>	yes	Pipeline run identifier (UUIDv7).

Responses

Status	Description
`200`	New retry run enqueued.
`400`	`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (run is not in a terminal state).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`project_id`	string<uuid>
`pipeline_env_id`	string<uuid>
`triggered_by`	string<uuid>
`run_type`	string (enum) `deploypromote`	Whether this is a direct deploy or a promotion.
`status`	string (enum) `queuedrunningsucceededfailedcancelledawaiting_approval`
`commit_sha`	string	The commit SHA being deployed.
`created_at`	string<date-time>
`started_at`	string<date-time>
`completed_at`	string<date-time>

GET /v1/relationship-types

List relationship types

Returns all relationship types visible to the caller's organization. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	no	Maximum number of records to return. Default and ceiling are endpoint-specific (commonly default 25–50, max 100).
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	List of relationship types.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/relationship-types

Create a relationship type

Defines a new directed relationship type with forward and reverse labels. Requires `relationship_type.create` permission. Duplicate `name` within the organization returns `CONFLICT`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`name`	string	yes
`forward_label`	string	yes
`reverse_label`	string	yes
`description`	string	no
`icon`	string	no
`color`	string	no	Hex color (e.g. `#FF5733` or `#F53`).

Responses

Status	Description
`201`	Relationship type created.
`400`	`INVALID_JSON` or `VALIDATION_ERROR` (field constraints).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`409`	`CONFLICT` — a relationship type with that name already exists in the organization.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>	Relationship type identifier (UUIDv7).
`org_id`	string<uuid>
`name`	string	Internal unique name within the organization.
`forward_label`	string	Human-readable label for the source→target direction (e.g. 'blocks').
`reverse_label`	string	Human-readable label for the target→source direction (e.g. 'blocked by').
`description`	string
`icon`	string
`color`	string	Optional hex color for display (e.g. `#FF5733` or `#F53`).
`created_at`	string<date-time>

GET /v1/relationships

List entity relationships

Returns relationships for a specific entity. The `entity_id` query parameter is required. Optionally filtered by relationship type UUID and direction. Requires `project.view` on the entity.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`entity_id`	query	string<uuid>	yes	The entity whose relationships to list (UUIDv7).
`type`	query	string<uuid>	no	Filter to a specific relationship type (UUIDv7).
`direction`	query	string (enum)	no	Filter by direction from the reference entity. `outgoing` returns edges where the entity is the source; `incoming` returns edges where it is the target.
`limit`	query	integer	no	Maximum number of records to return. Default and ceiling are endpoint-specific (commonly default 25–50, max 100).
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	List of relationships.
`400`	`INVALID_ID_FORMAT` (entity_id not a UUID) or `INVALID_PARAMETER` (unknown direction).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/relationships

Create a relationship between entities

Creates a directional relationship between two entities. Source and target must differ (`VALIDATION_ERROR` if equal). Requires `project.update` permission. Duplicate (source, target, type) returns `CONFLICT`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`source_entity_id`	string<uuid>	yes	Source entity. Must differ from `target_entity_id`.
`target_entity_id`	string<uuid>	yes	Target entity. Must differ from `source_entity_id`.
`relationship_type_id`	string<uuid>	yes	Relationship type identifier.
`metadata`	object	no	Optional JSONB metadata to attach to the edge.

Responses

Status	Description
`201`	Relationship created.
`400`	`INVALID_JSON`, `VALIDATION_ERROR` (same source/target, missing fields), or `INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	`NOT_FOUND` — source entity, target entity, or relationship type not found.
`409`	`CONFLICT` — a relationship of this type between these two entities already exists.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>	Relationship identifier (UUIDv7).
`source_entity_id`	string<uuid>	Source (origin) entity.
`target_entity_id`	string<uuid>	Target (destination) entity.
`relationship_type_id`	string<uuid>	The type that defines this edge's semantics.
`metadata`	object	Arbitrary JSONB metadata.
`created_at`	string<date-time>
`updated_at`	string<date-time>

DELETE /v1/relationships/{relationshipId}

Delete a relationship

Removes a relationship edge. Requires `project.delete` permission on the source entity.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`relationshipId`	path	string<uuid>	yes	Relationship identifier (UUIDv7).

Responses

Status	Description
`200`	Relationship deleted.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/templates

List project templates

Returns project templates visible to the authenticated caller within their organization. Supports filtering by publication status and free-text search.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`is_published`	query	boolean	no	Filter by publication state. Omit to return all visible templates.
`page`	query	integer	no	1-based page number (default 1, max 100000).
`page_size`	query	integer	no	Records per page (default 100, max 100).
`search`	query	string	no	Free-text search over template names/descriptions (max 500 chars).

Responses

Status	Description
`200`	List of templates.
`400`	`INVALID_PARAMETER` — an invalid query parameter value was supplied.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED` — caller lacks template view access or the `orgId` path param does not match the session org.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`templates`	array of object

POST /v1/templates

Create a project template

Creates a new project template in the caller's organization. The `description` field is screened by the platform content-safety gate; prohibited content returns `CONTENT_POLICY_VIOLATION`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`name`	string	yes	Display name for the template.
`description`	string	no	Optional human-readable description. Content is screened by the platform content-safety gate; prohibited content returns `CONTENT_POLICY_VIOLATION`.
`config`	object	no	Arbitrary JSON configuration (project structure, entity types, etc.). Defaults to `{}`.
`source_project_id`	string<uuid>	no	Optional project to seed the template from.

Responses

Status	Description
`201`	Template created.
`400`	`INVALID_JSON` (malformed body), `VALIDATION_ERROR` (field constraint), or `CONTENT_POLICY_VIOLATION` (description content rejected).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED`.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`template`	object	A project template that can be used as a starting point when creating new projects.

GET /v1/templates/{id}

Get a project template

Returns a single project template by identifier. Templates not visible to the caller are reported as `NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	Template identifier (UUIDv7).

Responses

Status	Description
`200`	The template record.
`400`	`INVALID_ID_FORMAT` — the `id` path parameter is not a valid UUID.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED`.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`template`	object	A project template that can be used as a starting point when creating new projects.

PUT /v1/templates/{id}

Update a project template

Updates a project template's name, description, config, or changelog. At least one field must be provided. The `description` field is screened by the content-safety gate.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	Template identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`name`	string	no
`description`	string	no	Set to `null` to clear. Content is screened by the platform content-safety gate.
`config`	object	no	Replaces the template configuration.
`changelog`	string	no	Optional human-readable change note for this version.

Responses

Status	Description
`200`	The updated template record.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR` (no fields provided or field constraint), or `CONTENT_POLICY_VIOLATION`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED`.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`template`	object	A project template that can be used as a starting point when creating new projects.

DELETE /v1/templates/{id}

Delete a project template

Deletes a project template from the caller's organization. Requires the caller to own or have admin rights over the template (enforced by the stored procedure).

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	Template identifier (UUIDv7).

Responses

Status	Description
`200`	Template deleted.
`400`	`INVALID_ID_FORMAT` — the `id` path parameter is not a valid UUID.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED`.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/templates/{templateId}/versions

List template versions

Returns the version history of a project template with page-based pagination. The caller must have visibility on the template.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`templateId`	path	string<uuid>	yes	Template identifier (UUIDv7).
`page`	query	integer	no	1-based page number (default 1, max 100000).
`page_size`	query	integer	no	Records per page (default 25, max 100).

Responses

Status	Description
`200`	Paginated version history.
`400`	`INVALID_ID_FORMAT` or `INVALID_PARAMETER` (unknown query param — strict schema).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	`FORBIDDEN` or `TENANT_ACCESS_DENIED`.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`versions`	array of object
`meta`	object	Pagination metadata. Endpoints use either page/pageSize or limit/offset style; fields present depend on the endpoint.

GET /v1/views

List views

Returns saved views accessible to the caller within an organization. Filterable by `project_id`, `view_type`, and `is_shared`. Paginated.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`project_id`	query	string<uuid>	no	Filter to views belonging to a specific project.
`view_type`	query	string (enum)	no	Filter by view rendering type.
`is_shared`	query	boolean	no	When `true`, return only shared views; `false` returns private views.
`limit`	query	integer	no
`offset`	query	integer	no	Number of records to skip for offset pagination.

Responses

Status	Description
`200`	Paginated view list.
`400`	`INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/views

Create a view

Creates a new saved view. Only `name` is required; `view_type` defaults to `list`. If `project_id` is supplied the caller must have `project.update` permission on that project. SP validates the unified `config` object; invalid config returns `VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required
`name`	string	yes
`description`	string	no
`view_type`	string (enum) `boardlisttablecalendartimelinegantt`	no
`project_id`	string<uuid>	no
`config`	object	no
`filters`	object	no
`columns`	array of object	no
`sort_config`	object	no
`group_by`	string	no
`is_default`	boolean	no
`is_shared`	boolean	no
`metadata`	object	no

Responses

Status	Description
`201`	View created.
`400`	`INVALID_JSON` or `VALIDATION_ERROR` (name length, unknown view_type, missing project_id).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>	View identifier (UUIDv7).
`org_id`	string<uuid>
`project_id`	string<uuid>
`created_by`	string<uuid>
`name`	string
`description`	string
`view_type`	string (enum) `boardlisttablecalendartimelinegantt`
`config`	object	View-type-specific rendering configuration.
`filters`	object	Filter expression applied before rendering.
`columns`	array of object	Column or field order/visibility config.
`sort_config`	object	Sort specification.
`group_by`	string	Field key to group rows by.
`is_default`	boolean
`is_shared`	boolean
`metadata`	object
`created_at`	string<date-time>
`updated_at`	string<date-time>

GET /v1/views/{viewId}

Get a view

Returns a saved view by identifier. Requires `project.view` on the owning project.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`viewId`	path	string<uuid>	yes	View identifier (UUIDv7).

Responses

Status	Description
`200`	The view record.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>	View identifier (UUIDv7).
`org_id`	string<uuid>
`project_id`	string<uuid>
`created_by`	string<uuid>
`name`	string
`description`	string
`view_type`	string (enum) `boardlisttablecalendartimelinegantt`
`config`	object	View-type-specific rendering configuration.
`filters`	object	Filter expression applied before rendering.
`columns`	array of object	Column or field order/visibility config.
`sort_config`	object	Sort specification.
`group_by`	string	Field key to group rows by.
`is_default`	boolean
`is_shared`	boolean
`metadata`	object
`created_at`	string<date-time>
`updated_at`	string<date-time>

PUT /v1/views/{viewId}

Update a view

Updates a saved view's configuration. Requires `project.update` on the owning project. At least one field must be provided.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`viewId`	path	string<uuid>	yes	View identifier (UUIDv7).

Request Body

Field	Type	Required
`name`	string	no
`description`	string	no
`config`	object	no
`filters`	object	no
`columns`	array of object	no
`sort_config`	object	no
`group_by`	string	no
`is_default`	boolean	no
`is_shared`	boolean	no
`metadata`	object	no

Responses

Status	Description
`200`	Updated view record.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (no fields provided).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>	View identifier (UUIDv7).
`org_id`	string<uuid>
`project_id`	string<uuid>
`created_by`	string<uuid>
`name`	string
`description`	string
`view_type`	string (enum) `boardlisttablecalendartimelinegantt`
`config`	object	View-type-specific rendering configuration.
`filters`	object	Filter expression applied before rendering.
`columns`	array of object	Column or field order/visibility config.
`sort_config`	object	Sort specification.
`group_by`	string	Field key to group rows by.
`is_default`	boolean
`is_shared`	boolean
`metadata`	object
`created_at`	string<date-time>
`updated_at`	string<date-time>

DELETE /v1/views/{viewId}

Delete a view

Soft-deletes a saved view. Requires `project.update` on the owning project.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`viewId`	path	string<uuid>	yes	View identifier (UUIDv7).

Responses

Status	Description
`200`	View deleted.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/views/{viewId}/execute

Execute a view query (legacy GET alias)

Legacy GET alias for view execution. Prefer `POST /v1/views/{viewId}/execute`. Returns a combined view-config-plus-results object rather than a bare row array. The `limit` and `offset` query params are not forwarded; the response always uses default pagination (limit 50, offset 0). Clients should migrate to the POST form.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`viewId`	path	string<uuid>	yes	View identifier (UUIDv7).

Responses

Status	Description
`200`	Combined view config and execution results.
`400`	`INVALID_ID_FORMAT`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

200 response body: data fields

Field	Type	Description
`id`	string<uuid>
`name`	string
`config`	object
`view_type`	string
`columns`	array of object
`rows`	array of object
`total_count`	integer

POST /v1/views/{viewId}/execute

Execute a view query

Runs the view's saved filter/sort/group configuration and returns the matching entity rows. Requires `project.view` on the owning project. This is the canonical Wave-4 execution endpoint.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`viewId`	path	string<uuid>	yes	View identifier (UUIDv7).

Request Body

Field	Type	Required	Description
`limit`	integer	no	Page size for this execution (1–500).
`offset`	integer	no	Zero-based row offset.

Responses

Status	Description
`200`	View execution results.
`400`	`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (limit/offset out of range).
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`403`	403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.
`404`	404 Not Found — the requested resource does not exist or is not visible to the caller.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

GET /v1/views/templates

List view templates

Returns system-provided and organization view templates, optionally filtered by `view_type`. This is a static path registered before `GET /v1/views/{viewId}` in the router to ensure correct routing.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`view_type`	query	string (enum)	no	Filter templates to a specific view type.

Responses

Status	Description
`200`	List of view templates.
`400`	`INVALID_PARAMETER`.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.