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. Task comments (see Task Comments below) are private to their task and are excluded from comment search.

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:

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.

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 or edited 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",
      "parent_id": null,
      "body": "This looks great!",
      "profile_type": "workspace",
      "profile_id": "1234567890123456789",
      "reference": null,
      "mentions": [],
      "reactions": {"👍": 2, "❤️": 1},
      "user_reaction": "👍",
      "version": 1,
      "can_edit": true,
      "can_delete": true,
      "can_reply": true,
      "created": "2025-01-15 10:30:00 UTC",
      "updated": "2025-01-15 10:30:00 UTC"
    }
  ],
  "count": 1,
  "allowed": true,
  "remaining": 95,
  "total": 5,
  "limit": 50,
  "offset": 0
}

Response Fields

Access Levels

Error Responses

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": "page", "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",
    "parent_id": null,
    "body": "Great work on this document!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "reference": null,
    "reactions": {},
    "user_reaction": null,
    "version": 1,
    "can_edit": true,
    "can_delete": true,
    "can_reply": true,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC"
  }
}

Response Fields

Access Levels

Error Responses

Notes

• Content filtering: Bodies are sanitized (HTML stripped) and filtered for profanity, spam, and PII. Spam is blocked; other detected categories result in the body being modified before storage.
• Mentions: Mentioned users are parsed and validated against entity membership before the comment is saved.
• Plan limits: Number of comments per entity is limited by the organization's plan.
• Updating: Only the original author can edit. Editing populates the top-level edited_at timestamp on the returned comment.

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, threading, and task/workflow links are immutable here.
• For a task comment, access additionally requires task access (Workflow feature enabled, not a share guest, task not trashed) — the same gating as the task's comment thread.

Get Comment Details

Auth: Required (JWT). Rate limited.

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",
    "parent_id": null,
    "body": "This looks great!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "reference": null,
    "reactions": {},
    "user_reaction": null,
    "version": 1,
    "can_edit": true,
    "can_delete": true,
    "can_reply": true,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC",
    "deleted": null
  }
}

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",
    "parent_id": null,
    "body": "This looks great!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "reference": null,
    "reactions": {},
    "user_reaction": null,
    "version": 1,
    "can_edit": false,
    "can_delete": false,
    "can_reply": false,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-16 08:00:00 UTC",
    "deleted": "2025-01-16 08:00:00 UTC"
  }
}

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}
  }
}

Response Fields

Per-Comment Error Messages

Request-Level Error Responses

Important: Unlike single delete, bulk delete does not recursively delete replies.

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.

Link Comment to Workflow Entity

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example

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

Response

{
  "result": true,
  "comment": {
    "id": "abc123opaqueid",
    "entity": "xyz789opaqueid",
    "user_id": "1234567890123456789",
    "parent_id": null,
    "body": "This looks great!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "linked_entity_type": "task",
    "linked_entity_id": "task789opaqueid",
    "reference": null,
    "reactions": {},
    "user_reaction": null,
    "version": 1,
    "can_edit": true,
    "can_delete": true,
    "can_reply": true,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC"
  }
}

Response Fields

Error Responses

Unlink Comment from Workflow Entity

Auth: Required (JWT). Rate limited.

Content-Type: application/json

Request Body

Request Example

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

Request Example — Without entity_id

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

Response

{
  "result": true,
  "comment": {
    "id": "abc123opaqueid",
    "entity": "xyz789opaqueid",
    "user_id": "1234567890123456789",
    "parent_id": null,
    "body": "This looks great!",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "reference": null,
    "reactions": {},
    "user_reaction": null,
    "version": 1,
    "can_edit": true,
    "can_delete": true,
    "can_reply": true,
    "created": "2025-01-15 10:30:00 UTC",
    "updated": "2025-01-15 10:30:00 UTC"
  }
}

Response Fields

Error Responses

Get Linked Comments

Auth: Required (JWT). Rate limited.

Path Parameters

Query Parameters

Request Example

