Inject content REST API
To inject content into documents server-side, use the PATCH endpoint described in this document. This feature supports version history, tracking changes made by users as well as content added through this endpoint.
The update document endpoint also allows JSON updates to modify documents on your Collaboration server, both On-Premises and Cloud.
- Add
json
,binary
,base64
content to any document server side - Inject content into specific nodes using the uniqueId extension
- Allow users to collaborate while content is injected
- Track user and injected content changes, fully compliant with version history
Use cases
The content injection REST API enables a couple of handy but sophisticated use cases.
- Live translation of document content.
- Programmatically tagging or manipulating the content of your documents server-side
- Server-side components, like executing an SQL query and displaying results.
- Version history integration and conflict-free merging of concurrent edits.
Subscription required
This feature requires a valid Business or Enterprise subscription and a running Tiptap Cloud instance.
Update a document
To update an existing document on the Collaboration server, you can use the PATCH
method with the following API endpoint:
PATCH /api/documents/:identifier?format=:format
This endpoint accepts a Yjs update message and applies it to the specified document. The format
query parameter specifies the format of the update and can be one of the following:
json
: Updates the document using JSON format (with some caveats, see below).binary
: Directly using Yjs'sY.encodeStateAsUpdate
method.base64
: The binary state encoded as a Base64 string.
Upon successful update, the server will return HTTP status 204
. If the document does not exist, it will return 404
, and if the payload is invalid or the update cannot be applied, it will return 422
.
Example curl
command to update a document:
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'
Update via JSON
When updating via JSON, the server computes the difference between the current document state and the provided JSON, then internally calculates the required Yjs update to reach the target state.
To ensure precise updates, especially for node-specific changes, it is recommended to use the nodeAttributeName
and nodeAttributeValue
parameters. These can be generated by Tiptap's UniqueID Extension or a custom implementation.
nodeAttributeName
: Configured asattributeName
in the UniqueID extension.nodeAttributeValue
: The unique value generated for the node to be updated.
From version 3.3.0 onwards, you can use ?mode=append
to append nodes to the document's JSON representation without altering existing content.
Omitting these parameters may result in overwriting any updates made between fetching the document and issuing the update call.
Here is an example of how to update a document using JSON:
// Define the document name, secret, and application ID
const docName = '' // URI-encoded if necessary
const secret = ''
const appId = '';
// Construct the base URL
const url = `https://${appId}.collab.tiptap.cloud`
// Fetch the current document's JSON representation
const docJson = await axios.get(`${url}/api/documents/${docName}?format=json`, {
headers: {
Authorization: secret
},
})
// Extract the document's JSON content
const tiptapJson = docJson.data
const nodes = tiptapJson.content
// Find and log specific nodes using their unique identifiers
const query = nodes.find(n => n.attrs?.identifier === 'fe5c0789-85d9-4877-a2c3-bccf5d874866').content[0].text
const resultTable = nodes.find(n => n.attrs?.identifier === '246368b6-0746-4ca1-a16f-8d964aff4041')
console.log(`Query: ${query}`)
console.log(JSON.stringify(resultTable.content))
// Append new content to the result table node
resultTable.content.push({
// New table row content here
{
"type": "tableRow",
"content": [
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "left"
},
"content": [
{
"type": "text",
"text": "Jan"
}
]
}
]
},
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "left"
},
"content": [
{
"type": "text",
"text": "Thurau"
}
]
}
]
},
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "left"
},
"content": [
{
"type": "text",
"text": "jan@janthurau.de"
}
]
}
]
}
]
}
})
// Send the updated JSON back to the server to apply the changes
await axios.patch(`${url}/api/documents/${docName}?format=json`, tiptapJson, {
headers: {
Authorization: secret
}
})
Create a document
To seed a new document on the Tiptap Collab server, use the POST
method with the following endpoint:
POST /api/documents/:identifier?format=:format
The server will return HTTP status 204
for successful creation, 409
if the document already exists (you must delete it first to overwrite), and 422
if the action failed.
The format
parameter accepts the same values as the update endpoint (binary
, base64
, or json
).