Files & Documents

File-bridge relay (WebSocket), BBProve confined source read/write, document library management, Backbuild Docs collaborative editor, document comments and shares, resource versioning, and Science artifact promotion.

41 endpoints. Generated from the OpenAPI 3.1 specification.

GET /v1/bbprove/projects/{projectId}/files/{path}

Read a confined project file (BBProve)

Returns a chunk of a file from the project's confined source repository managed by BBProve. Authentication is via the one-time ticket query parameter — the caller must have been granted `producer` or `consumer` role for this project. Responses are chunked; `eof=true` signals the final chunk.

Auth One-time ?token= ticket

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`path`	path	string	yes	Project-relative file path (wildcard segment, may contain `/`).
`token`	query	string	yes	One-time ticket granting read access to this project's confined repository.

Responses

Status	Description
`200`	File chunk returned successfully.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`503`	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
`sha256`	string	SHA-256 hex digest of the complete file.
`totalSize`	integer	Total file size in bytes.
`bytesBase64`	string	Base64-encoded bytes of this chunk.
`eof`	boolean	`true` if this is the final chunk.

PUT /v1/bbprove/projects/{projectId}/files/{path}

CAS-write a confined project file (BBProve)

Writes a file into the project's confined source repository using content-addressable storage (CAS). The `ifMatchSha256` field acts as an optimistic-concurrency guard — the write is rejected with `CONFLICT` if the current head hash differs. Authentication is via the one-time ticket query parameter.

Auth One-time ?token= ticket

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`path`	path	string	yes	Project-relative file path (wildcard segment, may contain `/`).
`token`	query	string	yes	One-time ticket granting write access to this project's confined repository.

Request Body

Field	Type	Required	Description
`contentBase64`	string	yes	Base64-encoded file content. Maximum 16 MB (encoded).
`ifMatchSha256`	string	yes	SHA-256 hex digest of the current HEAD. The write is rejected with `CONFLICT` if it doesn't match.

Responses

Status	Description
`200`	File written successfully.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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`	409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).
`413`	Payload exceeds the 16 MB file size limit (`FILE_SIZE_LIMIT_EXCEEDED`).
`503`	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
`newSha256`	string	SHA-256 hex digest of the newly written content.
`newSize`	integer	Size in bytes of the newly written file.

GET /v1/documents

List documents

Returns a paginated list of documents visible to the authenticated user. Results can be filtered by project, parent folder, and free-text search, and sorted by various fields.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`project_id`	query	string<uuid>	no	Filter documents belonging to this project.
`parent_id`	query	string<uuid>	no	Filter documents whose immediate parent folder has this ID.
`search`	query	string	no	Full-text search query. Maximum 200 characters.
`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.
`sort_by`	query	string (enum)	no	Field to sort results by.
`sort_order`	query	string (enum)	no	Sort direction.

Responses

Status	Description
`200`	Paginated list of documents.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed validation.
`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.

200 response body: data fields

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

POST /v1/documents

Create a document

Creates a new document in the library. The content is passed through the content-safety gate before storage; documents that violate the content policy are rejected with `CONTENT_POLICY_VIOLATION`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`title`	string	yes	Document title.
`content`	string	no	Initial document content.
`content_type`	string	no	MIME type or editor-specific content type identifier.
`project_id`	string<uuid>	no	Project to associate the document with.
`parent_id`	string<uuid>	no	Parent folder ID.
`tags`	array of string	no	Searchable tags.
`metadata`	object	no	Arbitrary JSON metadata. Subject to size bounds.

Responses

Status	Description
`201`	Document created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`document`	object	A document record in the document library.

GET /v1/documents/{id}

Get a document

Returns a single document by ID. Row Level Security ensures users can only retrieve documents they have access to.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the document.

Responses

Status	Description
`200`	Document returned.
`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
`document`	object	A document record in the document library.

PUT /v1/documents/{id}

Update a document

Updates one or more fields of an existing document. All fields are optional; only supplied fields are changed. Content updates pass through the content-safety gate.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the document to update.

Request Body

Field	Type	Required	Description
`title`	string	no	New document title.
`content`	string	no	New document content.
`content_type`	string	no	New content type.
`project_id`	string<uuid>	no	Reassign to a different project.
`parent_id`	string<uuid>	no	Reassign to a different parent folder.
`tags`	array of string	no	Replace the tag list.
`metadata`	object	no	Replace the metadata object.