curl -X GET "https://api.fast.io/current/comments/linked/task/task789opaqueid/?limit=25&offset=0" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "comments": [
    {
      "id": "abc123opaqueid",
      "entity": "xyz789opaqueid",
      "user_id": "1234567890123456789",
      "parent_id": null,
      "body": "This looks great!",
      "profile_type": "workspace",
      "profile_id": "1234567890123456789",
      "linked_entity_type": "task",
      "linked_entity_id": "task789opaqueid",
      "reference": null,
      "reactions": {"👍": 2},
      "user_reaction": "👍",
      "version": 1,
      "can_edit": true,
      "can_delete": true,
      "can_reply": true,
      "created": "2025-01-15 10:30:00 UTC",
      "updated": "2025-01-15 10:30:00 UTC"
    }
  ],
  "count": 1,
  "entity_type": "task",
  "entity_id": "task789opaqueid",
  "limit": 25,
  "offset": 0
}

Response Fields

Error Responses

Comment Attachments

Attach arbitrary platform objects to a comment to give it context — a file or folder, a workflow, a sign envelope, a share, a File Share, a workspace, or a task. 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).
• Attachments are not supported on workflow-review comments (a 400 is returned), and 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.

List Comment Attachments

Auth: Required (JWT). Rate limited.

Response

{
  "result": true,
  "comment_id": "abc123opaqueid",
  "attachments": [
    {
      "target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5",
      "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": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5"}'

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": ["n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5", "9876543210987654321"]}'

Response

{
  "result": true,
  "comment_id": "abc123opaqueid",
  "attached": 1,
  "attachments": [
    {
      "target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5",
      "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.

Task Comments

Tasks have their own dedicated comment thread, surfaced under the task path rather than the generic comment paths. A task comment is a normal comment object (same schema, threading, mentions, reactions, and reference anchoring as above) — only the list/create surface differs.

Privacy. Task comments are private to their task: they are not returned by the general comment listing (GET /current/comments/{entity_type}/{parent_id}/) and not included in comment search. They surface only through the task comment path above.

Reactions, edit, and delete of a task comment use the existing comment-by-id endpoints in this reference — POST /current/comments/{comment_id}/reactions/, DELETE /current/comments/{comment_id}/reactions/, POST /current/comments/{comment_id}/update/ (edit), and DELETE /current/comments/{comment_id}/delete/.

The task create endpoint never edits. A POST to the task comments path whose body includes a comment_id field is rejected with 400 Invalid Input (it does not create a duplicate); trailing path segments after …/comments/ return 404. Edits go through POST /current/comments/{comment_id}/update/ only.

Access. The task's workflow feature must be enabled on the owning workspace or share. On shares, member or admin access is required — guests are blocked. A soft-deleted task returns 404. Mentions are validated against the task's workspace/share membership.

The full request/response shapes for the task comment list and create endpoints are documented in the Workflow (Task Management) reference under Task Comments.

Threading

Comments support single-level threading only.

• Set parent_id to the comment you are replying to.
• 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]

Character limit details

• The full mention tag markup (e.g., @[user:1234567890123456789:Jane Smith]) counts toward the 8192-character body limit.
• Display text (excluding all mention markup) is separately limited to 500 characters.
• Mentioned users are validated against entity membership at save time. Invalid mentions (users without access to the entity) are dropped silently.

Example body with mentions

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

Reference Anchoring

Comments can be anchored to specific positions within a file using the reference object.

Reference object fields

Example — Video timestamp

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

Example — Document page

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

Example — Image region

{
  "body": "This area needs higher contrast.",
  "reference": {"type": "region", "region": {"x": 120, "y": 80, "width": 200, "height": 150}}
}

Example — Text snippet

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

Content Filtering

Comment bodies undergo automatic filtering:

• HTML sanitization: All HTML tags are stripped.
• Spam detection: Comments identified as spam are blocked entirely (400 error).
• Profanity/PII filtering: Detected content is modified in-place before storage; the returned body reflects the post-filter content.