--- title: "Document management API" description: "Manage your Tiptap documents programmatically with the Collaboration Management API. Find out more in the documentation." canonical_url: "https://tiptap.dev/docs/collaboration/documents/rest-api" --- # Document management API Manage your Tiptap documents programmatically with the Collaboration Management API. Find out more in the documentation. 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](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-cc186a66-df41-4df8-9c6e-e91b20deffe5). ## 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](mailto:humans@tiptap.dev). ## Access the API The REST API is exposed directly from your Document server at your custom URL: ```bash https://YOUR_APP_ID.collab.tiptap.cloud/ ``` Replace `YOUR_APP_ID` with your document server ID, which is labeled "Document server ID" in the [Cloud dashboard](https://cloud.tiptap.dev/v2/configuration/document-server). ### Authentication Authenticate your API requests by including your API secret in the `Authorization` header. You can find your API secret in the [settings](https://cloud.tiptap.dev/v2/configuration/document-server) 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](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-cc186a66-df41-4df8-9c6e-e91b20deffe5), 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` | Get 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. | | List Versions | GET | `/api/documents/:identifier/versions` | Get all versions of a document. | | Get Version | GET | `/api/documents/:identifier/versions/:versionId` | Get a specific version. | | Create Version | POST | `/api/documents/:identifier/versions` | Create a new version with optional name and metadata. | | Update Version | PATCH | `/api/documents/:identifier/versions/:versionId` | Update a version's name or metadata. | | Revert to Version | POST | `/api/documents/:identifier/versions/:versionId/revertTo` | Revert a document to an older version. | | 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. | Take a look at the [metrics and statistics endpoints](https://tiptap.dev/docs/collaboration/operations/metrics.md) as well! ## Create a document ```bash POST /api/documents/:identifier ``` This call lets you create a document using [binary Yjs](https://tiptap.dev/docs/collaboration/getting-started/overview.md#about-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](https://tiptap.dev/docs/collaboration/documents/rest-api.md#delete-a-document) first. - **Yjs format**: To create a document using a Yjs binary update message, first encode the Yjs document using `Y.encodeStateAsUpdate`. ```bash curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \ --header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \ --data '@yjsUpdate.binary' ``` - **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. ```bash 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 ```bash 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. ```bash 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 ```bash 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 either `yjs`, `base64`, `text`, 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 (e.g., `fragment=a&fragment=b`) or a single fragment you want to export. By default, we only export the `default` fragment. This parameter is only applicable when using the `json` or `text`format; with `yjs`, you'll always get the entire Yjs document. ```bash 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. ```typescript 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: ```typescript 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 ```bash 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. ```bash 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: ```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', }, }, ) ``` Note that the new document will not have the versions of the source document. If you want to preserve versions, you can use the import/export endpoint (see the postman collection) ## Encrypt a document ```bash 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. ```bash 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" } ] } ] }' ``` ## Version management Versions capture the state of a document at a point in time. Each version has a `version` number, `date`, and optionally a `name` and `meta` (arbitrary metadata object). Every version's `meta` object automatically includes a `__tiptap` key with server-generated metadata about who contributed changes and how the version was created. See [automatic version metadata](https://tiptap.dev/docs/collaboration/documents/snapshot.md#automatic-version-metadata) for details. For a full interactive reference of all version endpoints, see the [Postman Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-a6e8aa7e-c077-46ee-a2a3-241f8efd5d25?action=share\&creator=33042171\&active-environment=33042171-378cfb31-9c16-40f0-95b8-b9f0d3c7d2ab). ### Revert to version ```bash POST /api/documents/:identifier/versions/:versionId/revertTo ``` 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. The endpoint returns HTTP status `204` if the document is successfully reverted, or `404` if the document or version is not found. ```bash 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 version ```bash PATCH /api/documents/:identifier/versions/:versionId ``` This call lets you update a version's name or metadata. You can use this to rename versions or attach additional context after creation. For available request body parameters and examples, see the [Postman Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-a6e8aa7e-c077-46ee-a2a3-241f8efd5d25?action=share\&creator=33042171\&active-environment=33042171-378cfb31-9c16-40f0-95b8-b9f0d3c7d2ab). ## Update a document ```bash 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. ```bash 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' ``` 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](https://tiptap.dev/docs/collaboration/documents/content-injection.md) page. ## Delete a document ```bash 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. ```bash 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.