Comments API Threading, mentions, reactions, and reference anchoring for workspace and share entities.

Comments use JSON request bodies (Content-Type: application/json), unlike most other Fastio endpoints which use application/x-www-form-urlencoded.

Endpoint Summary

Searching comments: To search comments by keyword, use the unified search endpoint — GET /current/workspace/{workspace_id}/search/ (or /current/share/{share_id}/search/) returns a comments bucket alongside files and other types, each with its own pagination. See Unified Search in the Storage Operations reference. Comment search results are permission-filtered to comments the caller can see.

Path Parameters

Comments are scoped to a workspace, share, or File Share, and optionally to a specific node (file or folder) within it. When no node ID is specified, all comments across the entire workspace or share are returned.

File Share comments. When {entity_type} is "fileshare", {parent_id} is the File Share's 19-digit numeric profile ID. Comments on a File Share are scoped to that File Share — a recipient sees only the comments made under it, never comments on the same underlying file from the owning workspace or from another File Share. Commenting requires the viewer to be signed in; public anyone-with-link visitors cannot comment. Comments are available only when the File Share owner has enabled comments, and they are always disabled on public anyone-with-link shares. A client should read the File Share's effective comments_enabled flag from its details response to decide whether to show the comment UI.

Comment Object

Every comment returned by the API has this structure:

Null fields are omitted on most responses. On the list, create/update, update-by-ID and delete responses, a field whose value is null is left out rather than sent as null — parent_id, profile_type, profile_id, scope_id, linked_entity_*, external_author_*, reference, user_reaction, version_hash and edited_at. The details and unlink responses send them as null. Treat a missing key and null the same.

Note: the server-validated mentions set is surfaced as the top-level mentions array described above. The raw internal properties object (threading, pinning, content-filter flags, etc.) is never returned — only the curated mentions list is exposed.

Service accounts. A workspace service-account key may read comments in its own workspace; an editor may also create, edit, delete, react to and attach to them. Comments on a share or a File Share are refused with 403 and error.params.reason = service_account_not_permitted (even when the share belongs to the workspace), and comments that originated under a File Share (scope_id set) are left out of what it reads. A comment it writes has an actor carrying service_account: true, credential_id, credential_hint, account_type: "service_account" and the account's name (see Service-account keys). A service account is never notified of a mention or reply.

Thread State Fields (root comments only)

A thread is a root comment (one with no parent_id) plus its replies. These fields carry the thread's state and live on the root; a reply returns them as null/omitted, the same as any other null field (see Null fields are omitted above).

List Comments

Without {node_id}: returns all comments across the entire workspace or share. With {node_id}: returns only comments on that specific file or folder.

Note: Only comments created after 2026-03-15 are included in scope-level results (without {node_id}); older comments are accessible via the node-level endpoint.

Auth: Required (JWT). Rate limited.

Query Parameters

Request Example

curl -X GET "https://api.fast.io/current/comments/workspace/1234567890123456789/?limit=50&include_total=true" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "comments": [
    {
      "id": "abc123opaqueid",
      "entity": "xyz789opaqueid",
      "user_id": "1234567890123456789",
      "actor": {
        "user_id": "1234567890123456789",
        "kind": "human",
        "agent_name": null,
        "name_source": null,
        "credential_type": "session",
        "verified": false
      },
      "body": "This looks great!",
      "profile_type": "workspace",
      "profile_id": "1234567890123456789",
      "mentions": [],
      "reactions": {"👍": 2, "❤️": 1},
      "user_reaction": "👍",
      "version": 1,
      "created": "2025-01-15 10:30:00 UTC",
      "updated": "2025-01-15 10:30:00 UTC",
      "can_edit": true,
      "can_delete": true,
      "can_reply": true,
      "attachment_count": 0
    }
  ],
  "count": 1,
  "allowed": true,
  "remaining": 95,
  "total": 5,
  "limit": 50,
  "offset": 0
}

Response Fields

Thread Grouping (group=threads)

Without group=threads, the response is the flat shape above, unchanged. With group=threads, limit and offset page by root thread instead of by individual comment, and the response is:

{
  "result": true,
  "threads": [
    {
      "id": "abc123opaqueid",
      "kind": "comment",
      "resolved": false,
      "state_version": 2,
      "replies": [ { "id": "def456opaqueid", "parent_id": "abc123opaqueid" } ],
      "replies_total": 1
    }
  ],
  "counts": {"all": 12, "open": 9, "done": 3, "for_me": 2, "for_me_agents": 0, "open_comments": 8, "pending_suggestions": 1},
  "limits": {"root_threads_used": 12, "root_threads_max": 1000},
  "limit": 50,
  "offset": 0,
  "total": 12
}

Access Levels

Error Responses

