Post Comment

Create a new comment on a file. Comments can be pinned to specific locations on the canvas or left as general file-level comments.

POST https://api.figma.com/v1/files/:file_key/comments

Authentication

Requires a valid access token with file_comments:write scope. Pass via X-Figma-Token header (personal access token) or Authorization: Bearer header (OAuth).

Workflow

Get your file key

Find the file key from the Figma URL. For example, in figma.com/file/ABC123/My-File, the file key is ABC123.

Build your comment payload

Construct the request body with the comment message. Optionally pin the comment to a canvas location using client_meta, or reply to an existing comment using comment_id.

Send the request

POST the payload to the comments endpoint with your authentication header. The response returns the created comment with its assigned ID.

Parameters

The key of the file to comment on.

Request Body

Field	Type	Required	Description
`message`	`string`	Yes	The comment text. Supports basic formatting.
`client_meta`	`object`	No	Pin location on the canvas. See below.
`comment_id`	`string`	No	Parent comment ID to create a threaded reply.

Show client_meta object

Use client_meta to pin the comment to a specific location on a canvas node.

| Field | Type | Description | |-------|------|-------------| | x | number | X coordinate on the canvas | | y | number | Y coordinate on the canvas | | node_id | string | The node ID the comment is anchored to |

Example Request

curl -X POST "https://api.figma.com/v1/files/YOUR_FILE_KEY/comments" \
  -H "X-Figma-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "This looks great! Can we bump the font size?",
    "client_meta": {
      "x": 100,
      "y": 200,
      "node_id": "1:23"
    }
  }'

To reply to an existing comment thread, include the comment_id field with the ID of the parent comment. Omit client_meta when replying — the reply inherits the parent’s position.

Response

{
  "id": "789",
  "message": "This looks great! Can we bump the font size?",
  "created_at": "2024-01-15T10:30:00Z",
  "user": {
    "id": "456",
    "handle": "developer"
  }
}

Response Fields

Field	Type	Description
`id`	`string`	The unique comment ID
`message`	`string`	The comment text
`created_at`	`string`	ISO 8601 timestamp of when the comment was created
`user`	`object`	The user who posted the comment
`user.id`	`string`	The user’s Figma ID
`user.handle`	`string`	The user’s display name