Responses

Status	Description
`200`	Document updated.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`document`	object	A document record in the document library.

DELETE /v1/documents/{id}

Delete a document

Permanently deletes a document and its associated storage objects. This operation cannot be undone.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the document to delete.

Responses

Status	Description
`200`	Document deleted.
`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/documents/{id}/file

Download a document file (PDF)

Streams the raw document file (typically a PDF). Accepts either an `Authorization: Bearer` header for JWT/session authentication **or** the HMAC-signed query parameters `org`, `exp`, and `sig` minted by `/v1/documents/{id}/file-link`. When signed URL parameters are present, the Bearer header is ignored. Expired or tampered signatures return `UNAUTHORIZED`.

Auth or Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the document.
`org`	query	string<uuid>	no	Organisation UUID embedded in the signed URL (required when using signed-URL auth).
`exp`	query	integer	no	Unix timestamp at which the signed URL expires (required when using signed-URL auth).
`sig`	query	string	no	HMAC-SHA256 signature over `{org}:{id}:{exp}` (required when using signed-URL auth).

Responses

Status	Description
`200`	PDF binary stream.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.
`503`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.

POST /v1/documents/{id}/file-link

Mint a short-lived signed URL for a document file

Issues a 300-second HMAC-signed URL that can be used to retrieve the raw document file (typically a PDF) without an `Authorization` header. Requires the `documents.read` API key scope when authenticating with an API key.

Auth Session JWT (Bearer) or API key (Bearer bb_live_…)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the document whose file URL is being minted.

Responses

Status	Description
`200`	Signed URL minted.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`url`	string<uri>	Signed download URL valid for `ttl_seconds`.
`expires_at`	string<date-time>	ISO 8601 timestamp when the URL expires.
`ttl_seconds`	integer	Validity window in seconds (300).

GET /v1/documents/explorer

Get unified document explorer

Returns the full explorer tree for the authenticated user, organised into roots (`artifacts`, `personal`, `department`, `organization`, `projects`, `shared`, `sharing`), with nested folders and document items under each root.

Auth Session JWT (Bearer)

Responses

Status	Description
`200`	Explorer tree returned.
`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.

200 response body: data fields

Field	Type	Description
`roots`	array of object
`folders`	array of object
`items`	array of object

POST /v1/documents/folders

Create a document folder

Creates a virtual folder marker in the document library. Folders are identified by their root and path segments rather than a flat name hierarchy.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`root_id`	string (enum) `artifactspersonaldepartmentorganizationprojectssharedsharing`	yes	Explorer root the folder belongs to.
`path`	array of string	yes	Ordered list of path segments (at least one, at most 24).
`project_id`	string<uuid>	no	Project to associate the folder with.

Responses

Status	Description
`201`	Folder created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed validation.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`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
`folder`	object	A virtual folder in the document explorer.

PUT /v1/documents/folders/{id}

Rename a document folder

Renames the last segment of an existing document folder.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the folder to rename.

Request Body

Field	Type	Required	Description
`name`	string	yes	New folder name (the final path segment).

Responses

Status	Description
`200`	Folder renamed.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`folder`	object	A virtual folder in the document explorer.

DELETE /v1/documents/folders/{id}

Delete a document folder

Deletes a document folder and all its contents. This operation is permanent.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`id`	path	string<uuid>	yes	UUID of the folder to delete.

Responses

Status	Description
`200`	Folder deleted.
`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

POST /v1/documents/publish

Publish a document to the library

Upserts a document into a named library bucket with a category and folder path. Accepts either Markdown or a Base64-encoded PDF. PDFs are validated for JavaScript actions (`PDF_CONTAINS_JS_ACTION`) and checked against upload suppression lists (`UPLOAD_SUPPRESSED`). Requires the `documents.publish` API key scope when authenticating with an API key. Returns `operation: 'created'` (HTTP 201) or `operation: 'updated'` (HTTP 200).

Auth Session JWT (Bearer) or API key (Bearer bb_live_…)

Request Body

