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, deletion, and duplication.
You can experiment with the REST API by visiting our Postman Collection.
Rate limits
To maintain system integrity and protect from misconfigured clients, our infrastructure—including the management API and websocket connections through the TiptapCollabProvider
—is subject to rate limits.
Default rate limits (per source IP):
- Requests: 100
- Time window: 5 seconds
- Burst capacity: Up to 200 requests
If you encounter these limits under normal operation, please email us.
Access the API
The REST API is exposed directly from your Collaboration app at your custom URL:
https://YOUR_APP_ID.collab.tiptap.cloud/
Authentication
Authenticate your API requests by including your API secret in the Authorization
header. You can find your API secret in
the settings of your Tiptap Cloud dashboard.
Document identifiers
If your document identifier contains a slash (/
), encode it as %2F
, e.g., using encodeURIComponent
.
API endpoints overview
Access the Collaboration Management API to manage your documents efficiently. For a comprehensive view of all endpoints across Tiptap products, explore 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 or json update message. |
Batch Import Documents | PUT | /api/admin/batch-import | Import multiple documents in bulk. |
Get Document | GET | /api/documents/:identifier | Export a document in json or yjs format. |
List Documents | GET | /api/documents | Retrieve a list of all documents with pagination options. |
Duplicate Document | POST + GET | /api/documents/:identifier (GET then POST) | Duplicate a document by retrieving it and then creating it with a new identifier. |
Encrypt Document | POST | /api/documents/:identifier/encrypt | Encrypt a document using Base64. |
Revert to Version | POST | /api/documents/:identifier/versions | Import multiple documents in bulk. |
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. |
Search Documents | POST | /api/search | Execute a search on all documents. |
Take a look at the metrics and statistics endpoints as well!
Create a document
POST /api/documents/:identifier
This call lets you create a document using binary Yjs or JSON format (default: yjs
). It can be used to seed documents before a user connects to the Tiptap Collaboration server.
The endpoint returns HTTP status 204
if the document is created successfully, or 409
if the document already exists. To overwrite an existing document, you must delete it first.
- Yjs format: To create a document using a Yjs binary update message, first encode the Yjs document using
Y.encodeStateAsUpdate
.
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'
- JSON format: To create a document using JSON, pass the query parameter
format=json
and include the document's content in the Tiptap JSON format.
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--header 'Content-Type: application/json' \
--data '{
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "This is your content."
}
]
}
]
}'
Batch import documents
PUT /api/admin/batch-import
This call lets you import multiple documents in bulk using a predefined JSON structure. Each document must include its metadata (such as created_at, name, and version) and its content in the Tiptap JSON format.
The endpoint returns HTTP status 204
if the documents are imported successfully, or 400
if the request contains invalid data.
curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/batch-import' \
--header 'Content-Type: application/json' \
--data '[
[
{
"created_at": "2024-05-01T10:00:00Z",
"version": 0,
"name": "document-1",
"tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Text of document-1: v0"}]}]}
},
{
"created_at": "2024-05-01T11:00:00Z",
"version": 1,
"name": "document-1",
"tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Text of document-1: v1"}]}]}
}
],
[
{
"created_at": "2024-06-01T10:00:00Z",
"version": 0,
"name": "document-2",
"tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Text of document-2: v0"}]}]}
},
{
"created_at": "2024-06-01T11:00:00Z",
"version": 1,
"name": "document-2",
"tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Text of document-2: v1"}]}]}
}
]
]'
Get a document
GET /api/documents/:identifier?format=:format&fragment=:fragment
This call lets you export the specified document with all fragments in JSON or Yjs format. If the document is currently open on your server, we will return the in-memory version; otherwise, we read from the database.
-
format
supports eitheryjs
,base64
,text
, orjson
(default:json
). If you choose theyjs
format, you'll get the binary Yjs update message created withY.encodeStateAsUpdate
. -
fragment
can be an array (e.g.,fragment=a&fragment=b
) or a single fragment you want to export. By default, we only export thedefault
fragment. This parameter is only applicable when using thejson
ortext
format; withyjs
, you'll always get the entire Yjs document.
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
When using axios
, you need to specify responseType: arraybuffer
in the request options.
import * as Y from 'yjs'
const ydoc = new Y.Doc()
const axiosResult = await axios.get(
'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?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/DOCUMENT_NAME?format=yjs',
{
headers: {
Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
},
},
)
Y.applyUpdate(ydoc, Buffer.from(await docUpdateAsBinaryResponse.arrayBuffer()))
List documents
GET /api/documents?take=100&skip=0
This call returns a paginated list of all documents in storage. By default, we return the first
100 documents. Pass take
and skip
parameters to adjust pagination.
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
Duplicate a document
This call lets you copy or duplicate a document. First, retrieve the document using the GET
endpoint and then create a new one with the
POST
call. Here's an example in typescript:
const docUpdateAsBinaryResponse = await axios.get(
'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs',
{
headers: {
Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
},
responseType: 'arraybuffer',
},
)
await axios.post(
'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME-duplicated',
docUpdateAsBinaryResponse.data,
{
headers: {
Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
},
},
)
Encrypt a document
POST /api/documents/:identifier/encrypt
This call lets you encrypt a document with the specified identifier using Base64 encryption.
The endpoint returns HTTP status 204
if the document is successfully encrypted, or 404
if the document does not exist.
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/encrypt' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '{
"type": "doc",
"content": [
{
"type": "paragraph",
"attrs": {
"indent": 0,
"textAlign": "left"
},
"content": [
{
"text": "the entire document is replaced by this (except if you changed the mode parameter to '\''append'\'')",
"type": "text"
}
]
}
]
}'
Revert to version
POST /api/documents/:identifier/versions
This call lets you revert a document to a specific previous version by applying an update that corresponds to a prior state of the document. You must specify the version to revert to in the request body.
The endpoint returns HTTP status 204
if the document is successfully reverted, or 404
if the document or version is not found.
curl --location --request POST 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/versions/VERSION_ID/revertTo' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
Update a document
PATCH /api/documents/:identifier
This call accepts a Yjs update message and applies it to the existing document on the server.
The endpoint returns the HTTP status 204
if the document was updated successfully, 404
if
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 also supports JSON document updates, document history for tracking changes without replacing the entire document, and 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 call 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.
curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
Document persists after deletion
If the endpoint returns 204
but the document still exists, make sure that no user is re-creating the document from the provider. We close all connections before deleting a document, but your error handling might recreate the provider, thus creating the document again.
Search documents
POST /api/search
When Tiptap Semantic Search is enabled, you can perform contextually aware searches across all your documents.
Keeping your API key secret
Please handle the search requests in your backend to keep your API key secret. Consider enforcing rate limits in your application as necessary.
Query parameters
You can use the following query parameters to adjust the search results:
Query parameter | Type | Default | Description |
---|---|---|---|
threshold | float | 0.5 | Describes the similarity factor of documents. The value can be between 0 an 1 . |
limit | int | 20 | Limit the number of results. The value can be between 1 an 100 . |
Body parameters
Body parameter | Type | Default | Description |
---|---|---|---|
content | string | - | Your search terms. |
curl -X POST https://YOUR_APP_ID.collab.tiptap.cloud/api/search \
-H "Authorization: YOUR_SECRET_FROM_SETTINGS_AREA" \
-H "Content-Type: application/json" \
-d '{"content": "Your search terms"}'