Reading the error tables: the four-digit 16xx/17xx values below are HTTP-status classes, not error.code. The error.code a client actually receives is assigned per endpoint, so use the HTTP status as the gate and a documented error.code — five or six digits, plus the 9661-9669 family — only as a refinement. A 16xx value identifies the status class — useful for telling which kind of failure occurred — but comparing one against error.code will never match. Five- and six-digit codes (and the 9661-9669 family) are real error.code values. If you widen a check from a specific code to a status, widen what you assert with it — a status covers failures the narrower code did not, so a message written for that one code becomes a confident falsehood on the rest.

Share reads are filtered and paged by thread. On a share (GET /current/comments/share/{share_id}/ and .../{node_id}/), the access table above decides what you see, and comments on files you cannot view (for example, another guest's upload on a Receive share) are never shown. limit and offset count the top-level comments you can see, and each one is followed by its replies that you can see, so count can be larger than limit. With include_total=true, total is the number of top-level comments you can see. allowed and remaining reflect the share's full comment count, not only the comments visible to you. A comment you cannot see answers 404 "Comment not found" on its details, reactions and attachments routes, and replying to it answers 404 "Parent comment not found". Share search results follow the same rules.

Workspace node reads include File Share comments. A file shared through a File Share is the same node that lives in the owning workspace, so a workspace node read (GET /current/comments/workspace/{workspace_id}/{node_id}/) also returns comments left by File Share recipients on that file. Those File Share comments appear read-only in the workspace view: can_reply, can_edit, and can_delete are false (replies and edits to a File Share comment go through the File Share's own surface). The total count reflects everything visible in the listing (the workspace's own comments plus the File Share comments), while the allowed / remaining fields reflect only the workspace's own writable comments — so remaining is not reduced by File Share comments you cannot edit. This inclusion is one-directional: workspace members see File Share comments, but File Share recipients never see the workspace's internal comments.

Create or Update Comment

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example — Create a new comment

curl -X POST "https://api.fast.io/current/comments/workspace/1234567890123456789/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Great work on this document!"
  }'

Request Example — Reply to a comment

curl -X POST "https://api.fast.io/current/comments/workspace/1234567890123456789/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Thanks for the feedback!",
    "parent_id": "abc123opaqueid"
  }'

Request Example — Comment with mention and page reference

curl -X POST "https://api.fast.io/current/comments/workspace/1234567890123456789/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hey @[user:9876543210987654321:Jane Smith], can you review page 3?",
    "reference": {"type": "document", "page": 3}
  }'

Request Example — Update an existing comment

curl -X POST "https://api.fast.io/current/comments/workspace/1234567890123456789/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "comment_id": "def456opaqueid",
    "body": "Updated: This looks great after the revision."
  }'

Response

{
  "result": true,
  "comment": {
    "id": "abc123opaqueid",
    "entity": "xyz789opaqueid",
    "user_id": "1234567890123456789",
    "actor": {
      "user_id": "1234567890123456789",
      "kind": "agent",
      "agent_name": "Dobby",
      "name_source": "api_key_label",
      "credential_type": "api_key",
      "verified": false
    },
    "body": "Great work on this document!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "mentions": [],
    "reactions": [],
    "version": 1,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC",
    "can_edit": true,
    "can_delete": true,
    "can_reply": true
  },
  "attachments": [],
  "attachment_count": 0
}

Response Fields

Access Levels

Error Responses

Notes

• Body fidelity: The body is trimmed of leading and trailing whitespace and then stored unmodified — HTML is not stripped or escaped — so code, generic type parameters (Array<T>), path templates (<workspace-id>), and structured data such as data: {count: 5} survive a round trip intact. Treat a returned body as untrusted input and escape it in your own client before rendering it as HTML.
• Content filtering: No profanity, spam, or PII filtering is applied to bodies today. The spam-rejection response documented under Content Filtering remains part of this endpoint's contract and is not currently triggered.
• Mentions: Mentioned users are parsed and validated against entity membership before the comment is saved. A mention that sits inside markdown code is treated as quoted text — it notifies nobody and counts in full against the 500-character display cap (see Mentions inside code).
• Thread limits: Each file has a limit on its threads (top-level comments, including suggestion threads); replies are never counted against it. See Thread Limits under Thread State: Resolve, Reopen, Assign below.
• Reopening and assigning on reply: a reply body may carry reopen and/or assign (see Request Body above); both apply atomically with the reply.
• Updating: Only the original author can edit. Editing populates the top-level edited_at timestamp on the returned comment. A text anchor (exact / prefix / suffix) is fixed when the comment is created: an edit may resend it unchanged or omit reference, but cannot change it.
• Server-managed properties: reactions, version, version_hash, edited_at, content_filtered, mentions, actor, pinned and reply_to in a request's properties are ignored on create and on edit — only the server writes them.
• Mention notifications on edit: an edit notifies only the people it newly mentions; anyone already mentioned before the edit is not notified again.
• Creation rate: comment creation (top-level comments and replies) is rate limited per user. An over-limit create answers 429 with a Retry-After header.

