Comments

Overview

Comments are visual annotations pinned to specific positions on folio canvases. They support collaborative review workflows. Reading comments does not require authentication; writing requires auth context (or is fully public in OSS mode).

Each comment is tied to a specific version and file within the folio.

Comment Object

{
  "id": "c_1718400000000",
  "author": "jane@example.com",
  "text": "The header needs more contrast",
  "createdAt": "2025-06-20T14:30:00.000Z",
  "versionId": "v1",
  "filename": "index.html",
  "resolved": false,
  "x": 50,
  "y": 5,
  "selector": "#hero-section > h1",
  "elementHtml": "<h1 class=\"text-4xl\">Welcome</h1>"
}

Field	Type	Description
id	string	Unique comment ID (format: c_<timestamp>)
author	string	Email or display name of the commenter
text	string	Comment body text
createdAt	string	ISO 8601 timestamp
versionId	string	Version this comment applies to
filename	string	File this comment targets
resolved	boolean	Whether the comment has been resolved
x	number	Horizontal position on canvas (percentage, 0-100)
y	number	Vertical position on canvas (percentage, 0-100)
selector	string	CSS selector of the targeted DOM element
elementHtml	string	HTML of the targeted element at comment time

List Comments

GET /api/files/{id}/comments

Returns all comments for a folio. No authentication required (public).

Example Request:

curl https://livefolio.cloud/api/files/a1b2c3d/comments

Response: Array of comment objects.

Add a Comment

POST /api/files/{id}/comments
Content-Type: application/json

Creates a new pinned comment on the folio.

Request Body:

Field	Type	Required	Description
text	string	Yes	Comment body text
versionId	string	Yes	Version ID this comment targets
filename	string	Yes	File path this comment targets
author	string	No	Display name (defaults to auth email or "Guest")
x	number	No	Horizontal position (percentage)
y	number	No	Vertical position (percentage)
selector	string	No	CSS selector of the targeted element
elementHtml	string	No	HTML snippet of the targeted element

Example Request:

curl -X POST https://livefolio.cloud/api/files/a1b2c3d/comments \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The header needs more contrast against the background",
    "versionId": "v1",
    "filename": "index.html",
    "x": 50,
    "y": 5,
    "selector": "#hero-section > h1",
    "elementHtml": "<h1 class=\"text-4xl\">Welcome</h1>",
    "author": "Jane Reviewer"
  }'

Response:

{
  "success": true,
  "comment": {
    "id": "c_1718400000000",
    "author": "Jane Reviewer",
    "text": "The header needs more contrast against the background",
    "createdAt": "2025-06-20T14:30:00.000Z",
    "versionId": "v1",
    "filename": "index.html",
    "resolved": false,
    "x": 50,
    "y": 5,
    "selector": "#hero-section > h1",
    "elementHtml": "<h1 class=\"text-4xl\">Welcome</h1>"
  }
}

Error Responses:

Status	Error	Description
400	Missing comment parameters	Required fields missing (text, versionId, or filename)
403	Comments are disabled for this folio.	Folio has allowComments: false
404	Project not found	Folio does not exist

In Cloud mode with Slack or Discord integrations configured, new comments automatically trigger notifications to the connected channels.

Resolve a Comment

PUT /api/files/{id}/comments
Content-Type: application/json

Toggles the resolved state of a comment.

Request Body:

Field	Type	Required	Description
commentId	string	Yes	ID of the comment to update
resolved	boolean	Yes	New resolved state

Example Request:

curl -X PUT https://livefolio.cloud/api/files/a1b2c3d/comments \
  -H "Content-Type: application/json" \
  -d '{
    "commentId": "c_1718400000000",
    "resolved": true
  }'

Response:

{
  "success": true,
  "comment": {
    "id": "c_1718400000000",
    "resolved": true,
    ...
  }
}

Delete a Comment

DELETE /api/files/{id}/comments?commentId=c_1718400000000

Removes a comment permanently.

Query Parameters:

Parameter	Type	Required	Description
commentId	string	Yes	ID of the comment to delete

Example Request:

curl -X DELETE "https://livefolio.cloud/api/files/a1b2c3d/comments?commentId=c_1718400000000"

Response:

{
  "success": true
}

Error Responses:

Status	Error	Description
400	Missing commentId param	No commentId query parameter
404	Project not found	Folio does not exist