Documents

Manage documents within workspaces. Documents support hierarchical tree structures, full-text search, export, and public publishing.

Base Path: /api/v1/documents Authentication: Required (Bearer Token) Tag: Documents

---

List Documents

Retrieve documents in a workspace, optionally filtered by parent.

GET /documents?workspaceId={workspaceId}&parentId={parentId}

Query Parameters

Parameter	Type	Required	Description
workspaceId	UUID	Yes	Workspace to list documents from
parentId	UUID	No	Filter by parent document (root documents if omitted)

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Getting Started",
      "parentId": null,
      "workspaceId": "660e8400-e29b-41d4-a716-446655440000",
      "icon": "📚",
      "hasChildren": true,
      "childCount": 3,
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Response Type: ApiResponse<List<DocumentListResponse>>

---

Get Document Tree

Retrieve the full document tree structure for a workspace.

GET /documents/tree?workspaceId={workspaceId}

Query Parameters

Parameter	Type	Required	Description
workspaceId	UUID	Yes	Workspace ID

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Getting Started",
      "parentId": null,
      "workspaceId": "660e8400-e29b-41d4-a716-446655440000",
      "icon": "📚",
      "updatedAt": "2025-01-15T10:30:00Z",
      "children": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440000",
          "title": "Installation",
          "parentId": "550e8400-e29b-41d4-a716-446655440000",
          "children": []
        }
      ]
    }
  ]
}

Response Type: ApiResponse<List<DocumentTreeResponse>>

---

Search Documents

Full-text search across documents in a workspace.

GET /documents/search?workspaceId={workspaceId}&query={query}

Query Parameters

Parameter	Type	Required	Description
workspaceId	UUID	Yes	Workspace to search in
query	String	Yes	Search query string

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Getting Started",
      "icon": "📚",
      "parentId": null,
      "snippet": "...matching text with <mark>highlighted</mark> terms...",
      "matchField": "content"
    }
  ]
}

Response Type: ApiResponse<List<SearchResultResponse>>

---

Get Document

Retrieve a single document by ID with full content.

GET /documents/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Document ID

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Getting Started",
    "content": "[{\"type\":\"paragraph\",\"content\":[...]}]",
    "excerpt": "This guide helps you...",
    "parentId": null,
    "workspaceId": "660e8400-e29b-41d4-a716-446655440000",
    "ownerId": "880e8400-e29b-41d4-a716-446655440000",
    "icon": "📚",
    "coverImageUrl": null,
    "isTemplate": false,
    "isArchived": false,
    "wordCount": 150,
    "hasChildren": true,
    "childCount": 3,
    "openCommentCount": 2,
    "createdBy": "880e8400-e29b-41d4-a716-446655440000",
    "lastEditedBy": "990e8400-e29b-41d4-a716-446655440000",
    "createdByUser": {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "name": "John Doe",
      "avatarUrl": "https://..."
    },
    "lastEditedByUser": {
      "id": "990e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith",
      "avatarUrl": "https://..."
    },
    "isPublished": false,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
}

Response Type: ApiResponse<DocumentResponse>

---

Get Children

Retrieve direct child documents of a document.

GET /documents/{id}/children

Path Parameters

Parameter	Type	Description
id	UUID	Parent document ID

Response Type: ApiResponse<List<DocumentListResponse>>

---

Get Ancestors (Breadcrumb)

Retrieve the ancestor chain from root to the specified document (for breadcrumb navigation).

GET /documents/{id}/ancestors

Path Parameters

Parameter	Type	Description
id	UUID	Document ID

Response

{
  "success": true,
  "data": [
    { "id": "...", "title": "Root Doc" },
    { "id": "...", "title": "Parent Doc" },
    { "id": "...", "title": "Current Doc" }
  ]
}

Response Type: ApiResponse<List<DocumentBreadcrumb>>

---

Create Document

Create a new document in a workspace.

POST /documents

Request Body

{
  "title": "New Document",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440000",
  "parentId": null,
  "content": [{"type": "paragraph", "content": []}],
  "icon": "📄",
  "coverImageUrl": null
}

Field	Type	Required	Validation	Description
title	String	No	Max 500 chars	Document title
workspaceId	UUID	Yes	Not null	Target workspace
parentId	UUID	No	-	Parent document (null = root)
content	Object	No	-	BlockNote JSON content
icon	String	No	Max 50 chars	Document icon/emoji
coverImageUrl	String	No	-	Cover image URL

Response

Status: 201 Created Response Type: ApiResponse<DocumentResponse>

---

Update Document

Update an existing document.

PUT /documents/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Document ID

Request Body

{
  "title": "Updated Title",
  "content": [{"type": "paragraph", "content": []}],
  "icon": "📝",
  "coverImageUrl": "https://...",
  "isArchived": false
}

Field	Type	Required	Validation	Description
title	String	No	Max 500 chars	New title
content	Object	No	-	BlockNote JSON content
icon	String	No	Max 50 chars	Document icon
coverImageUrl	String	No	-	Cover image URL
isArchived	Boolean	No	-	Archive status

Response Type: ApiResponse<DocumentResponse>

---

Move Document

Move a document to a different parent or to root level.

PUT /documents/{id}/move

Request Body

{
  "parentId": "770e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
parentId	UUID	No	New parent document ID (null = move to root)

Response Type: ApiResponse<DocumentResponse>

---

Delete Document

Delete a document. Children become root-level documents.

DELETE /documents/{id}

Response Type: ApiResponse<Void>

---

Delete Document (Cascade)

Delete a document and all its children recursively.

DELETE /documents/{id}/cascade

danger

This action is irreversible. All child documents will be permanently deleted.

Response Type: ApiResponse<Void>

---

Export Document

Export a document to PDF, DOCX, or Markdown format.

GET /documents/{id}/export?format={format}

Query Parameters

Parameter	Type	Required	Values	Description
format	String	Yes	pdf, docx, markdown	Export format

Response

Returns the file as a binary stream with appropriate Content-Type and Content-Disposition headers.

Format	Content-Type	Extension
pdf	application/pdf	.pdf
docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
markdown	text/markdown	.md

---

Publish Document

Make a document publicly accessible (no authentication required).

POST /documents/{id}/publish

Response Type: ApiResponse<Void>

---

Unpublish Document

Remove public access from a published document.

POST /documents/{id}/unpublish

Response Type: ApiResponse<Void>