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:

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 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": "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",
    "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.

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/1234567890123456789/n1o2p3q4r5s6t7u8v9w0x1/" \
  -H "Authorization: Bearer {jwt_token}"

Request Example — create

curl -X POST "https://api.fast.io/current/comments/fileshare/1234567890123456789/n1o2p3q4r5s6t7u8v9w0x1/" \
  -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, and — for an externally-authored comment — the external_author_* fields identify the author while user_id is null.

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.

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.

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.

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.

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

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 undergo automatic filtering:

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