GET and POST /v1/documents/:id/comments

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

string

required

Bearer token obtained from your Clerk session. Example: Bearer eyJhbGc...

Path parameters

string

required

The unique identifier of the document whose comments you want to retrieve.

Response

object[]

required

Array of comment objects. Returns at most 80 items, ordered from oldest to newest within that window.

Show comment properties

string

required

Account ID of the user who posted the comment.

string

required

Comment content. Maximum 2000 characters.

Example

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

{
  "comments": [
    {
      "userId": "usr_clerk_abc123",
      "text": "Verified lien release received from provider."
    },
    {
      "userId": "usr_clerk_xyz789",
      "text": "Updated payoff statement attached to the file. Remaining balance confirmed."
    }
  ]
}

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

string

required

Bearer token obtained from your Clerk session.

string

required

Must be application/json.

Path parameters

string

required

The unique identifier of the document to comment on.

Request body

string

required

The comment text. Minimum 1 character, maximum 2000 characters.

Response

Returns 201 Created with the newly created comment object.

object

required

The comment that was just appended to the thread.

Show comment properties

string

required

Your account ID — the authenticated user who posted this comment.

string

required

The comment text you submitted.

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."
  }'

{
  "comment": {
    "userId": "usr_clerk_abc123",
    "text": "Payoff quote received. Good through 2026-05-31."
  }
}

Error cases

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

Overview

Documents

Signing

Workspace

GET and POST /v1/documents/:id/comments

List comments

Request headers

Path parameters

Response

Example

Post a comment

Request headers

Path parameters

Request body

Response

Example

Error cases

​List comments

​Request headers

​Path parameters

​Response

​Example

​Post a comment

​Request headers

​Path parameters

​Request body

​Response

​Example

​Error cases

List comments

Request headers

Path parameters

Response

Example

Post a comment

Request headers

Path parameters

Request body

Response

Example

Error cases