File Share Comments

fileshare is a third {entity_type} on the comment surface, used by File Share recipients to read and post comments on a file inside a File Share. It shares the request/response shapes of the workspace/share List and Create endpoints above — the only differences are the fileshare discriminator and that the {node_id} segment is required (a File Share comment always targets a specific node, never the whole container).

Auth: Required. The caller must have access to the File Share (a signed-in recipient); anonymous callers are denied. Comments left here are the File Share recipient's own comments on the node.

Path Parameters

Request Example — list

curl -X GET "https://api.fast.io/current/comments/fileshare/adheih5r326qjiqvk4wfamvt4rqeh/23d4zvoprfmonyhy2wwjpoccqjaiz/" \
  -H "Authorization: Bearer {jwt_token}"

Request Example — create

curl -X POST "https://api.fast.io/current/comments/fileshare/adheih5r326qjiqvk4wfamvt4rqeh/23d4zvoprfmonyhy2wwjpoccqjaiz/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"body": "Received — thanks for sending this over."}'

The list and create responses use the same envelope and Comment Object schema as the entity-scoped endpoints above. A File Share comment carries the File Share's ID in scope_id; user_id is the recipient's account ID.

Notes

• File Share comments are visible read-only in the owning workspace's node thread (can_reply / can_edit / can_delete are false there); replies and edits happen through this File Share surface. See the List Comments notes for the one-directional visibility rules.
• The invalid-entity_type error message for the whole comment surface is Entity type must be "workspace", "share", or "fileshare".

Error Responses

Update Comment by ID

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Updated: this looks great after the revision."
  }'

Response

The full updated comment object (same shape as Create or Update Comment above), with edited_at populated.

Error Responses

Notes

• Only the original author can edit; mentions are re-validated from the edited body and the comment's edited_at timestamp is populated.
• An edit can never move the comment: its entity, scope, and threading are immutable here.
• Server-managed properties keys (reactions, version, version_hash, edited_at, content_filtered, mentions, actor, pinned, reply_to) supplied in the request are ignored — they are written only by the server (actor is set from the credential that made the request).
• The text anchor (exact / prefix / suffix) cannot change after the comment is created; resending it unchanged is accepted.
• Only people the edit newly mentions are notified.

Get Comment Details

When the comment is a root (no parent_id), the response carries the Thread State Fields described under Comment Object above.

Auth: Required (JWT). Rate limited.

Query Parameters (root comments only)

Request Example

curl -X GET "https://api.fast.io/current/comments/abc123opaqueid/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "comment": {
    "id": "abc123opaqueid",
    "entity": "xyz789opaqueid",
    "user_id": "1234567890123456789",
    "actor": {
      "user_id": "1234567890123456789",
      "kind": "human",
      "agent_name": null,
      "name_source": null,
      "credential_type": "session",
      "verified": false
    },
    "parent_id": null,
    "body": "This looks great!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "scope_id": null,
    "linked_entity_type": null,
    "linked_entity_id": null,
    "external_author_email": null,
    "external_author_name": null,
    "external_author_token_id": null,
    "reference": null,
    "mentions": [],
    "reactions": [],
    "user_reaction": null,
    "version_hash": null,
    "version": 1,
    "edited_at": null,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC",
    "deleted": null,
    "can_edit": true,
    "can_delete": true,
    "can_reply": true,
    "attachment_count": 0,
    "attachments": []
  }
}

On a root comment, comment additionally carries the Thread State Fields above, plus replies (array, paged by replies_offset / replies_limit) and replies_total (int, the thread's total reply count). These three are omitted on a reply.

Error Responses

Delete Comment

Auth: Required (JWT). Rate limited.

Request Example

curl -X DELETE "https://api.fast.io/current/comments/abc123opaqueid/delete/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "message": "Comment deleted successfully",
  "comment": {
    "id": "abc123opaqueid",
    "entity": "xyz789opaqueid",
    "user_id": "1234567890123456789",
    "actor": {
      "user_id": "1234567890123456789",
      "kind": "human",
      "agent_name": null,
      "name_source": null,
      "credential_type": "session",
      "verified": false
    },
    "body": "This looks great!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "mentions": [],
    "reactions": [],
    "version": 1,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-16 08:00:00 UTC",
    "deleted": "2025-01-16 08:00:00 UTC",
    "can_edit": false,
    "can_delete": false,
    "can_reply": true
  },
  "skipped": []
}

skipped lists the ids of replies you can access that could not be deleted (normally empty). Each can be deleted by its own author or by a moderator; deleting the parent again does not retry them.

Access Levels

Error Responses

