Skip to content

[PLAT-8079] Documenting Body Documents as a "core concept" with updated examples #104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MadisonEhlers-Vertex merged 2 commits into from
Mar 5, 2026
Merged

[PLAT-8079] Documenting Body Documents as a "core concept" with updated examples #104

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b5faa8
[PLAT-8079] Documenting Body Documents as a "core concept" with updat…
MadisonEhlers-Vertex Mar 4, 2026
f93c3bd
removing extra content
MadisonEhlers-Vertex Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 127 additions & 6 deletions docs/guides/collaboration-apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,51 @@ to continue discussions, provide updates, or give feedback.
An **Attachment** is an additional linked relationship to a reply or a thread. Users can attach
files and other kinds of data to be provided as additional context for a thread or reply.

### Body Document
A **Body Document** is a field contained within a reply or a thread. The body document is modeled as an Abstract Syntax Tree (AST) that enables
clients to specify various forms of textual representations for **threads** and **replies**. Vertex allows you to specify mentions within your thread or reply,
and then your client can display the AST however the client decides to display and style the data therein.

#### Example - Body Document With Text Only
```json
"document": {
"type": "text-document-v1",
"root": {
"type": "root-node",
"content": [
{
"type": "paragraph-node",
"content":[
{
"type": "text-node",
"text": "Text Only Document"
}
]
}
]
}
}
```

#### Example - Body Document With Mention
```json
"document": {
"type": "text-document-v1",
"root": {
"type": "root-node",
"content": [
{
"type": "paragraph-node",
"content": [
{ "type": "text-node", "text": "Hey " },
{ "type": "mention-node", "userId": "{USER_UUID}" },
{ "type": "text-node", "text": ", could you please review this?" }
]
}
]
}
}
```

## Access Control

Expand Down Expand Up @@ -248,7 +293,26 @@ curl --request POST 'https://platform.vertexvis.com/collaboration-contexts/YOUR_
"data": {
"type": "thread",
"attributes": {
"body": "Gap found in left flange",
"withBodyDocument": {
"type": "with-body-document",
"document": {
"type": "text-document-v1",
"root": {
"type": "root-node",
"content": [
{
"type": "paragraph-node",
"content":[
{
"type": "text-node",
"text": "Gap found in left flange"
}
]
}
]
}
}
},
"type": "issue",
"status": "open"
}
Expand All @@ -266,7 +330,26 @@ curl --request POST 'https://platform.vertexvis.com/threads/YOUR_THREAD_ID/repli
"data": {
"type": "reply",
"attributes": {
"body": "We will update the CAD file to fix this issue."
"withBodyDocument": {
"type": "with-body-document",
"document": {
"type": "text-document-v1",
"root": {
"type": "root-node",
"content": [
{
"type": "paragraph-node",
"content": [
{
"type": "text-node",
"text": "We will update the CAD file to fix this issue."
}
]
}
]
}
}
}
}
}
}'
Expand All @@ -286,7 +369,7 @@ These endpoints demonstrate how to update and filter your threads and replies.
### Update a Thread

Updates an existing thread to modify the body, title, status or other fields. You can update the drafting state when you are ready for your thread to be visible in a list request. Any fields you do not want to change can be omitted.
Editing the title or body will result in a new field `editedAt` to be populated on the thread, that will indicate the contents of the thread have been modified. Status and drafting state will not impact the `editedAt` field.
Editing the title or body document will result in a new field `editedAt` to be populated on the thread, that will indicate the contents of the thread have been modified. Status and drafting state will not impact the `editedAt` field, nor will modifying the other fields while the thread is in a "drafting" state.

```bash
curl --request PATCH 'https://platform.vertexvis.com/threads/YOUR_THREAD_ID' \
Expand All @@ -295,7 +378,26 @@ curl --request PATCH 'https://platform.vertexvis.com/threads/YOUR_THREAD_ID' \
--data '{
"data": {
"attributes": {
"body": "Updated Body",
"withBodyDocument": {
"type": "with-body-document",
"document":{
"type": "text-document-v1",
"root": {
"type": "root-node",
"content": [
{
"type": "paragraph-node",
"content": [
{
"type": "text-node",
"text": "Updated Body"
}
]
}
]
}
}
},
"isDrafting": false,
"status": "resolved",
"title": "Updated Title"
Expand Down Expand Up @@ -329,7 +431,7 @@ curl --request DELETE 'https://platform.vertexvis.com/threads/YOUR_THREAD_ID' \

### Update a Reply

Editing the body of a reply will result in a new field `editedAt` to be populated on the reply, this field indicates that the reply has been modified from its original state. Drafting state will not impact the `editedAt` field.
Editing the body document of a reply will result in a new field `editedAt` to be populated on the reply, this field indicates that the reply has been modified from its original state. Drafting state will not impact the `editedAt` field.

```bash
curl --request PATCH 'https://platform.vertexvis.com/replies/YOUR_REPLY_ID' \
Expand All @@ -338,7 +440,26 @@ curl --request PATCH 'https://platform.vertexvis.com/replies/YOUR_REPLY_ID' \
--data '{
"data": {
"attributes": {
"body": "Updated reply body",
"withBodyDocument": {
"type": "with-body-document",
"document": {
"type": "text-document-v1",
"root":{
"type": "root-node",
"content": [
{
"type": "paragraph-node",
"content": [
{
"type": "text-node",
"text": "Updated reply body"
}
]
}
]
}
}
},
"isDrafting": false
},
"type": "reply"
Expand Down