Skip to main content
Two endpoints manage the comment thread attached to a chattel document. GET /v1/documents/:id/comments retrieves the most recent 80 comments on a document. POST /v1/documents/:id/comments appends a new comment to the thread. Both endpoints require that the document belongs to your account.
The comment feature requires the Safeclose real-time service to be active. If the service is unavailable, POST requests return 503 Service Unavailable. Contact your workspace administrator if comments are consistently unavailable.

​
List comments

GET /v1/documents/:id/comments
Returns the most recent 80 comments on the specified document, in the order they were stored. The document must be owned by your authenticated account.

​
Request headers

​
Authorization
string
required
Bearer token obtained from your Clerk session. Example: Bearer eyJhbGc...

​
Path parameters

​
id
string
required
The unique identifier of the document whose comments you want to retrieve.

​
Response

​
comments
object[]
required
Array of comment objects. Returns at most 80 items, ordered from oldest to newest within that window.

​
Example

curl --request GET \
  --url https://your-api.example.com/v1/documents/doc_01j9z8x7w6v5u4t3s2r1q0p/comments \
  --header 'Authorization: Bearer <your-session-token>'

​
Post a comment

POST /v1/documents/:id/comments
Appends a new comment to the document’s comment thread. The comment is attributed to your authenticated account. Returns 503 if the real-time service is unavailable.

​
Request headers

​
Authorization
string
required
Bearer token obtained from your Clerk session.
​
Content-Type
string
required
Must be application/json.

​
Path parameters

​
id
string
required
The unique identifier of the document to comment on.

​
Request body

​
text
string
required
The comment text. Minimum 1 character, maximum 2000 characters.

​
Response

Returns 201 Created with the newly created comment object.
​
comment
object
required
The comment that was just appended to the thread.

​
Example

curl --request POST \
  --url https://your-api.example.com/v1/documents/doc_01j9z8x7w6v5u4t3s2r1q0p/comments \
  --header 'Authorization: Bearer <your-session-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Payoff quote received. Good through 2026-05-31."
  }'

​
Error cases

StatusError messageCause
400Invalid body.The text field is missing, empty, or exceeds 2000 characters.
401Missing Authorization Bearer token.No Authorization header was sent.
401Invalid or expired token.The Bearer token is malformed or has expired.
404Not found.No document with the given id exists, or it belongs to a different account.
503Redis not configured.The real-time service is not available. Comments cannot be written until the service is enabled. Applies to POST only.