Bulk Delete Comments

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/bulk/delete/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"comment_ids": ["abc123opaqueid", "def456opaqueid", "ghi789opaqueid"]}'

Response

{
  "result": true,
  "success": true,
  "deleted_count": 3,
  "failed_count": 0,
  "total_count": 3,
  "results": {
    "abc123opaqueid": {"id": "abc123opaqueid", "success": true, "error": null},
    "def456opaqueid": {"id": "def456opaqueid", "success": true, "error": null},
    "ghi789opaqueid": {"id": "ghi789opaqueid", "success": true, "error": null}
  },
  "skipped": []
}

Response Fields

Per-Comment Error Messages

Request-Level Error Responses

Replies: like single delete, bulk delete also deletes the replies you can access. An id already deleted earlier in the same batch (as a reply, or listed twice) is reported as a success.

Add or Change Reaction

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/reactions/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'

Response

{
  "result": true,
  "reactions": {"👍": 3, "❤️": 1},
  "user_reaction": "👍"
}

Response Fields

Error Responses

Remove Reaction

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example — Remove specific emoji

curl -X DELETE "https://api.fast.io/current/comments/abc123opaqueid/reactions/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'

Request Example — Remove any reaction

curl -X DELETE "https://api.fast.io/current/comments/abc123opaqueid/reactions/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "result": true,
  "reactions": {"❤️": 1},
  "user_reaction": null
}

Response Fields

Error Responses

Notes: Removing a reaction that does not exist returns success (idempotent). A "removed" event is triggered only when a reaction was actually removed.

Unlink Comment

Auth: Required (JWT). Rate limited.

Authorization re-runs against the comment's own scope — the workspace, share, or File Share that owns it — not against whatever context you are calling from. On top of that, only the comment's author, or a workspace/share admin or owner (moderation; never on a File Share comment), may unlink it.

Request Body (JSON, optional)

Response

The updated comment, in the standard shape (see Comment Object), with its link cleared.

Error Responses

Notes: A comment-unlinked event fires only when the comment actually had a link to clear.

Thread State: Resolve, Reopen, Assign

A thread is a root comment (one with no parent_id) plus its replies. Thread state lives on the root — open or resolved, a single assignee, and state_version, a counter that increments on every change (see Thread State Fields under Comment Object above). Replies carry no thread state: sending a reply's ID to any of these three routes returns 400 comment_not_root.

All three routes:

• take a JSON body, the same encoding as POST /comments/...;
• return {"result": true, "comment": {...}}, the comment row with its thread fields;
• require that you can comment on the item.

Comments that belong to a File Share are read- and post-only. All three routes refuse them with 403 comment_thread_read_only.

Resolve

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body (optional)

Who may resolve: the thread's author, the current assignee, anyone who can edit the item, or a workspace or share admin.

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/resolve/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{"result": true, "comment": {...}}, the updated thread.

Idempotency: resolving an already-resolved thread returns it unchanged, with 200. resolved_by and resolved_at are not restamped, and no event fires.

Reopen

A “Resolve” undo is a reopen call with if_state_version set to the state_version that the resolve returned.

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/reopen/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"if_state_version": 3}'

Response

{"result": true, "comment": {...}}.

Assign

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body (exactly one form, plus an optional if_state_version)

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/assign/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"assignee_user_id": "1234567890123456789"}'

Response

{"result": true, "comment": {...}}.

Notes

• Calls are idempotent. Assigning the current assignee, or clearing a thread that has no assignee, returns the thread unchanged.
• An assignee who cannot see the item gets 400 assignee_no_access.
• A malformed body, an unknown connection, a connection that belongs to someone else, or one whose scopes do not reach this workspace or share gets 400 assignee_invalid.
• A service account cannot assign Ripley (a Ripley run is billed to a person): 400 assignee_invalid.
• unassign is the same call as assign with {"clear": true}.
• To find who can be assigned (or mentioned) on a given file, use GET /current/workspace/{workspace_id}/storage/{node_id}/principals/ (see Comment Principals in the Storage reference).

Concurrency (if_state_version)

if_state_version is optional on resolve, reopen and assign. When it is present and the thread has changed since you read it, the route returns 409 with error.params.reason = state_version_conflict and error.params.state_version set to the current value. Reload and retry.

If the thread is already in the state you asked for, the call succeeds unchanged even with a stale if_state_version — that makes a retry after a lost response safe.

Errors

Gate on HTTP status, then error.params.reason.

Thread Limits

Each file has a limit on its threads (top-level comments, and suggestion threads too). Replies are never counted.

• Free: 100 threads per file.
• Paid plans: 1,000.
• Top plans: unlimited.

When a new thread would exceed the limit, creating it (see Create or Update Comment above) fails with 409 comment_thread_limit_reached. If the limit cannot be checked, it fails with 503 comment_thread_limit_unavailable (retryable). See Thread Grouping under List Comments above for the limits block that reports usage against the cap.

