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 and DOCUMENT_NAME with your own values, and YOUR_JWT with a signed token carrying Documents:Api:All (see Authentication). Keep that token server-side, since it grants full API access. The APP_ID is your document server ID, labeled "Document server ID" in the Cloud dashboard. 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)

curl --location \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT' \
--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 --location \
'https://APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Authorization: Bearer YOUR_JWT' \

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.

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

Update a single node in a document

Use the following request to fetch the current JSON document.

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

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 --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: Bearer YOUR_JWT' \
--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).

{
    "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 --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: Bearer YOUR_JWT'

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 --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: Bearer YOUR_JWT' \
--data '{
    "level": 3
}'