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. 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: 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 --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.

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 --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 --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).

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