Suggestions

A suggestion is a proposed edit to a workspace note: a comment thread with kind: "suggestion" whose root carries suggestion{}. The anchor (the root's reference exact / prefix / suffix) is the text it changes. Suggestions exist on workspace notes only.

Create a suggestion

The comment create body, plus:

A suggestion is never a reply (parent_id), never an edit (comment_id) and takes no attachments (target_ids / target_id): those are 400 with error.params.reason = suggestion_invalid, as is an invalid suggestion object, or a suggestion object sent without kind: "suggestion". A surface other than a workspace note is 400 suggestion_unsupported_surface. A suggestion counts against the file's thread limit like any root comment. The response comment is the root row with its thread fields and suggestion{}.

POST /current/comments/workspace/{workspace_id}/{note_id}/suggestions/bulk/ creates up to 50 in one request: {items: [{reference, suggestion, body?}]} returns {created: [...], failed: [{index, reason}]}.

Reading suggestions

Suggestion threads are hidden from comment lists, details, counts and search unless you opt in with include_suggestions=true (or kind=suggestion on a list). Opted in, each suggestion root row carries:

In counts, an open suggestion (pending or accepting) counts in open and pending_suggestions; a decided one counts in done. status=open / status=resolved judge a suggestion by its own state. Workspace search (GET /current/workspace/{workspace_id}/search/) returns suggestion comments only with include_suggestions=true.

Edit, withdraw, reject, undo

• Edit — POST /current/comments/{comment_id}/update/ with suggestion: {op?, replacement?} (merged over the stored payload) and/or body (the rationale; omit it to keep the stored one). Author only, and only while the suggestion is pending: while an accept holds it, once it is decided, or once a headless accept was sent, the edit is 409 suggestion_not_pending. if_state_version pins the suggestion's state_version (409 state_version_conflict) on every edit, a rationale-only one too; every edit advances it. The comment and the suggestion change together or not at all. A body that is not a string is 400.
• Withdraw — POST /current/comments/{comment_id}/suggestion/withdraw/: the author takes it back.
• Reject — POST /current/comments/{comment_id}/suggestion/reject/: anyone who may resolve the thread.
• Undo — POST /current/comments/{comment_id}/suggestion/undo/: the decider returns a rejected or withdrawn suggestion to pending. Undoing an accept needs the editor (409 suggestion_needs_editor).

withdraw, reject and undo accept if_state_version; reject and withdraw also accept confirm_unsettled (boolean, default false; see below — any other type is 400 suggestion_invalid). Replies, reactions and mentions on a suggestion thread work like on any comment.

An unsettled headless accept blocks reject and withdraw. Once a headless accept has sent the edit to the note and no applied answer has been recorded, the suggestion is unsettled: the edit may already be in the note. This lasts after the accept's hold expires and the suggestion reads pending again — expiry alone never settles it. While it is unsettled, reject and withdraw answer 409 with error.params.reason = suggestion_apply_unknown, retryable: true, and retry_after while a hold remains. Two ways forward: accept again in headless mode (the same idempotency_key while the hold lasts, any key once it has expired) — only an applied answer settles the suggestion, as accepted; or check the note yourself and, if you still want to decide, send the reject or withdraw again with "confirm_unsettled": true. That decides as usual even though the edit may be in the note (the response carries "unsettled_acknowledged": true); remove the edit from the note yourself if it landed. confirm_unsettled never overrides a live hold: while one remains the reject or withdraw still answers 409 suggestion_not_pending with retry_after, so wait for it to end. An editor-mode accept that confirms also settles the suggestion (as accepted). No other accept answer (suggestion_stale, suggestion_apply_unknown, ...) proves the earlier send was not applied, so none settles it.

Delete

Deleting the root ends the suggestion: it can no longer be decided or edited, and it leaves lists and search like any deleted comment. A read that includes deleted comments (include_deleted, details/) can still show it, with can_accept / can_reject false. Deleting the workspace removes its suggestions.

Accept a Suggestion

Accept a suggested edit on a workspace note. {comment_id} is the suggestion's thread (root comment). Auth required. You need edit rights on the note; agent platform tokens cannot accept.

Request Body (JSON)

One accept at a time. An accept holds the suggestion for a 90-second lease (renewed while a headless accept runs) plus a 25-second grace, so up to 116 seconds after its last renewal; retry_after always says when the hold ends. While it is held, any OTHER accept attempt — including your own with a different idempotency_key, with none, or in the other mode — gets 409 with error.params.reason = suggestion_not_pending, retryable: true and retry_after. Only a retry of the same attempt (same idempotency_key, or the editor's own accept_token) picks the held accept back up.

Headless Outcomes

Every successful accept response carries comment — the suggestion's root row with its suggestion{} (the leased replacement included) — in editor and headless mode, on a first accept, on a resume of the same attempt and on a repeat of an accept that already applied.

Editor mode returns {comment, state: "accepting", accept_token, lease_expires, lease_seconds, apply_generation}. Apply the edit in your editor, save, then call POST /current/comments/{comment_id}/suggestion/confirm/ with {accept_token, applied_version_id} (the saved version of this note), or POST /current/comments/{comment_id}/suggestion/release/ with {accept_token} to give it back. A headless accept whose edit was sent cannot be released by anyone: release answers 503 suggestion_apply_unknown with retry_after, and the hold ends when it is confirmed or expires.

Suggestion Decisions: Withdraw, Reject, Undo, Confirm, Release

These routes act on a suggestion thread on a workspace note. {comment_id} is the suggestion's root comment. Every route takes a JSON object body (an empty body is {}) and answers {"result": true, "comment": {...}, "state": "..."}: comment is the root row with its thread fields and suggestion{}, and state is the suggestion's state after the call. Each route first checks that you can comment on the note, so the common errors at the end of each table apply to every one.

Withdraw a Suggestion

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Who may call it: The suggestion's author only (the author of its root comment). You must be able to comment on the note.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/suggestion/withdraw/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{"result": true, "comment": {...}, "state": "withdrawn"} — comment is the root row with its thread fields and suggestion{}. Adds "unsettled_acknowledged": true when confirm_unsettled decided over an unsettled headless accept.

• Idempotent: withdrawing again returns the suggestion unchanged (200), and no event fires.
• Event: comment_suggestion_decided (decision withdrawn) on a real change.

Errors

Gate on HTTP status, then error.params.reason.

Reject a Suggestion

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Who may call it: Anyone who may resolve the thread: its author, the current assignee, anyone who can edit the note, or a workspace admin. You must be able to comment on the note.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/suggestion/reject/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"if_state_version": 2}'

Response

{"result": true, "comment": {...}, "state": "rejected"} — comment is the root row with its thread fields and suggestion{}. Adds "unsettled_acknowledged": true when confirm_unsettled decided over an unsettled headless accept.

• Idempotent: a repeat by the same caller returns the suggestion unchanged (200), and no event fires. A suggestion someone else already decided is 409 suggestion_not_pending.
• Event: comment_suggestion_decided (decision rejected) on a real change.

Errors

Gate on HTTP status, then error.params.reason.

Undo a Suggestion Decision

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Who may call it: The user who decided it only. Undoing an accepted suggestion also needs edit rights on the note.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/suggestion/undo/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"mode": "editor", "reverted_version_id": "{version_id}"}'