Field	Type	Required	Description
`library`	string	yes	Target library bucket name.
`category`	string	yes	Category within the library.
`folder_path`	array of string	yes	Ordered path segments for the document's folder location.
`title`	string	yes	Document title.
`source_path`	string	yes	Canonical source path used for upsert resolution.
`markdown`	string	no	Markdown content for the document (up to 2 MB). Mutually exclusive with `pdf_base64`.
`pdf_base64`	string	no	Base64-encoded PDF content. Mutually exclusive with `markdown`. Validated for JavaScript actions.
`metadata`	object	no	Optional arbitrary metadata to attach to the document.

Responses

Status	Description
`200`	Document updated (already existed at the resolved path).
`201`	Document created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`413`	Payload exceeds the size limit (`PAYLOAD_TOO_LARGE`).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.
`503`	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>	Document ID.
`operation`	string (enum) `createdupdated`	Whether the document was newly created or an existing document was updated.
`r2_key`	string	R2 object key where the file is stored.
`file_url`	string<uri>	Accessible URL of the stored file.
`file_size`	integer	File size in bytes.
`folder_path`	array of string	Resolved folder path segments.

201 response body: data fields

Field	Type	Description
`id`	string<uuid>	Document ID.
`operation`	string (enum) `createdupdated`	Whether the document was newly created or an existing document was updated.
`r2_key`	string	R2 object key where the file is stored.
`file_url`	string<uri>	Accessible URL of the stored file.
`file_size`	integer	File size in bytes.
`folder_path`	array of string	Resolved folder path segments.

GET /v1/files/ws

Open FileBridge WebSocket relay

Upgrades to a WebSocket connection routed through the FileBridge Durable Object. Used by the Backbuild IDE to synchronise file trees between a local producer and a remote consumer. Authentication is via a short-lived one-time ticket passed in the `token` query parameter — **no `Authorization` header is accepted on this endpoint**. The ticket encodes the allowed role and pairing identity.

Auth One-time ?token= ticket

Parameters

Name	In	Type	Required	Description
`token`	query	string	yes	Short-lived one-time ticket issued by the control plane. Must be supplied instead of an `Authorization` header.
`role`	query	string (enum)	yes	The role this connection plays in the pairing.
`pairingId`	query	string<uuid>	yes	UUID that identifies the pairing session shared by producer and consumer.
`projectId`	query	string<uuid>	yes	UUID of the project whose files are being shared.
`documentId`	query	string<uuid>	no	UUID of the document being opened. Required when `role=consumer`.
`deviceId`	query	string	no	Opaque client device identifier. Maximum 256 characters.
`rootFingerprint`	query	string	no	Hash of the workspace root used by the producer for integrity checks. Maximum 256 characters.

Responses

Status	Description
`101`	Switching Protocols — WebSocket connection established.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed validation.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.

GET /v1/projects/{projectId}/bbdocs

List BB Docs in a project

Returns a paginated list of BB Docs belonging to the project. Supports pagination, full-text search, and filtering by content type.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`page`	query	integer	no	1-based page number.
`page_size`	query	integer	no	Items per page.
`search`	query	string	no	Full-text search query. Maximum 500 characters.
`content_type`	query	string (enum)	no	Filter by BB Doc content type.

Responses

Status	Description
`200`	Paginated list of BB Docs.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`items`	array of object
`meta`	object	Pagination metadata. Endpoints use either page/pageSize or limit/offset style; fields present depend on the endpoint.

POST /v1/projects/{projectId}/bbdocs

Create a BB Doc

Creates a new BB Doc in the specified project. Optionally initialises the document from a template, with pre-populated content in a supported format, or copies the content from an existing source document.

Auth Session JWT (Bearer)

Parameters

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

Request Body

Field	Type	Required	Description
`name`	string	yes	Title of the new BB Doc.
`fromTemplateId`	string<uuid>	no	Optional template to initialise the document from.
`initialContent`	string	no	Optional initial content (up to 10 MB).
`initialFormat`	string (enum) `pf2amsthmlatex`	no	Format of `initialContent`, if provided.
`sourceDocumentId`	string<uuid>	no	Optional existing BB Doc to copy content from.

Responses

Status	Description
`201`	BB Doc created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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`	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
`document`	object	A BB Doc — a collaborative document with Yjs CRDT backing.

GET /v1/projects/{projectId}/bbdocs/{documentId}

Get a BB Doc

Returns the metadata and current state of a single BB Doc.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.

Responses

Status	Description
`200`	BB Doc returned.
`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
`document`	object	A BB Doc — a collaborative document with Yjs CRDT backing.

