Join the document's live co-editing room

POST

/api/v1/documents/{id}/live

For documents of teams and classes on a plan with live editing (or shared between members of one), when the organisation's policy allows it. Returns {url, token, expiresAt, role: viewer|editor, colour, name}: open a WebSocket to url?token=… within 10 minutes (Yjs sync and awareness, binary). Ask again to reconnect. 402 plan_required without the plan; 403 policy_denied when turned off. While a room is open, text writes answer 409 live_session_active.

App integration: Admission is available only to user principals with document access and eligible live-editing entitlement/policy. Use the returned short-lived token in the separate binary WebSocket protocol. Acquire fresh admission on reconnect; standalone personal accounts may receive 402 plan_required.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://handwrites.io/oauth/authorize

Token URL: https://handwrites.io/api/oauth/token

Refresh URL: https://handwrites.io/api/oauth/token

Scopes:

documents:read-List, fetch and download documents, including ones shared with you

Path Params

Responses

🟢200

application/json

The session.

Headers

Bodyapplication/json

🟠402

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠429TooManyRequests

🔴500ServerError

🔴503Unavailable

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/api/v1/documents//live' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Example 1

{
    "url": "string",
    "token": "string",
    "expiresAt": "2019-08-24T14:15:22.123Z",
    "role": "viewer",
    "colour": "string",
    "name": "string"
}

Modified at 2026-10-26 12:58:15

Replace the text

Every document you own, with its text