Response

{"result": true, "comment": {...}, "state": "pending"}.

• Rejected or withdrawn: metadata only, in either mode, with no body needed.
• Accepted: Fastio never reverts the text. Apply the inverse edit in your editor, save, then send that save's version as reverted_version_id. Undoing an accept starts a new accept attempt: an accept key used before the undo is a new attempt afterwards.
• Idempotent: a suggestion that is already pending is returned unchanged.
• Event: comment_suggestion_reverted on a real change.

Errors

Gate on HTTP status, then error.params.reason.

Confirm an Editor Accept

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Who may call it: The holder of the editor accept (its accept_token), with edit rights on the note. Fastio's built-in agent cannot confirm.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/suggestion/confirm/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"accept_token": "{accept_token}", "applied_version_id": "{version_id}"}'

Response

{"result": true, "comment": {...}, "state": "accepted", "applied_version_id": "{version_id}"}.

• Replay-safe: the same accept_token and applied_version_id on an accepted suggestion return it unchanged, and no second event fires.
• A lapsed hold still confirms while nobody else has taken the suggestion (it still holds your token): the edit is in the note.
• Event: comment_suggestion_decided (decision accepted) on a real change.

Errors

Gate on HTTP status, then error.params.reason.

Release an Editor Accept

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Who may call it: The holder of the accept (its accept_token). You must be able to comment on the note.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/suggestion/release/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"accept_token": "{accept_token}"}'

Response

{"result": true, "comment": {...}, "state": "pending"}.

• Idempotent: a suggestion that is already pending is returned unchanged.
• A headless accept whose edit was sent is never released, by anyone: it ends when it is confirmed or its hold expires.
• Event: none.

Errors

Gate on HTTP status, then error.params.reason.

Comment Email Notifications

Fastio emails people about comment activity that concerns them. Each kind of email is separate:

• Mention — someone mentions you in a comment.
• Assignment — a comment thread is assigned to you, or to one of your agents (“Assigned to you · via Claude” emails you).
• Reply — someone replies in a thread you started or that is assigned to you.
• Suggestion decided — a suggestion you made is accepted or rejected.

