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

# Comment on filings

> Add comments and replies, target document versions, and resolve discussions.

Readers can list comments. Editors can add comments and replies on managed
filings. No chat session is required. Comments use the existing filing
annotations, so native record discussions and these APIs share thread IDs.

Complete the [authentication setup](/guides/managed-filings#authenticate) and set
`FILING_ID` to a [filing workspace ID](/guides/managed-filings/read-filings).
Message bodies must contain non-whitespace text and be at most 20,000 characters.

## Start a discussion

Start a filing-level discussion:

```bash theme={null}
curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer ${EFFECTIVE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"body":"Please confirm the proposed effective date."}' \
  "${EFFECTIVE_API_BASE_URL%/}/api/v2/managed-filings/${FILING_ID}/comments"
```

The `201` response includes the comment `id`, `threadId`, actor, body, target,
creation time, and `status: "open"`. Save the comment ID as `COMMENT_ID`.

## Reply

Another Editor can reply from a different client or harness using its own credential:

```bash theme={null}
curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer ${EFFECTIVE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{\"body\":\"Confirmed.\",\"parentCommentId\":\"${COMMENT_ID}\"}" \
  "${EFFECTIVE_API_BASE_URL%/}/api/v2/managed-filings/${FILING_ID}/comments"
```

Replies inherit the original target. Reply to a top-level message; replies do
not nest further. Do not send `target` with `parentCommentId`.

## Comment on a document or record

To address a particular document version, create the first message with:

```json theme={null}
{
  "body": "Please verify the exclusion in this version.",
  "target": {
    "type": "artifact",
    "recordType": "filing_items",
    "recordId": "<filing item UUID>",
    "artifactId": "<attached file UUID>",
    "artifactVersionId": "<immutable Vault version UUID>"
  }
}
```

Discover versions through `GET /api/v1/artifacts/{artifactId}/versions`.
Use a version's `id`, not a legacy storage generation. The file must be the item's
primary document or a related attachment. The server checks file access and
that the version belongs to it. `submission_items` is also supported. Replacing
the working document does not move old comments or their replies to the new file.

For a record or field, use `target` with `type: "record"`, its `recordType`,
`recordId`, and optional `field` (for example `description`). The record must be
this filing or one of its filing items, submissions, submission items,
objections, or objection items. The field must exist on that record.

## List comments

List unresolved discussions with
`GET /api/v2/managed-filings/{filingId}/comments?status=open&limit=50`.
The response contains `comments` and `nextCursor`. Follow the cursor with the same
filing, status, and limit until null. Cursors expire after 24 hours. The timeline
includes status events and deletion tombstones, ordered by creation time and ID.
It is a live view; changes to thread status can change membership while paging.
Older native discussions may use `anchor` instead of an explicit `target`.
Only threads attached to the filing are listed, not unrelated artifact discussions.

## Resolve or edit a comment

Resolve a discussion with
`PATCH /api/v2/managed-filings/{filingId}/comments/{commentId}` and
`{"status":"resolved"}`. Use `{"status":"open"}` to reopen it. Any filing Editor
can do this; repeating the same state adds no event. To edit your own message,
send `{"body":"Corrected text"}` instead. Send only one of `body` or `status` per
request. Only the author can edit message text, and system events are immutable.
Resolution does not prove that a check passed or a prerequisite was met.

Targets are immutable. Imported filings remain read-only. POST is not idempotent;
after an uncertain result, inspect the timeline before retrying. Reading comments
does not grant permission to download the referenced document.

See [error recovery](/guides/managed-filings#recover-from-errors) for failed requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.