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 Fast.io endpoints which use application/x-www-form-urlencoded.

Endpoint Summary

Path Parameters

Comments are scoped to an entity (workspace or share) and optionally to a specific node (file or folder).

Comment Object

Every comment returned by the API has this structure:

List Comments

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": "yes",
  "response": {
    "comments": [
      {
        "id": "abc123opaqueid",
        "entity_id": "xyz789opaqueid",
        "profile_id": "1234567890123456789",
        "parent_id": null,
        "body": "This looks great!",
        "properties": {},
        "reference": null,
        "reactions": {"👍": 2, "❤️": 1},
        "user_reaction": "👍",
        "created": "2025-01-15T10:30:00+00:00",
        "updated": "2025-01-15T10:30:00+00:00",
        "deleted": null
      }
    ],
    "count": 1,
    "allowed": true,
    "remaining": 95,
    "total": 5,
    "limit": 50,
    "offset": 0
  },
  "current_api_version": "1.0"
}

Response Fields

Access Levels

Error Responses

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": "yes",
  "response": {
    "comment": {
      "id": "abc123opaqueid",
      "entity_id": "xyz789opaqueid",
      "profile_id": "1234567890123456789",
      "parent_id": null,
      "body": "Great work on this document!",
      "properties": {},
      "reference": null,
      "reactions": {},
      "user_reaction": null,
      "created": "2025-01-15T10:30:00+00:00",
      "updated": "2025-01-15T10:30:00+00:00",
      "deleted": null
    }
  },
  "current_api_version": "1.0"
}

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 filtered content is modified and content_filtered is set in properties.
• Mentions: Mentioned users are parsed and validated against entity membership. Valid mention profile IDs are stored in properties.mentions.
• Plan limits: Number of comments per entity is limited by the organization's plan.
• Updating: Only the original author can edit. Editing sets edited_at in properties.

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": "yes",
  "response": {
    "comment": {
      "id": "abc123opaqueid",
      "entity_id": "xyz789opaqueid",
      "profile_id": "1234567890123456789",
      "parent_id": null,
      "body": "This looks great!",
      "properties": {},
      "reference": null,
      "reactions": {},
      "user_reaction": null,
      "created": "2025-01-15T10:30:00+00:00",
      "updated": "2025-01-15T10:30:00+00:00",
      "deleted": null
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "message": "Comment deleted successfully",
    "comment": {
      "id": "abc123opaqueid",
      "entity_id": "xyz789opaqueid",
      "profile_id": "1234567890123456789",
      "parent_id": null,
      "body": "This looks great!",
      "properties": {},
      "reference": null,
      "reactions": {},
      "user_reaction": null,
      "created": "2025-01-15T10:30:00+00:00",
      "updated": "2025-01-15T10:30:00+00:00",
      "deleted": "2025-01-16T08:00:00+00:00"
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "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}
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "reactions": {"👍": 3, "❤️": 1},
    "user_reaction": "👍"
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "reactions": {"❤️": 1},
    "user_reaction": null
  },
  "current_api_version": "1.0"
}

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.

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. Valid mentions are stored in properties.mentions.

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 and properties.content_filtered is set to true.