Resolving or reopening a thread never sends email. Agents and service accounts are never emailed; work assigned to your agent is emailed to you. You are not emailed about your own actions, except a reply the Ripley agent posts on your behalf. Before an email is sent, Fastio checks again that the comment still exists, that you can still see it, and that your preference allows it. Email links open the file with the comment selected (?comment={comment_id}).

Preference Modes

A preference is global, with an optional override per file. The override wins; without one the file uses your global mode; without a global mode the default applies.

GET /current/comments/preferences/

Your global comment email mode.

{ "result": true, "mode": "mine_and_mentions" }

POST /current/comments/preferences/

Set your global mode. JSON body:

{ "mode": "all" }

mode is one of all, mine_and_mentions, none, or inherit (clears your global setting so the default applies). The response is the same as GET.

GET /current/comments/preferences/{node_id}/

Your mode for one file. You must be able to view the file.

{ "result": true, "mode": "none", "inherited": false }

inherited is true when the file has no override and mode comes from your global setting (or the default).

POST /current/comments/preferences/{node_id}/

Set or clear the override for one file. JSON body { "mode": "all" | "mine_and_mentions" | "none" | "inherit" }; inherit removes the override. The response is the same as GET.

Errors (error.params.reason):

• notification_preference_invalid (400): mode is missing or not one of the values above.
• notification_preferences_unavailable (503, retryable: true): try again.
• notification_preferences_forbidden (403): service accounts have no comment email preferences.
• Invalid file id (400), a file you cannot view (403) or that does not exist (404).

OAuth connections restricted per place need the comment tool on the file's workspace or share to POST a per-file preference; reading it needs read.

Comment Attachments

Attach arbitrary platform objects to a comment to give it context — a file or folder, a sign envelope, a share, a File Share, or a workspace. An attachment is a lightweight reference: it records what is attached, not a copy of it.

• A comment can hold up to 25 attachments.
• Attaching is idempotent — re-attaching an object already attached is a no-op and does not count against the cap.
• Attaching does not verify the target exists or is accessible; display names are resolved (and access-gated) on read.
• Attaching/detaching is author-only — only the comment's author can add or remove attachments (a moderator who can delete a comment cannot mutate its attachments).
• A soft-deleted comment returns 404.

Attachment Object (hydrated)

Every attachment returned by the API is hydrated and access-gated to the caller: an object the caller cannot see (or that no longer exists) is returned with available: false and display_name: null rather than leaking its name. Render defensively: when available is false, never show a name — show a generic placeholder, and never assume display_name is non-null.

List Comment Attachments

Auth: Required (JWT). Rate limited.

Response

{
  "result": true,
  "comment_id": "abc123opaqueid",
  "attachments": [
    {
      "target_id": "23d4zvoprfmonyhy2wwjpoccqjaiz",
      "target_type": "node",
      "kind": "node",
      "display_name": "spec.pdf",
      "available": true
    },
    {
      "target_id": "9876543210987654321",
      "target_type": "share",
      "kind": "share",
      "display_name": null,
      "available": false
    }
  ],
  "count": 2
}

Attach Objects to a Comment

Auth: Required (JWT). Rate limited. Content-Type: application/json.

Request Body

A request whose new attachments would push the comment over the 25-attachment cap is rejected before anything is written.

Request Example — single

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/attachments/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "23d4zvoprfmonyhy2wwjpoccqjaiz"}'

Request Example — bulk

curl -X POST "https://api.fast.io/current/comments/abc123opaqueid/attachments/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_ids": ["23d4zvoprfmonyhy2wwjpoccqjaiz", "9876543210987654321"]}'

Response

{
  "result": true,
  "comment_id": "abc123opaqueid",
  "attached": 1,
  "attachments": [
    {
      "target_id": "23d4zvoprfmonyhy2wwjpoccqjaiz",
      "target_type": "node",
      "kind": "node",
      "display_name": "spec.pdf",
      "available": true
    }
  ],
  "count": 1
}

Response Fields

Error Responses

Detach an Object from a Comment

Auth: Required (JWT). Rate limited. Content-Type: application/json.

Request Body

Response

{
  "result": true,
  "comment_id": "abc123opaqueid",
  "removed": true,
  "attachments": [],
  "count": 0
}

Response Fields

Attaching at comment-create time (inline)

You can attach objects when creating a comment by including target_id or target_ids in the comment-create body (see Create or Update Comment). Inline attachments apply only to a new comment — they are ignored on an update, and the comment plus its attachments are written together so the comment never appears without them. An invalid target or one that would exceed the cap rejects the whole create.

attachment_count is returned on every comment list row and on the comment detail response. The hydrated attachments array is returned only on the comment detail response (GET /current/comments/{comment_id}/details/). All counts are computed live on each read.

Threading