PATCH /v1/projects/{projectId}/bbdocs/{documentId}

Rename a BB Doc

Updates the title of a BB Doc. The title is trimmed and must be between 1 and 255 characters after trimming.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc to rename.

Request Body

Field	Type	Required	Description
`title`	string	yes	New title for the BB Doc (whitespace-trimmed before storage).

Responses

Status	Description
`200`	BB Doc renamed.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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`	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
`document`	object	A BB Doc — a collaborative document with Yjs CRDT backing.

GET /v1/projects/{projectId}/bbdocs/{documentId}/comments

List comments on a BB Doc

Returns all comments (and their replies) on the specified BB Doc.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.

Responses

Status	Description
`200`	Comment list returned.
`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
`comments`	array of object

POST /v1/projects/{projectId}/bbdocs/{documentId}/comments

Create a comment on a BB Doc

Adds a new comment anchored to a character range in the BB Doc. The anchor positions refer to Yjs document offsets. An optional `commentId` can be supplied by the client for idempotency.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc to comment on.

Request Body

Field	Type	Required	Description
`commentId`	string<uuid>	no	Optional client-supplied ID for idempotency.
`anchorFrom`	integer	yes	Start offset of the comment anchor in the Yjs document.
`anchorTo`	integer	yes	End offset of the comment anchor in the Yjs document.
`body`	string	yes	Comment body text.
`authorName`	string	no	Display name of the comment author.

Responses

Status	Description
`201`	Comment created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`comment`	object	A comment thread on a BB Doc.

PATCH /v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}

Update a BB Doc comment

Toggles the resolved state of a comment. Currently the only mutable field.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`commentId`	path	string<uuid>	yes	UUID of the comment to update.

Request Body

Field	Type	Required	Description
`resolved`	boolean	yes	Whether the comment thread is resolved.

Responses

Status	Description
`200`	Comment updated.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`comment`	object	A comment thread on a BB Doc.

DELETE /v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}

Delete a BB Doc comment

Permanently deletes a comment thread and all its replies.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`commentId`	path	string<uuid>	yes	UUID of the comment to delete.

Responses

Status	Description
`200`	Comment deleted.
`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

POST /v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/assign

Assign a BB Doc comment to a user

Assigns responsibility for resolving a comment to a specific user. Triggers an in-app notification to the assignee.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`commentId`	path	string<uuid>	yes	UUID of the comment to assign.

Request Body

Field	Type	Required	Description
`assigneeUserId`	string<uuid>	yes	UUID of the user to assign the comment to.
`assigneeName`	string	no	Display name of the assignee (used in notifications).

Responses

Status	Description
`200`	Comment assigned.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`comment`	object	A comment thread on a BB Doc.
`notified`	boolean	Whether the assignee was successfully notified.

POST /v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/assignment-done

Mark a BB Doc comment assignment as done

Marks the comment assignment as completed. Typically called by the assignee when the requested change has been made.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`commentId`	path	string<uuid>	yes	UUID of the comment whose assignment is being completed.

Responses

Status	Description
`200`	Assignment marked as done.
`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
`comment`	object	A comment thread on a BB Doc.

POST /v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/replies

Add a reply to a BB Doc comment

Appends a reply to an existing comment thread. An optional `replyId` can be supplied by the client for idempotency.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`commentId`	path	string<uuid>	yes	UUID of the parent comment thread.

Request Body

Field	Type	Required	Description
`replyId`	string<uuid>	no	Optional client-supplied ID for idempotency.
`body`	string	yes	Reply body text.
`authorName`	string	no	Display name of the reply author.

Responses

Status	Description
`201`	Reply created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`reply`	object	A reply within a BB Doc comment thread.

DELETE /v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/replies/{replyId}

Delete a reply from a BB Doc comment

Permanently deletes a single reply from a comment thread.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`commentId`	path	string<uuid>	yes	UUID of the parent comment thread.
`replyId`	path	string<uuid>	yes	UUID of the reply to delete.

Responses

Status	Description
`200`	Reply deleted.
`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/projects/{projectId}/bbdocs/{documentId}/shares

List shares on a BB Doc

Returns the active share grants on a BB Doc. Revoked shares are excluded by default.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`include_revoked`	query	string (enum)	no	Pass `true` to include revoked share grants in the response.

Responses

Status	Description
`200`	Share list returned.
`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
`shares`	array of object

