Skip to main content

Documents

Complete reference for document-related methods and models.

Methods​

create_document​

create_document(request: CreateDocumentRequest) -> CreateDocumentResponse

Create a new document in specified scope (Space/Member/Project).

Parameters:

  • request - CreateDocumentRequest with kind, kind_id, title, index, and optional parent_document_id

Returns: CreateDocumentResponse with created document

Example:

from vaiz.models import CreateDocumentRequest, Kind

response = client.create_document(
    CreateDocumentRequest(
        kind=Kind.Project,
        kind_id="project_id",
        title="Project Plan",
        index=0
    )
)

document = response.payload.document
print(f"Created: {document.id}")

edit_document​

edit_document(request: EditDocumentRequest) -> EditDocumentResponse

Edit document metadata such as title.

Parameters:

  • request - EditDocumentRequest with document_id and title

Returns: EditDocumentResponse with updated document

Example:

from vaiz.models import EditDocumentRequest

response = client.edit_document(
    EditDocumentRequest(
        document_id="doc_id",
        title="Updated Title"
    )
)

edited_doc = response.payload.document
print(f"Updated: {edited_doc.title}")

get_documents​

get_documents(request: GetDocumentsRequest) -> GetDocumentsResponse

Get list of documents filtered by scope (Space/Member/Project) and scope ID.

Parameters:

  • request - GetDocumentsRequest with kind and kind_id

Returns: GetDocumentsResponse with list of documents

Example:

from vaiz.models import GetDocumentsRequest, Kind

docs = client.get_documents(
    GetDocumentsRequest(
        kind=Kind.Project,
        kind_id="project_id"
    )
)

replace_markdown_document​

replace_markdown_document(document_id: str, markdown: str) -> ReplaceMarkdownDocumentResponse

Replace document content with Markdown. Markdown is converted to native rich editor blocks on the server (headings, lists, tables, code blocks, checklists, links, etc.). This is the recommended way to write document content.

Parameters:

  • document_id - Document ID to replace content for
  • markdown - New content as a Markdown string

Returns: ReplaceMarkdownDocumentResponse (empty on success)

Example:

client.replace_markdown_document(
    document_id="doc_id",
    markdown="# Title\n\nSome **bold** text\n\n- item 1\n- item 2"
)

append_markdown_document​

append_markdown_document(document_id: str, markdown: str) -> AppendMarkdownDocumentResponse

Append Markdown content to the end of a document without removing existing content.

Parameters:

  • document_id - Document ID to append content to
  • markdown - Content to append as a Markdown string

Returns: AppendMarkdownDocumentResponse (empty on success)

Example:

client.append_markdown_document(
    document_id="doc_id",
    markdown="## Update\n\nAdditional notes"
)

get_markdown_document​

get_markdown_document(document_id: str) -> str

Fetch document content rendered as Markdown. Returns an empty string for legacy documents that have no rich content yet.

Parameters:

  • document_id - Document ID to fetch

Returns: str - Document content as Markdown

Example:

markdown = client.get_markdown_document("doc_id")
print(markdown)

Models​

Document​

Main document model representing a document in the system.

class Document:
    id: str                             # Document ID
    title: str                          # Document title
    size: int                           # Document size in bytes
    contributor_ids: List[str]          # List of contributor IDs
    archiver: Optional[str]             # User who archived (if archived)
    followers: Dict[str, str]           # Document followers
    archived_at: Optional[datetime]     # Archive timestamp
    kind_id: str                        # ID of document
    kind: Kind                          # Document scope (Space/Member/Project)
    creator: str                        # Creator user ID
    map: List[Any]                      # Document structure map
    created_at: datetime                # Creation timestamp
    updated_at: datetime                # Last update timestamp
    bucket: str                         # Storage bucket ID

EditDocument​

Model representing an edited document (without internal fields like map).

