tiptap/docs/collaboration/management-api.md

tableOfContents
true

Management API

The Collaboration Management API provides a suite of RESTful endpoints for managing documents and their collaborative aspects. This API facilitates document creation, listing, retrieval, updates, and deletion, along with the ability to duplicate documents for efficient content management. Additionally, it includes settings management for runtime configuration without the need for restarts, and server statistics to monitor performance metrics like document counts and connection statistics

Explore the Postman Collection for a hands-on experience, allowing you to experiment with the REST API's capabilities.

Accessing the Management 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.

Document Operations

Create 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 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'll export all fragments. 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'

Note: 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 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'

Delete 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 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',
  },
})

Configuration Settings

TiptapCollab has a few settings that can be configured at runtime (no restart needed):

Key	Type	Editable	Description
secret	string	Yes	The secret used to sign JWT tokens ; auto-generated on first boot.
api_secret	string	Yes	The secret that is sent in API calls (as the Authorization header) ; auto-generated on first boot.
webhook_url	string	Yes	The webhook URL ; optional
authentication_disabled	string	Yes	Whether authentication is disabled. Must be 1 or 0 ; optional (default = 0)
name	string	Yes	The name of the instance ; optional

Create setting

If you want to create or overwrite settings, this is the API for it.

curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

List settings

All current settings can be retrieved with the GET /api/admin/settings call.

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

Get setting

If you want to get a setting value, this is the API for it.

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

Update setting

If you want to create or overwrite settings, this is the API for it.

curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

Delete setting

If you want to delete settings, this is the API for it.

curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

Server Performance

You can get a few server statistics using the /api/statistics endpoint. We currently export the total number of documents, the maximum concurrent connections (last 30 days), the total number of connections (last 30 days) and the lifetime connection count. Not that the last two values are exported as string, as they are internally a BIGINT.

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