POST /v1/projects/{projectId}/bbdocs/{documentId}/shares

Create a share grant on a BB Doc

Grants access to a BB Doc for an org, user, or named scope. The caller's existing sharing level acts as a ceiling — attempting to grant a level that exceeds the caller's own access returns `403 Forbidden`.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc to share.

Request Body

Field	Type	Required	Description
`level`	string (enum) `viewcommentsuggestedit`	no	Access level to grant. Defaults to `view`.
`scope`	string	no	Sharing scope identifier.
`target_id`	string	no	Scoped target identifier.
`recipient_org_id`	string<uuid>	no	Organisation to share with.
`recipient_user_id`	string<uuid>	no	User to share with.
`scope_kind`	string (enum) `resourcefilefolder`	no	The kind of scope this grant applies to.
`path`	string	no	Path scoping this grant (when `scope_kind` is `file` or `folder`).

Responses

Status	Description
`201`	Share grant created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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`	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
`share`	object	A share grant on a BB Doc.

DELETE /v1/projects/{projectId}/bbdocs/{documentId}/shares/{shareId}

Revoke a BB Doc share grant

Revokes a share grant. If the grant was already revoked, returns the existing record with `already_revoked: true` rather than an error.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`shareId`	path	string<uuid>	yes	UUID of the share grant to revoke.

Responses

Status	Description
`200`	Share grant revoked (or was already revoked).
`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>
`revoked_at`	string<date-time>
`already_revoked`	boolean

GET /v1/projects/{projectId}/bbdocs/{documentId}/thumbnail

Get BB Doc thumbnail metadata

Returns the thumbnail for a BB Doc. If the document's first page has a page-icon, returns `{icon}` (a string icon name). If a rendered bitmap is available, returns a 302 redirect to a short-lived signed blob URL (`/v1/projects/{projectId}/bbdocs/{documentId}/thumbnail/blob?...`).

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.

Responses

Status	Description
`200`	Page-icon thumbnail returned.
`302`	Redirect to signed blob URL for bitmap thumbnail.
`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
`icon`	string	Icon name representing the document thumbnail.

GET /v1/projects/{projectId}/bbdocs/{documentId}/thumbnail/blob

Download BB Doc thumbnail bitmap

Streams the WebP thumbnail bitmap for a BB Doc. Authentication is via HMAC-signed query parameters (`org`, `sha`, `exp`, `sig`) minted by the control plane — **no `Authorization` header is accepted**. The signed URL is obtained from the `Location` header of a `302` response on `GET /v1/projects/{projectId}/bbdocs/{documentId}/thumbnail`.

Auth

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`org`	query	string<uuid>	yes	Organisation UUID embedded in the signed URL.
`sha`	query	string	yes	Content hash of the blob, embedded in the signed URL.
`exp`	query	integer	yes	Unix timestamp at which the signed URL expires.
`sig`	query	string	yes	HMAC-SHA256 signature.

Responses

Status	Description
`200`	WebP thumbnail bitmap.
`401`	401 Unauthorized — missing, expired, malformed, or revoked credentials.
`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/projects/{projectId}/bbdocs/{documentId}/versions

List versions of a BB Doc

Returns the append-only version chain for a BB Doc, newest first. Each version represents a snapshot checkpoint.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.

Responses

Status	Description
`200`	Version list returned.
`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

GET /v1/projects/{projectId}/bbdocs/{documentId}/versions/{versionId}

Get a specific BB Doc version

Returns a single version snapshot for a BB Doc by version ID.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`versionId`	path	string<uuid>	yes	UUID of the version snapshot.

Responses

Status	Description
`200`	Version snapshot returned.
`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
`version`	object	A snapshot version of a BB Doc.

POST /v1/projects/{projectId}/bbdocs/{documentId}/versions/{versionId}/restore

Restore a BB Doc to a previous version

Creates a new HEAD version that copies the content of the specified version snapshot. The restore operation is non-destructive — the existing version chain is preserved.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`documentId`	path	string<uuid>	yes	UUID of the BB Doc.
`versionId`	path	string<uuid>	yes	UUID of the version to restore from.