class EditDocument:
    id: str                             # Document ID
    title: str                          # Document title
    space: str                          # Space ID
    size: int                           # Document size in bytes
    contributor_ids: List[str]          # List of contributor IDs
    archiver: Optional[str]             # User who archived (if archived)
    followers: Dict[str, str]           # Document followers
    archived_at: Optional[datetime]     # Archive timestamp
    kind_id: str                        # ID of document scope
    kind: Kind                          # Document scope (Space/Member/Project)
    creator: str                        # Creator user ID
    created_at: datetime                # Creation timestamp
    updated_at: datetime                # Last update timestamp
    bucket: str                         # Storage bucket ID
    content: Optional[str]              # Document content (encoded)
    content_updated_at: Optional[datetime]  # Content update timestamp

Request Models​

CreateDocumentRequest​

class CreateDocumentRequest:
    kind: Kind                          # Required - Document scope (Space/Member/Project)
    kind_id: str                        # Required - ID of space/member/project
    title: str                          # Required - Document title
    index: int                          # Required - Position in document list
    parent_document_id: Optional[str]   # Optional - Parent document ID for nesting

EditDocumentRequest​

class EditDocumentRequest:
    document_id: str                    # Required - Document ID to edit
    title: str                          # Required - New document title

Response Models​

CreateDocumentResponse​

class CreateDocumentResponse:
    payload: CreateDocumentPayload      # Response payload
    type: str                           # Response type ("CreateDocument")

CreateDocumentPayload​

class CreateDocumentPayload:
    document: Document                  # Created document

EditDocumentResponse​

class EditDocumentResponse:
    payload: EditDocumentPayload        # Response payload
    type: str                           # Response type ("EditDocument")

EditDocumentPayload​

class EditDocumentPayload:
    document: EditDocument              # Edited document

GetDocumentsRequest​

class GetDocumentsRequest:
    kind: Kind                          # Required - Document scope (Space/Member/Project)
    kind_id: str                        # Required - ID of space/member/project

GetDocumentsResponse​

class GetDocumentsResponse:
    payload: GetDocumentsPayload        # Response payload
    type: str                           # Response type ("GetDocuments")

GetDocumentsPayload​

class GetDocumentsPayload:
    documents: List[Document]           # List of documents

GetDocumentRequest​

class GetDocumentRequest:
    document_id: str                    # Required - Document ID

ReplaceDocumentRequest​

class ReplaceDocumentRequest:
    document_id: str                    # Required - Document ID
    description: str                    # Required - New document content

ReplaceDocumentResponse​

class ReplaceDocumentResponse:
    # Empty response on success
    pass

ReplaceJSONDocumentRequest​

class ReplaceJSONDocumentRequest:
    document_id: str                    # Required - Document ID
    content: List[Dict[str, Any]]       # Required - JSONContent array in document structure format

ReplaceJSONDocumentResponse​

class ReplaceJSONDocumentResponse:
    # Empty response on success
    pass

ReplaceMarkdownDocumentRequest​

class ReplaceMarkdownDocumentRequest:
    document_id: str                    # Required - Document ID
    markdown: str                       # Required - New content as Markdown

ReplaceMarkdownDocumentResponse​

class ReplaceMarkdownDocumentResponse:
    # Empty response on success
    pass

AppendMarkdownDocumentRequest​

class AppendMarkdownDocumentRequest:
    document_id: str                    # Required - Document ID
    markdown: str                       # Required - Content to append as Markdown

AppendMarkdownDocumentResponse​

class AppendMarkdownDocumentResponse:
    # Empty response on success
    pass

GetMarkdownDocumentRequest​

class GetMarkdownDocumentRequest:
    document_id: str                    # Required - Document ID

GetMarkdownDocumentResponse​

class GetMarkdownDocumentResponse:
    payload: GetMarkdownDocumentPayload # Response payload
    type: str                           # Response type

    @property
    def markdown(self) -> str: ...      # Shortcut for payload.markdown

GetMarkdownDocumentPayload​

class GetMarkdownDocumentPayload:
    markdown: str                       # Document content as Markdown ("" if empty)

See Also​