Create and edit documents

Use the createDocument, updateDocument, and deleteDocument mutations to manage the lifecycle of a rich-text document — a collaboratively-edited page that lives inside a workspace. Workspaces are Project objects in the API, and each document is a Document. The same Document row powers both regular documents and Wiki pages: set wiki: true on create to make it a Wiki page.

A document carries two content representations. content is the rendered HTML. contentBase64 is the base64-encoded collaborative-editing snapshot (the Yjs binary state the editor syncs over WebSocket). When you create a document from the API, sending content is usually enough; contentBase64 is for clients that maintain their own collab state.

This page covers rich-text documents only. The separate Portable Document subsystem (PDF templates for printing record data) is documented under Build Portable Document templates.

Request

Create a document in a workspace. projectId is the only required field; everything else is optional.

mutation CreateDocument {
  createDocument(
    input: {
      projectId: "project_123"
      title: "Onboarding runbook"
      content: "<h1>Onboarding runbook</h1><p>Step 1…</p>"
    }
  ) {
    id
    title
    wiki
    createdAt
  }
}

To create a Wiki page instead, set wiki: true:

mutation CreateWikiPage {
  createDocument(input: { projectId: "project_123", title: "Team handbook", wiki: true }) {
    id
    title
    wiki
  }
}

Parameters

CreateDocumentInput

Response

{
  "data": {
    "createDocument": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Onboarding runbook",
      "wiki": null,
      "createdAt": "2026-05-29T10:12:04.000Z"
    }
  }
}

Document

The fields available on the returned Document type.

Update a document

Use updateDocument to change a document’s fields. Only id is required — include just the fields you want to change. A title-only edit passes through without touching content.

mutation UpdateDocument {
  updateDocument(
    input: {
      id: "document_123"
      title: "Onboarding runbook (v2)"
      content: "<h1>Onboarding runbook</h1><p>Updated.</p>"
    }
  ) {
    id
    title
    updatedAt
  }
}

UpdateDocumentInput

Delete a document

Use deleteDocument to delete a document by ID. It returns Boolean — true on success — so it takes no sub-selection. The deleted document is moved to trash, not hard-deleted.

mutation DeleteDocument {
  deleteDocument(id: "document_123")
}

{ "data": { "deleteDocument": true } }

Errors

Permissions

• createDocument requires the caller to be an ADMIN, OWNER, or MEMBER on the workspace, and the workspace must have the relevant feature enabled for that role: the docs feature for a regular document, or the wiki feature when wiki: true. It is rate-limited to a default of 5 requests per 60 seconds per user.
• updateDocument and deleteDocument require the caller to have permission for the document’s type (docs for documents, wiki for Wiki pages). For an update that flips wiki, the caller needs permission for both the current and the resulting type. deleteDocument also succeeds for the document’s original creator.
• updateDocument additionally accepts internal Blue service callers. The userId field exists only for that path — Blue’s collaboration server passes it to attribute an edit to the right user. The server validates it against a real User and rejects it otherwise, so regular API clients should never set it; the editing user is taken from your credentials.

Related

• Query and subscribe to documents — fetch a document, list a workspace’s documents, and stream real-time changes.
• Build Portable Document templates — the separate PDF-template subsystem.
• Documents overview — how rich-text Documents and Portable Documents differ.