Documents

Methods for creating and managing structured documents (e.g. requirements, design specs) attached to a System configuration.

A document is a versioned, ProseMirror-formatted Resource scoped to a configuration_id. Documents track a revision history identical to other Resources, but their content is rich text rather than a binary file. They support exporting to multiple formats (json, markdown, docx, pdf).

All methods are available on the Client instance. Parameters marked (required) must be provided. See Pagination for page/size defaults.

Create and update

create_document()

Create a new document on a System configuration. Pass content as a Python dict (ProseMirror JSON) or a JSON string; omit it to start with an empty document.

• Parameters:

  • create_document_request (CreateDocumentRequest) – Configuration ID, name, and optional content/description. (required)
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: Document

update_document()

Update an existing document. Provide only the fields you want to change — unspecified fields are preserved from the base revision. By default the update is based on the current revision; pass revision_id to base the update on a specific older revision (useful for explicit conflict detection).

• Parameters:

  • document_id (str) – ID of the document to update. (required)
  • update_document_request (UpdateDocumentRequest) – Fields to change. (required)
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: Document

Retrieve and list

get_document()

Retrieve a document by ID, including its current revision and ProseMirror content.

• Parameters:

  • document_id (str) – ID of the document to retrieve. (required)
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: Document

get_document_by_revision_id()

Retrieve the document state captured by a specific file revision.

• Parameters:

  • revision_id (str) – File revision ID to retrieve the document at. (required)
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: Document

list_documents()

List documents the caller has access to, optionally filtered by configuration, system, archive status, or a substring of the name.

• Parameters:

  • page (int) – Page number.
  • size (int) – Page size.
  • filter_by (FilterBy) – Filter by ownership: created_by_id (yours) or -created_by_id (shared with you).
  • archive_status (ArchiveStatus) – Filter by archive state. One of: active, archived, all.
  • configuration_id (str) – Restrict to documents on a specific configuration.
  • system_id (str) – Restrict to documents across all configurations on a System.
  • search (str) – Case-insensitive substring match on document name.
  • sort (str) – Sort expression accepted by the registry.
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: PageDocumentListItem

list_configuration_documents()

List documents attached to a single configuration.

• Parameters:

  • configuration_id (str) – ID of the configuration to list documents for. (required)
  • page (int) – Page number.
  • size (int) – Page size.
  • archive_status (ArchiveStatus) – Filter by archive state.
  • sort (str) – Sort expression accepted by the registry.
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: PageDocumentListItem

Archive

archive_document()

Archive a document. Archived documents are excluded from default list queries unless archive_status="archived" or archive_status="all" is passed.

• Parameters:

  • document_id (str) – ID of the document to archive. (required)
  • archive (Archive, optional) – Optional reason payload recorded on the archive event.
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: Document

Export

export_document()

Export the current document (or a specified revision/snapshot) to one of the supported output formats. Resource links inside the document are resolved against the snapshot or revision context, when supplied.

• Parameters:

  • document_id (str) – ID of the document to export. (required)
  • output_format (str) – Output format: json, markdown, docx, or pdf.
  • snapshot_id (str) – Optional snapshot ID for a point-in-time export. Resource links resolve against the snapshot.
  • revision_id (str) – Optional file revision ID to export a specific older version of the document. If both revision_id and snapshot_id are passed, snapshot_id wins.
  • http_request_timeout_secs (int, optional) – timeout setting for this request

• Return Type: object (export payload; format depends on output_format)

Data types

CreateDocumentRequest

Body for create_document.

Attribute	Type	Description
configuration_id	str	Configuration the document lives on
name	str	Document name (e.g. "Requirements")
content	dict | str | None	ProseMirror content as a Python dict or JSON string; omit for an empty document
description	str | None	Optional description

UpdateDocumentRequest

Body for update_document. At least one of content, name, or description is required.

Attribute	Type	Description
content	dict | str | None	New ProseMirror content; omit to leave unchanged
name	str | None	New document name; omit to leave unchanged
description	str | None	New description; omit to leave unchanged
revision_id	str | None	Base revision for the update; defaults to the current revision. Pass an older revision to detect conflicts.

Document

Returned by create_document, get_document*, update_document, and archive_document. See Files, models & artifacts data types for the shared revision/content_token shape; document-specific attributes mirror the create/update request fields plus the standard archive metadata.

PageDocumentListItem

Standard pagination wrapper around lightweight DocumentListItem rows; see Common data types for the page shape.