Documents

GraphQL API for document operations including CRUD, publishing, permissions, and analytics

Overview

The Document API provides operations for managing documents within AFFiNE workspaces, including creating, reading, updating, publishing, and managing document-level permissions.

Queries

Get Document

Retrieve a specific document by ID within a workspace.

Query

query GetDocument($workspaceId: String!, $docId: String!) {
  workspace(id: $workspaceId) {
    doc(docId: $docId) {
      id
      workspaceId
      title
      mode
      public
      defaultRole
      createdAt
      updatedAt
      createdBy {
        id
        name
        avatarUrl
      }
      lastUpdatedBy {
        id
        name
        avatarUrl
      }
      permissions {
        Doc_Read
        Doc_Update
        Doc_Delete
        Doc_Publish
        Doc_Users_Manage
      }
    }
  }
}

workspaceId · String! · required

The workspace containing the document

docId · String! · required

The document ID to retrieve

---

Get Public Documents

Retrieve all publicly shared documents in a workspace.

Query

query GetPublicDocs($workspaceId: String!) {
  workspace(id: $workspaceId) {
    publicDocs {
      id
      title
      mode
      public
      createdAt
      updatedAt
    }
  }
}

---

Get Recently Updated Documents

Retrieve recently updated documents with pagination.

Query

query GetRecentDocs($workspaceId: String!, $pagination: PaginationInput!) {
  workspace(id: $workspaceId) {
    recentlyUpdatedDocs(pagination: $pagination) {
      edges {
        cursor
        node {
          id
          title
          updatedAt
          lastUpdatedBy {
            id
            name
          }
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
    }
  }
}

pagination · PaginationInput! · required

Show PaginationInput fields

first · Int · default: "10"

Number of items to return

after · String

Cursor for pagination

offset · Int · default: "0"

Offset for pagination

---

Get Document Metadata

Retrieve document metadata including editor information.

Query

query GetDocMeta($workspaceId: String!, $docId: String!) {
  workspace(id: $workspaceId) {
    doc(docId: $docId) {
      meta {
        createdAt
        updatedAt
        createdBy {
          name
          avatarUrl
        }
        updatedBy {
          name
          avatarUrl
        }
      }
    }
  }
}

---

Get Document Analytics

Retrieve page view analytics for a document.

Query

query GetDocAnalytics($workspaceId: String!, $docId: String!, $input: DocPageAnalyticsInput) {
  workspace(id: $workspaceId) {
    doc(docId: $docId) {
      analytics(input: $input) {
        window {
          from
          to
          timezone
          bucket
        }
        summary {
          totalViews
          uniqueViews
          guestViews
          lastAccessedAt
        }
        series {
          date
          totalViews
          uniqueViews
          guestViews
        }
        generatedAt
      }
    }
  }
}

---

Mutations

Publish Document

Make a document publicly accessible.

Mutation

mutation PublishDoc($workspaceId: String!, $docId: String!, $mode: PublicDocMode) {
  publishDoc(workspaceId: $workspaceId, docId: $docId, mode: $mode) {
    id
    public
    mode
    defaultRole
  }
}

mode · PublicDocMode · default: "Page"

The display mode for the public document. Values: Page, Edgeless

---

Revoke Public Document

Remove public access from a document.

Mutation

mutation RevokePublicDoc($workspaceId: String!, $docId: String!) {
  revokePublicDoc(workspaceId: $workspaceId, docId: $docId) {
    id
    public
  }
}

---

Grant Document User Roles

Grant specific users access to a document with a defined role.

Mutation

mutation GrantDocUserRoles($input: GrantDocUserRolesInput!) {
  grantDocUserRoles(input: $input)
}

input · GrantDocUserRolesInput! · required

Show GrantDocUserRolesInput fields

workspaceId · String! · required

The workspace ID

docId · String! · required

The document ID

userIds · [String!]! · required

Array of user IDs to grant access

role · DocRole! · required

The role to grant: Owner, Manager, Editor, Commenter, Reader

---

Update Document User Role

Change a user’s role on a specific document.

Mutation

mutation UpdateDocUserRole($input: UpdateDocUserRoleInput!) {
  updateDocUserRole(input: $input)
}

---

Revoke Document User Roles

Remove a user’s access to a document.

Mutation

mutation RevokeDocUserRoles($input: RevokeDocUserRoleInput!) {
  revokeDocUserRoles(input: $input)
}

---

Update Document Default Role

Set the default permission level for users accessing the document.

Mutation

mutation UpdateDocDefaultRole($input: UpdateDocDefaultRoleInput!) {
  updateDocDefaultRole(input: $input)
}

The default role cannot be set to Owner. Valid values are Manager, Editor, Commenter, Reader, None.

---

Type Definitions

DocType

id · String!

Unique document identifier

workspaceId · String!

ID of the workspace containing the document

title · String

Document title

mode · PublicDocMode!

Display mode: Page or Edgeless

public · Boolean!

Whether the document is publicly accessible

defaultRole · DocRole!

Default permission level for workspace members

createdAt · DateTime

Document creation timestamp

updatedAt · DateTime

Last update timestamp

creatorId · String

ID of the user who created the document

lastUpdaterId · String

ID of the user who last updated the document

summary · String

AI-generated document summary

DocRole Enum

• Owner - Full control, can transfer ownership
• Manager - Can manage users and settings
• Editor - Can edit document content
• Commenter - Can add comments only
• Reader - Read-only access
• None - No access
• External - Limited external access

DocPermissions

Boolean flags indicating available actions:

• Doc_Read - Can read the document
• Doc_Update - Can edit the document
• Doc_Delete - Can delete the document
• Doc_Trash - Can move to trash
• Doc_Restore - Can restore from trash
• Doc_Copy - Can copy the document
• Doc_Duplicate - Can duplicate the document
• Doc_Publish - Can publish/unpublish
• Doc_Users_Read - Can view shared users
• Doc_Users_Manage - Can manage user permissions
• Doc_TransferOwner - Can transfer ownership
• Doc_Comments_Read - Can read comments
• Doc_Comments_Create - Can create comments
• Doc_Comments_Delete - Can delete comments
• Doc_Comments_Resolve - Can resolve comments

---

Error Handling

DocNotFound

{
  "errors": [{
    "message": "DOC_NOT_FOUND",
    "extensions": {
      "code": "DOC_NOT_FOUND",
      "spaceId": "workspace-id",
      "docId": "doc-id"
    }
  }]
}

The requested document does not exist.

DocActionDenied

{
  "errors": [{
    "message": "DOC_ACTION_DENIED",
    "extensions": {
      "code": "DOC_ACTION_DENIED",
      "action": "Doc.Update",
      "spaceId": "workspace-id",
      "docId": "doc-id"
    }
  }]
}

You don’t have permission to perform this action on the document.

DocUpdateBlocked

{
  "errors": [{
    "message": "DOC_UPDATE_BLOCKED",
    "extensions": {
      "code": "DOC_UPDATE_BLOCKED",
      "spaceId": "workspace-id",
      "docId": "doc-id"
    }
  }]
}

Document updates are currently blocked.