---
title: "Collaboration API"
description: "Collaboration API"
canonical_url: "https://tiptap.dev/docs/guides/collaboration-api"
---

# Collaboration API

Collaboration API

## Add initial content to a document

In order to add initial content to a document (or create an empty document), you can use our create document API.

Note that you need to replace `APP_ID`, `DOCUMENT_NAME` and `API_SECRET` with your own values. The `APP_ID` is your document server ID, labeled "Document server ID" in the [Cloud dashboard](https://cloud.tiptap.dev/v2/configuration/document-server).
If you want to just create an empty document, you can send an empty array as `content`.

The payload of the request should be Tiptap JSON, which you can get by calling `editor.getJSON()` (see [Get JSON](https://tiptap.dev/docs/guides/output-json-html.md#option-1-json))

```curl
curl --location \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_SECRET' \
--data '{
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "attrs": {
          "indent": 0,
          "textAlign": "left"
        },
        "content": [
          {
            "text": "This is my initial content.",
            "type": "text"
          }
        ]
      }
    ]
}'
```

## Update the full content of a document

Updating a document is as simple as fetching the current JSON document, applying your changes to it, and sending it back to us.

Use the following request to fetch the current JSON document.

```curl
curl --location \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Authorization: API_SECRET' \
```

Now, you can apply your changes to the JSON, and then send it back to us. We will calculate the diff between your new JSON and the current state of the document, and apply it in a collaborative way.
If you only want to update a single node, see [Update a single node in a document](#update-a-single-node-in-a-document).

```curl
curl --location --request PATCH \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_SECRET' \
--data 'UPDATED_JSON'
```

## Update a single node in a document

Use the following request to fetch the current JSON document.

```curl
curl --location \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Authorization: API_SECRET'
```

Now, you can identify the node that you want to update and apply your update in the JSON. You then need to send only that updated node back to us, but in the full Tiptap JSON format.
To tell us which node you want to update, you need to pass query parameters `nodeAttributeName` and `nodeAttributeValue`. For example, if you use our unique-id
extension and the target node has an `id` attribute with value `12345`, you would pass `nodeAttributeName=id&nodeAttributeValue=12345`. Note that this only works for top-level nodes.

```curl
curl --location --request PATCH \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json&nodeAttributeName=id&nodeAttributeValue=12345' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_SECRET' \
--data 'UPDATED_JSON'
```

An example of `UPDATED_JSON` can be found below. Only include the node that should be updated and omit all others (from the "content" array).

```json
{
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "attrs": {
          "id": "12345"
        },
        "content": [
          {
            "text": "The API will update the node that matches the query filters (nodeAttributeName and nodeAttributeValue from the query) with the content of this node.",
            "type": "text"
          }
        ]
      }
    ]
}
```

## Delete a node in a document

In order to delete an entire node in a document, you can send a request like this.

Make sure to replace `ATTR_NAME` and `ATTR_VALUE` with your own values, for example "id" and "12345".

```curl
curl --location --request PATCH \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json&nodeAttributeName=ATTR_NAME&nodeAttributeValue=ATTR_VALUE&mode=delete' \
--header 'Authorization: API_SECRET'
```

## Update attributes of a node in a document

If you want to update the attributes of a node, you can send a request like below.
Note that this deletes all attributes that are not part of the request, if you don't want that,
you can add `mergeAttributes=1` to the URL.

Make sure to replace `ATTR_NAME` and `ATTR_VALUE` with your own values, for example "id" and "12345".

```curl
curl --location --request PATCH \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json&nodeAttributeName=ATTR_NAME&nodeAttributeValue=ATTR_VALUE&mode=attrs' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_SECRET' \
--data '{
    "level": 3
}'
```