> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safeclose.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Read the most recent 80 comments on a chattel document or post a new comment. Both endpoints are scoped to documents owned by your account.

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.

<Note>
  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.
</Note>

***

## List comments

```http theme={null}
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

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from your Clerk session. Example: `Bearer eyJhbGc...`
</ParamField>

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the document whose comments you want to retrieve.
</ParamField>

### Response

<ResponseField name="comments" type="object[]" required>
  Array of comment objects. Returns at most 80 items, ordered from oldest to newest within that window.

  <Expandable title="comment properties">
    <ResponseField name="userId" type="string" required>
      Account ID of the user who posted the comment.
    </ResponseField>

    <ResponseField name="text" type="string" required>
      Comment content. Maximum 2000 characters.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://your-api.example.com/v1/documents/doc_01j9z8x7w6v5u4t3s2r1q0p/comments \
    --header 'Authorization: Bearer <your-session-token>'
  ```

  ```json Response 200 theme={null}
  {
    "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."
      }
    ]
  }
  ```
</CodeGroup>

***

## Post a comment

```http theme={null}
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

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from your Clerk session.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the document to comment on.
</ParamField>

### Request body

<ParamField body="text" type="string" required>
  The comment text. Minimum 1 character, maximum 2000 characters.
</ParamField>

### Response

Returns `201 Created` with the newly created comment object.

<ResponseField name="comment" type="object" required>
  The comment that was just appended to the thread.

  <Expandable title="comment properties">
    <ResponseField name="userId" type="string" required>
      Your account ID — the authenticated user who posted this comment.
    </ResponseField>

    <ResponseField name="text" type="string" required>
      The comment text you submitted.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash Request theme={null}
  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."
    }'
  ```

  ```json Response 201 theme={null}
  {
    "comment": {
      "userId": "usr_clerk_abc123",
      "text": "Payoff quote received. Good through 2026-05-31."
    }
  }
  ```
</CodeGroup>

***

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