Internal API

Server-to-server API for the Hocuspocus real-time collaboration server. These endpoints are not intended for client use.

Base Path: /api/v1/internal/documents Authentication: API Key (X-Internal-Api-Key header) Tag: Hidden (Internal)

caution

These endpoints are for internal server-to-server communication only. They are protected by a shared API key, not JWT authentication. Do not expose these endpoints to client applications.

---

Check Permission

Verify if a user has edit permission on a document. Used by Hocuspocus to authorize collaborative editing connections.

GET /internal/documents/{documentId}/permission?userId={userId}

Headers

X-Internal-Api-Key: <shared_secret>

Path Parameters

Parameter	Type	Description
documentId	UUID	Document ID

Query Parameters

Parameter	Type	Required	Description
userId	String	Yes	Firebase UID or user identifier

Response

{
  "success": true,
  "data": {
    "canEdit": true,
    "role": "EDITOR",
    "workspaceId": "660e8400-e29b-41d4-a716-446655440000"
  }
}

Response Type: ApiResponse<DocumentPermissionResponse>

---

Load Yjs State

Load the binary Yjs CRDT state for a document. Used by Hocuspocus to initialize the collaboration state.

GET /internal/documents/{documentId}/yjs-state

Headers

X-Internal-Api-Key: <shared_secret>

Path Parameters

Parameter	Type	Description
documentId	UUID	Document ID

Response

• 200 OK - Returns the binary Yjs state as application/octet-stream
• 204 No Content - No Yjs state exists for this document

---

Save Yjs State

Save the Yjs CRDT state for a document. Called by Hocuspocus when collaboration state changes.

POST /internal/documents/{documentId}/yjs-state

Headers

X-Internal-Api-Key: <shared_secret>
Content-Type: multipart/form-data

Path Parameters

Parameter	Type	Description
documentId	UUID	Document ID

Form Data

Field	Type	Required	Description
yjsState	MultipartFile	Yes	Binary Yjs CRDT state
plainText	String	No	Extracted plain text (for search indexing)
jsonContent	String	No	JSON representation of document content
firebaseUid	String	No	Firebase UID of last editor

Response Type: ApiResponse<Void>