Comments support single-level threading only.

• Set parent_id in the request body to the opaque ID of the comment you are replying to. This is distinct from {parent_id} in the URL path, which identifies the workspace or share container.
• Replies to a top-level comment appear as children of that comment.
• Replies to a reply are auto-flattened — they become siblings of the original reply (children of the same top-level parent). The API does not support nested threading beyond one level.

Comment A (top-level)
├── Comment B (reply to A)
├── Comment C (reply to B → auto-flattened to reply to A)
└── Comment D (reply to A)

Mentions

Use mention markup in the body field to tag other users:

@[user:USER_ID:Display Name]

To summon Ripley into a workspace file's thread, use the token @[agent:ripley] (or assign the thread with {"assignee": "ripley"}); see the AI reference.

Character limit details

• The full mention tag markup (e.g., @[user:1234567890123456789:Jane Smith]) counts toward the 8192-character body limit. Both the 8192 raw cap and the 500 display cap count UTF-8 characters, not bytes — a CJK or emoji character costs exactly one, the same as an ASCII one.
• Display text (excluding all mention markup) is separately limited to 500 characters. A mention inside markdown code is not discounted — it counts in full (see Mentions inside code, below).
• Mentioned users are validated against entity membership at save time. Invalid mentions (users without access to the entity) are dropped silently.
• A workspace service account is never a mention recipient: no mention or reply notification is ever sent to it.

Example body with mentions

Hey @[user:1234567890123456789:Jane Smith] and @[user:9876543210987654321:Bob Jones], please review this file.

Mentions inside code

This is a live behaviour change. A mention that sits inside markdown code — a fenced block, or a single-line inline backtick span — is treated as text the author is showing, not as a hail:

• It does not notify the mentioned user.
• It counts in full against the 500-character display cap, instead of being discounted as mention markup.

Two consequences to plan for: someone who is notified today by a fenced mention stops being notified, and a long body that hid mention markup inside a fence may now be rejected by the display cap that previously discounted it.

What counts as code — deliberately narrow, and matched per line:

• A fenced block opened by a run of three or more backticks or three or more tildes, indented at most 3 spaces, closing on a run of the same character at least as long, alone on its line. An unclosed fence runs to the end of the body.
• A single-line inline backtick span — a run of N backticks closing on a run of exactly N backticks on the same line.

What is NOT recognised as code. A mention in any of these still notifies, and is still discounted from the display cap, exactly as before:

• A fence carrying a blockquote or other container prefix (a > marker ahead of the fence characters).
• A fence indented four or more spaces.
• Indented code blocks generally — four spaces or a tab, with no fence markers at all.
• A backtick span whose opening and closing runs sit on different lines.

The bias is deliberate. Failing to recognise code is safe — it is the behaviour that was already live. Inventing code where there is none would silently drop a real person's notification. When in doubt, it is not code.

Reference Anchoring

Comments can be anchored to a specific position within a file using the reference object. The type field is required and selects which additional fields are valid.

type values

Anchor fields

Any unrecognized type is rejected with "Invalid reference type: {value}", and any key not listed above with "Unknown reference key: {key}" (error.params.reason = anchor_invalid). The whole reference object, JSON-encoded, may not exceed 2048 bytes (non-ASCII characters count as their 6-byte escaped form); a larger one is rejected with error.params.reason = anchor_too_large.

The text anchor is immutable. Once a comment is created, its exact, prefix and suffix cannot be changed, added or removed by an edit — either edit route rejects that with "The anchor of an existing comment cannot be changed" (error.params.reason = anchor_invalid). Resending the same values, or omitting reference, is fine; the offsets may change.

Example — Video timestamp

{
  "body": "The transition at this point needs work.",
  "reference": {"type": "video", "timestamp": 42.5}
}

Example — Document page

{
  "body": "Typo in the second paragraph.",
  "reference": {"type": "document", "page": 7}
}

Example — Image region

{
  "body": "This area needs higher contrast.",
  "reference": {"type": "image", "region": {"x1": 20, "y1": 15, "x2": 55, "y2": 40}}
}

Example — Document text snippet

{
  "body": "This sentence should be rephrased.",
  "reference": {"type": "document", "text_snippet": "The quick brown fox jumps over the lazy dog."}
}

Content Filtering

Comment bodies are stored as sent — the filtering stages below are currently inactive:

• HTML handling: HTML is not stripped or escaped — the body is trimmed of leading and trailing whitespace and then stored unmodified, so code and markup-shaped text survive intact. Escape or sanitize the body in your own client before rendering it as HTML.
• Spam detection: No spam detection is applied today. The spam-rejection response (406 error) remains part of this endpoint's documented contract and may become active again, so clients should continue to handle it.
• Profanity/PII filtering: No profanity or PII filtering is applied today; the returned body matches what was stored.