Review workflows

Scopes needed: comments:write to comment, comments:read to list or export, shares:write to create a review link, and members:read to resolve a user id to a name.

1. Comment on a file

Comments (and replies) are nested under the file they belong to. A video or audio comment can anchor to a timestamp; an image or video comment can carry drawn annotations.

curl -X POST https://us.api.brault.app/v1/files/<file_id>/comments \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-7777-4c1a-9c1e-comment-create" \
  -d '{
    "text": "The logo needs to sit lower in this frame.",
    "timestamp_ms": 4200,
    "annotations": [
      { "type": "rectangle", "coordinates": [{"x": 0.62, "y": 0.08}, {"x": 0.94, "y": 0.22}] }
    ]
  }'

{
  "object": "comment",
  "id": "<comment_id>",
  "file_id": "<file_id>",
  "version_id": null,
  "text": "The logo needs to sit lower in this frame.",
  "author": { "user_id": "<user_id>" },
  "anonymous_name": null,
  "mentions": [],
  "timestamp_ms": 4200,
  "annotations": [
    { "type": "rectangle", "coordinates": [{"x": 0.62, "y": 0.08}, {"x": 0.94, "y": 0.22}] }
  ],
  "resolved": false,
  "resolved_at": null,
  "resolved_by_id": null,
  "has_replies": false,
  "created_at": "2026-09-06T10:00:00.000Z",
  "updated_at": "2026-09-06T10:00:00.000Z",
  "edited_at": null
}

Mention someone inline with [@<user_id>] in text — resolve the id to a name with GET /v1/members/:userId under the members:read scope.

2. Resolve it once addressed

curl -X POST https://us.api.brault.app/v1/files/<file_id>/comments/<comment_id>/resolve \
  -H "Authorization: Bearer $BRAULT_API_KEY"

Anyone who can view the file can resolve or reopen a comment. Only the original author can edit its text — an owner or admin gets the same shared 404 as anyone else on someone else's comment. Deleting it is broader: the author, or a creator whose brandspace role is owner or admin, can delete it.

3. Share the file for external review

access: "review" lets a visitor comment on the file without a Brault account:

curl -X POST https://us.api.brault.app/v1/shared-links \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-8888-4c1a-9c1e-share-create" \
  -d '{
    "target": { "type": "file", "id": "<file_id>" },
    "access": "review",
    "anonymous_comments": true,
    "expires_at": "2026-10-01T00:00:00.000Z"
  }'

{
  "object": "shared_link",
  "id": "8xK3mZq2p1a",
  "url": "https://brault.app/shared/8xK3mZq2p1a",
  "target": { "type": "file", "id": "<file_id>" },
  "access": "review",
  "password_protected": false,
  "expires_at": "2026-10-01T00:00:00.000Z",
  "expired": false,
  "anonymous_comments": true,
  "show_versions": true,
  "show_properties": true,
  "display_mode": "grid",
  "board_views": null,
  "view_count": 0,
  "created_at": "2026-09-06T10:00:00.000Z",
  "updated_at": "2026-09-06T10:00:00.000Z",
  "created_by_id": "<user_id>"
}

Send password (4–72 bytes, bcrypt's own limit) to require a password, and remember that a target can only ever have one link — creating a second one for the same file answers 409 conflict with the existing link's id in details.shared_link_id.

A target you can name isn't necessarily one you can already see everything in. For file, folder and library targets, shares:write only checks that the target belongs to your own brandspace — not that your key's creator can otherwise open it. A board target is the one exception: sharing a board additionally requires the creator's own management access to it.

4. Export comments for a paper trail

curl "https://us.api.brault.app/v1/files/<file_id>/comments?format=csv" \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -o comments.csv

The export never carries a name or email — every person is a user id, except anonymous_name, the display name a shared-link visitor typed on their own comment. See the Comments reference for the full column list.