Responses

Status	Description
`200`	New HEAD version created from the specified snapshot.
`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
`version`	object	A snapshot version of a BB Doc.

GET /v1/projects/{projectId}/bbdocs/recents

Get recently accessed BB Docs in a project

Returns the most recently accessed BB Docs for the authenticated user in the specified project.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string<uuid>	yes	Project identifier (UUIDv7).
`limit`	query	integer	no	Maximum number of recents to return. Between 1 and 50.

Responses

Status	Description
`200`	Recent BB Docs returned.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`items`	array of object

POST /v1/projects/{projectId}/documents:resolve

Resolve a document by project-relative path

Resolves a project-relative path to a document record. Returns a uniform `403 Forbidden` for both unauthorised access and non-existent paths to prevent existence oracle attacks.

Auth Session JWT (Bearer)

Parameters

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

Request Body

Field	Type	Required	Description
`rel_path`	string	yes	Project-relative path of the document to resolve.

Responses

Status	Description
`200`	Document resolved.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`document_id`	string<uuid>
`doc_type`	string
`capability`	string
`classification`	string

POST /v1/science/documents/promote-artifact

Promote a Science artifact to the document library

Copies a Science artifact from the RAG source bucket into the user's document library as a new document record (copy-on-write). The artifact must belong to an accessible catalog and be confined to the caller's organisation. If the artifact file exceeds 16 MB the promotion is rejected with `PAYLOAD_TOO_LARGE`.

Auth Session JWT (Bearer)

Request Body

Field	Type	Required	Description
`artifact_id`	string<uuid>	yes	ID of the Science artifact to promote.
`project_id`	string<uuid>	yes	Target project that will own the new document.
`title`	string	no	Title for the new document (whitespace-trimmed). Defaults to the artifact name.
`folder_id`	string<uuid>	no	Target folder in the document library.
`content_type`	string	no	MIME type override (whitespace-trimmed). Defaults to the artifact's detected content type.
`dest_path`	string	no	Override the destination R2 object path (whitespace-trimmed).

Responses

Status	Description
`201`	Artifact promoted and document created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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`	409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).
`413`	Artifact file exceeds the 16 MB promotion limit (`PAYLOAD_TOO_LARGE`).
`500`	500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.
`503`	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
`document`	object	A document record in the document library.
`copy`	object	Details of the R2 copy operation.

GET /v1/versioning/{resourceType}/{resourceId}

List versions of a versioned resource

Returns the version history of a supported resource type. Supported types are `skill`, `entity_type`, `screen_definition`, `workflow`, `pricing_plan`, and `tool`. Returns `INVALID_PARAMETER` for unsupported types.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`resourceType`	path	string (enum)	yes	The type of the versioned resource.
`resourceId`	path	string<uuid>	yes	UUID of the resource.
`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`	Version list returned.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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.
`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
`pagination`	object	Pagination metadata. Endpoints use either page/pageSize or limit/offset style; fields present depend on the endpoint.

GET /v1/versioning/{resourceType}/{resourceId}/{version}

Get a specific version of a resource

Returns a single version snapshot of a resource by its sequential version number.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`resourceType`	path	string (enum)	yes	The type of the versioned resource.
`resourceId`	path	string<uuid>	yes	UUID of the resource.
`version`	path	integer	yes	Sequential positive-integer version number.

Responses

Status	Description
`200`	Version snapshot returned.
`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
`version`	object	A version snapshot of a versioned API resource.

POST /v1/versioning/{resourceType}/{resourceId}/revert

Revert a resource to a previous version

Creates a new HEAD version of the resource that copies the content of the specified version. Returns `CONFLICT` if the requested version is already the current HEAD.

Auth Session JWT (Bearer)

Parameters

Name	In	Type	Required	Description
`resourceType`	path	string (enum)	yes	The type of the versioned resource.
`resourceId`	path	string<uuid>	yes	UUID of the resource to revert.

Request Body

Field	Type	Required	Description
`version`	integer	yes	Sequential version number to revert to.
`changelog`	string	no	Optional human-readable note explaining why this revert was made.

Responses

Status	Description
`200`	Resource reverted — new HEAD version created.
`400`	400 Bad Request — a request parameter, body field, or the JSON body itself failed 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`	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
`version`	object	A version snapshot of a versioned API resource.