Document management API

The Collaboration Management API provides a suite of RESTful endpoints for managing documents. This API can be used for document creation, listing, retrieval, updates, and deletion, along with the ability to duplicate documents.

Review the postman collection

You can also experiment with the REST API by heading over to our Postman Collection.

Access the API

The REST API is exposed directly from your Collaboration app, available at your custom URL:

https://YOUR_APP_ID.collab.tiptap.cloud/

Authentication is done using an API secret which you can find in the settings of your Collaboration app. The secret must be sent as an Authorization header.

If your document identifier contains a slash (/), just make sure to encode it as %2F, e.g. using encodeURIComponent.

Review all API endpoints

Access the Collaboration Management API to manage your documents efficiently. You can create, list, retrieve, update, delete, and duplicate documents through our RESTful endpoints. For a comprehensive view of all endpoints across Tiptap products, review our Postman Collection which includes detailed examples and configurations.

Operation	Method	Endpoint	Description
Create Document	POST	/api/documents/:identifier	Create a document using a Yjs update message.
List Documents	GET	/api/documents	Retrieve a list of all documents with pagination options.
Get Document	GET	/api/documents/:identifier	Export a document in 'json' or 'yjs' format.
Update Document	PATCH	/api/documents/:identifier	Apply a Yjs update message to an existing document.
Delete Document	DELETE	/api/documents/:identifier	Delete a document from the server.
Duplicate Document	POST + GET	/api/documents/:identifier (GET then POST)	Duplicate a document by retrieving and then creating it with a new identifier.

Take a look at the metrics and statistics endpoints as well!

Create a document

POST /api/documents/:identifier

This call takes a binary Yjs update message (an existing Yjs document on your side must be encoded using Y.encodeStateAsUpdate) and creates a document. This can be used to seed documents before a user connects to the Tiptap Collab server.

This endpoint will return the HTTP status 204 if the document was created successfully, or 409 if the document already exists. If you want to overwrite it, you must delete it first.

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'

List documents

GET /api/documents?take=100&skip=0

This call returns a list of all documents present on the servers storage. We're returning the first 100 by default, pass take or skip parameters to adjust this.

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

Get a document

GET /api/documents/:identifier?format=:format&fragment=:fragment

This call exports the given document with all fragments in JSON format. We export either the current in-memory version or the version read from the database. If the document is currently open on your server, we will return the in-memory version.

format supports either yjs or json. Default: json

If you choose the yjs format, you'll get the binary Yjs update message created with Y.encodeStateAsUpdate.

fragment can be an array (fragment=a&fragment=b) of or a single fragment that you want to export. By default we only export the default fragment. Note that this is only taken into account when using the json format, otherwise you'll always get the whole Yjs document.

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

Specify arrayBuffer when using axios

When using axios, you need to specify responseType: arraybuffer in the options of the request.

import * as Y from 'yjs'

const ydoc = new Y.Doc()

const axiosResult = await axios.get(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc?format=yjs',
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
    responseType: 'arraybuffer',
  },
)

Y.applyUpdate(ydoc, axiosResult.data)

When using node-fetch, you need to use .arrayBuffer() and create a Buffer from it:

import * as Y from 'yjs'

const ydoc = new Y.Doc()

const fetchResult = await fetch(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc?format=yjs',
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
  },
)

Y.applyUpdate(ydoc, Buffer.from(await docUpdateAsBinaryResponse.arrayBuffer()))

Update a document

PATCH /api/documents/:identifier

This call accepts a Yjs update message and will apply it on the existing document on the server. This endpoint will return the HTTP status 204 if the document was updated successfully, 404 is the document does not exist, or 422 if the payload is invalid or the update cannot be applied.

curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'

The API endpoint is also capable of JSON document updates. It also supports document history, allowing you to track changes without replacing the entire document, and enables node-specific updates.

For more detailed information on manipulating documents using JSON instead of Yjs, refer to our Content injection page.

Delete a document

DELETE /api/documents/:identifier

This endpoint deletes a document from the server after closing any open connection to the document.

It returns either HTTP status 204 if the document was deleted successfully or 404 if the document was not found.

If the endpoint returned 204, but the document still exists, make sure that there is no user re-creating the document from the provider. We are closing all connections before deleting a document, but your error handling might re-create the provider, and thus create the document again.

curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

Duplicate a document

In order to copy a document, you can just use the GET endpoint and then create it again with the POST endpoint, here's an example in typescript:

const docUpdateAsBinaryResponse = await axios.get(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc?format=yjs',
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
    responseType: 'arraybuffer',
  },
)

await axios.post(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc-duplicated',
  docUpdateAsBinaryResponse.data,
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
  },
)

Rate limits

To maintain system integrity and prevent abuse, our infrastructure—including the management API and websocket connections through the TiptapCollabProvider—is subject to rate limits. These are designed to protect from misconfigured clients and ensure service reliability.

Default Rate Limits (per source IP):

{
  "requests": 100,
  "within_seconds": 5,
  "burst_capacity": 200
}

If you encounter these limits under normal operations, please contact us for assistance.