---
title: "Add a comment to a file"
method: POST
path: "/v1/files/{file_key}/comments"
tags: ["Comments"]
---

# Add a comment to a file

`POST /v1/files/{file_key}/comments`

Posts a new comment on the file.

## Path parameters

- `file_key` string, required

## Request body

- object
  - `message` string, required — The text contents of the comment to post.
  - `comment_id` string — The ID of the comment to reply to, if any. This must be a root comment. You cannot reply to other replies (a comment that has a parent_id).
  - `client_meta` union — The position where to place the comment.
    - Vector — A 2d vector.
      - `x` number, required — X coordinate of the vector.
      - `y` number, required — Y coordinate of the vector.
    - FrameOffset — Position of a comment relative to the frame to which it is attached.
      - `node_id` string, required — Unique id specifying the frame.
      - `node_offset` Vector, required — A 2d vector.
        - `x` number, required — X coordinate of the vector.
        - `y` number, required — Y coordinate of the vector.
    - Region — Position of a region comment on the canvas.
      - `x` number, required — X coordinate of the position.
      - `y` number, required — Y coordinate of the position.
      - `region_height` number, required — The height of the comment region. Must be greater than 0.
      - `region_width` number, required — The width of the comment region. Must be greater than 0.
      - `comment_pin_corner` 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' — The corner of the comment region to pin to the node's corner as a string enum.
    - FrameOffsetRegion — Position of a region comment relative to the frame to which it is attached.
      - `node_id` string, required — Unique id specifying the frame.
      - `node_offset` Vector, required — A 2d vector.
        - `x` number, required — X coordinate of the vector.
        - `y` number, required — Y coordinate of the vector.
      - `region_height` number, required — The height of the comment region. Must be greater than 0.
      - `region_width` number, required — The width of the comment region. Must be greater than 0.
      - `comment_pin_corner` 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' — The corner of the comment region to pin to the node's corner as a string enum.

## Response `200`

Response from the POST /v1/files/{file_key}/comments endpoint.

- Comment — A comment or reply left by a user.
  - `id` string, required — Unique identifier for comment.
  - `client_meta` union, required — Positioning information of the comment. Includes information on the location of the comment pin, which is either the absolute coordinates on the canvas or a relative offset within a frame. If the comment is a region, it will also contain the region height, width, and position of the anchor in regards to the region.
    - Vector — A 2d vector.
      - `x` number, required — X coordinate of the vector.
      - `y` number, required — Y coordinate of the vector.
    - FrameOffset — Position of a comment relative to the frame to which it is attached.
      - `node_id` string, required — Unique id specifying the frame.
      - `node_offset` Vector, required — A 2d vector.
        - `x` number, required — X coordinate of the vector.
        - `y` number, required — Y coordinate of the vector.
    - Region — Position of a region comment on the canvas.
      - `x` number, required — X coordinate of the position.
      - `y` number, required — Y coordinate of the position.
      - `region_height` number, required — The height of the comment region. Must be greater than 0.
      - `region_width` number, required — The width of the comment region. Must be greater than 0.
      - `comment_pin_corner` 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' — The corner of the comment region to pin to the node's corner as a string enum.
    - FrameOffsetRegion — Position of a region comment relative to the frame to which it is attached.
      - `node_id` string, required — Unique id specifying the frame.
      - `node_offset` Vector, required — A 2d vector.
        - `x` number, required — X coordinate of the vector.
        - `y` number, required — Y coordinate of the vector.
      - `region_height` number, required — The height of the comment region. Must be greater than 0.
      - `region_width` number, required — The width of the comment region. Must be greater than 0.
      - `comment_pin_corner` 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' — The corner of the comment region to pin to the node's corner as a string enum.
  - `file_key` string, required — The file in which the comment lives
  - `parent_id` string — If present, the id of the comment to which this is the reply
  - `user` User, required — A description of a user.
    - `id` string, required — Unique stable id of the user.
    - `handle` string, required — Name of the user.
    - `img_url` string, required — URL link to the user's profile image.
  - `created_at` string, date-time, required — The UTC ISO 8601 time at which the comment was left
  - `resolved_at` string, date-time, nullable — If set, the UTC ISO 8601 time the comment was resolved
  - `message` string, required — The content of the comment
  - `order_id` string, nullable, required — Only set for top level comments. The number displayed with the comment in the UI
  - `reactions` Reaction[], required — An array of reactions to the comment
    - `user` User, required — A description of a user.
      - `id` string, required — Unique stable id of the user.
      - `handle` string, required — Name of the user.
      - `img_url` string, required — URL link to the user's profile image.
    - `emoji` string, required — The emoji type of reaction as shortcode (e.g. `:heart:`, `:+1::skin-tone-2:`). The list of accepted emoji shortcodes can be found in [this file](https://raw.githubusercontent.com/missive/emoji-mart/main/packages/emoji-mart-data/sets/14/native.json) under the top-level emojis and aliases fields, with optional skin tone modifiers when applicable.
    - `created_at` string, date-time, required — The UTC ISO 8601 time at which the reaction was left.

## Other responses

- `400` — Bad request. Parameters are invalid or malformed. Please check the input formats. This error can also happen if the requested resources are too large to complete the request, which results in a timeout. Please reduce the number and size of objects requested.
- `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
- `404` — The requested file or resource was not found.
- `429` — In some cases API requests may be throttled or rate limited. Please wait a while before attempting the request again (typically a minute).
- `500` — An internal server error occurred.

---

[API](https://skmtc.net/thirdstrandstudio/apis/figma-api.md) · [All operations](https://skmtc.net/thirdstrandstudio/apis/figma-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thirdstrandstudio/figma-api/versions/48f84f49653a/schema)