Figma Comments API

openapi: 3.2.0
info:
  title: Figma Comments API
  termsOfService: https://www.figma.com/developer-terms/
  version: '1.0'
  description: 'Operations tagged Comments across 2 of this provider''s published API definitions: figma-openapi.yml, figma-rest-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.figma.com
tags:
- name: Comments
  description: Interact with file comments.
  externalDocs:
    description: Comment endpoints documentation
    url: https://developers.figma.com/docs/rest-api/comments-endpoints/
paths:
  /v1/files/{file_key}/comments:
    get:
      tags:
      - Comments
      summary: Get comments in a file
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - file_comments:read
        - files:read
      description: Gets a list of comments left on the file.
      operationId: getComments
      parameters:
      - name: file_key
        in: path
        description: File to get comments from. This can be a file key or branch key. Use `GET /v1/files/:key` with the `branch_data` query param to get the branch key.
        required: true
        schema:
          type: string
      - name: as_md
        in: query
        description: If enabled, will return comments as their markdown equivalents when applicable.
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/GetCommentsResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrMessage'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrMessage'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrMessage'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrMessage'
    post:
      tags:
      - Comments
      summary: Add a comment to a file
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - file_comments:write
      description: Posts a new comment on the file.
      operationId: postComment
      parameters:
      - name: file_key
        in: path
        description: File to add comments in. This can be a file key or branch key. Use `GET /v1/files/:key` with the `branch_data` query param to get the branch key.
        required: true
        schema:
          type: string
      requestBody:
        description: Comment to post.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The text contents of the comment to post.
                comment_id:
                  type: string
                  description: 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:
                  description: The position where to place the comment.
                  oneOf:
                  - $ref: '#/components/schemas/Vector'
                  - $ref: '#/components/schemas/FrameOffset'
                  - $ref: '#/components/schemas/Region'
                  - $ref: '#/components/schemas/FrameOffsetRegion'
              required:
              - message
      responses:
        '200':
          $ref: '#/components/responses/PostCommentResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrorBoolean'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrMessage'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrMessage'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrMessage'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrMessage'
    servers:
    - url: https://api.figma.com
  /v1/files/{file_key}/comments/{comment_id}:
    delete:
      tags:
      - Comments
      summary: Delete a comment
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - file_comments:write
      description: Deletes a specific comment. Only the person who made the comment is allowed to delete it.
      operationId: deleteComment
      parameters:
      - name: file_key
        in: path
        description: File to delete comment from. This can be a file key or branch key. Use `GET /v1/files/:key` with the `branch_data` query param to get the branch key.
        required: true
        schema:
          type: string
      - name: comment_id
        in: path
        description: Comment id of comment to delete
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/DeleteCommentResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrMessage'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrMessage'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrMessage'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrMessage'
    servers:
    - url: https://api.figma.com
  /v1/files/{file_key}/comments/{comment_id}/reactions:
    get:
      tags:
      - Comments
      summary: Figma Get Comment Reactions
      operationId: getCommentReactions
      description: Gets a paginated list of reactions for a comment.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: comment_id
        in: path
        description: The ID of the comment.
        required: true
        schema:
          type: string
        example: '500123'
      - name: cursor
        in: query
        description: Cursor for paginated results.
        required: false
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully retrieved reactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReactionsResponse'
              examples:
                Getcommentreactions200Example:
                  summary: Default getCommentReactions 200 response
                  x-microcks-default: true
                  value:
                    reactions:
                    - emoji: example_value
                      created_at: '2026-01-15T10:30:00Z'
                    pagination:
                      cursor: example_value
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Comments
      summary: Figma Post Comment Reaction
      operationId: postCommentReaction
      description: Posts a reaction to a comment.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - file_comments:write
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: comment_id
        in: path
        description: The ID of the comment.
        required: true
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emoji
              properties:
                emoji:
                  type: string
                  description: The emoji string to react with.
            examples:
              PostcommentreactionRequestExample:
                summary: Default postCommentReaction request
                x-microcks-default: true
                value:
                  emoji: example_value
      responses:
        '200':
          description: Successfully posted the reaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                Postcommentreaction200Example:
                  summary: Default postCommentReaction 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    status: 200
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://api.figma.com
      description: Figma Production API Server
components:
  schemas:
    User:
      type: object
      description: A description of a user.
      properties:
        id:
          type: string
          description: Unique stable id of the user.
        handle:
          type: string
          description: Name of the user.
        img_url:
          type: string
          description: URL link to the user's profile image.
      required:
      - id
      - handle
      - img_url
    Comment:
      type: object
      description: A comment or reply left by a user.
      properties:
        id:
          type: string
          description: Unique identifier for comment.
        client_meta:
          description: 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.
          oneOf:
          - $ref: '#/components/schemas/Vector'
          - $ref: '#/components/schemas/FrameOffset'
          - $ref: '#/components/schemas/Region'
          - $ref: '#/components/schemas/FrameOffsetRegion'
        file_key:
          type: string
          description: The file in which the comment lives
        parent_id:
          type: string
          description: If present, the id of the comment to which this is the reply
        user:
          $ref: '#/components/schemas/User'
          description: The user who left the comment
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the comment was left
        resolved_at:
          type:
          - string
          - 'null'
          format: date-time
          description: If set, the UTC ISO 8601 time the comment was resolved
        message:
          type: string
          description: The content of the comment
        order_id:
          type:
          - string
          - 'null'
          description: Only set for top level comments. The number displayed with the comment in the UI
        reactions:
          type: array
          description: An array of reactions to the comment
          items:
            $ref: '#/components/schemas/Reaction'
      required:
      - id
      - client_meta
      - file_key
      - user
      - created_at
      - message
      - reactions
      - order_id
    Emoji:
      type: string
      description: 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.
    Vector:
      type: object
      description: A 2d vector.
      properties:
        x:
          type: number
          description: X coordinate of the vector.
        y:
          type: number
          description: Y coordinate of the vector.
      required:
      - x
      - y
    FrameOffset:
      type: object
      description: Position of a comment relative to the frame to which it is attached.
      properties:
        node_id:
          type: string
          description: Unique id specifying the frame.
        node_offset:
          $ref: '#/components/schemas/Vector'
          description: 2D vector offset within the frame from the top-left corner.
      required:
      - node_id
      - node_offset
    Reaction:
      type: object
      description: A reaction left by a user.
      properties:
        user:
          $ref: '#/components/schemas/User'
          description: The user who left the reaction.
        emoji:
          $ref: '#/components/schemas/Emoji'
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the reaction was left.
      required:
      - user
      - emoji
      - created_at
    ErrorResponsePayloadWithErrMessage:
      type: object
      description: A response indicating an error occurred.
      properties:
        status:
          type: number
          description: Status code
        err:
          type: string
          description: A string describing the error
      required:
      - status
      - err
    ErrorResponsePayloadWithErrorBoolean:
      type: object
      description: A response indicating an error occurred.
      properties:
        error:
          type: boolean
          description: For erroneous requests, this value is always `true`.
          enum:
          - true
        status:
          type: number
          description: Status code
        message:
          type: string
          description: A string describing the error
      required:
      - error
      - status
      - message
    FrameOffsetRegion:
      type: object
      description: Position of a region comment relative to the frame to which it is attached.
      properties:
        node_id:
          type: string
          description: Unique id specifying the frame.
        node_offset:
          $ref: '#/components/schemas/Vector'
          description: 2D vector offset within the frame from the top-left corner.
        region_height:
          type: number
          description: The height of the comment region. Must be greater than 0.
        region_width:
          type: number
          description: The width of the comment region. Must be greater than 0.
        comment_pin_corner:
          type: string
          description: The corner of the comment region to pin to the node's corner as a string enum.
          enum:
          - top-left
          - top-right
          - bottom-left
          - bottom-right
          default: bottom-right
      required:
      - node_id
      - node_offset
      - region_height
      - region_width
    Region:
      type: object
      description: Position of a region comment on the canvas.
      properties:
        x:
          type: number
          description: X coordinate of the position.
        y:
          type: number
          description: Y coordinate of the position.
        region_height:
          type: number
          description: The height of the comment region. Must be greater than 0.
        region_width:
          type: number
          description: The width of the comment region. Must be greater than 0.
        comment_pin_corner:
          type: string
          description: The corner of the comment region to pin to the node's corner as a string enum.
          enum:
          - top-left
          - top-right
          - bottom-left
          - bottom-right
          default: bottom-right
      required:
      - x
      - y
      - region_height
      - region_width
    User_2:
      type: object
      description: A Figma user account.
      required:
      - id
      - handle
      - img_url
      properties:
        id:
          type: string
          description: Unique stable ID of the user.
          example: abc123
        handle:
          type: string
          description: Display name of the user.
          example: example_value
        img_url:
          type: string
          format: uri
          description: URL of the user's profile image.
          example: https://www.example.com
        email:
          type: string
          format: email
          description: Email address associated with the user's account.
          example: user@example.com
    ErrorResponse:
      type: object
      description: Standard error response from the Figma API.
      required:
      - error
      - status
      - message
      properties:
        error:
          type: boolean
          description: Always true for error responses.
          enum:
          - true
          example: true
        status:
          type: integer
          description: The HTTP status code.
          example: 10
        message:
          type: string
          description: A human-readable description of the error.
          example: example_value
    Comment_2:
      type: object
      description: A comment or reply left by a user on a Figma file. Comments can be pinned to specific locations on the canvas.
      required:
      - id
      - file_key
      - user
      - created_at
      - message
      - reactions
      - order_id
      properties:
        id:
          type: string
          description: Unique identifier for the comment.
          example: abc123
        file_key:
          type: string
          description: The key of the file the comment belongs to.
          example: example_value
        parent_id:
          type:
          - string
          - 'null'
          description: If present, the ID of the comment to which this is a reply.
          example: '500123'
        user:
          $ref: '#/components/schemas/User_2'
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the comment was left.
          example: '2026-01-15T10:30:00Z'
        resolved_at:
          type:
          - string
          - 'null'
          format: date-time
          description: If set, the UTC ISO 8601 time the comment was resolved.
          example: '2026-01-15T10:30:00Z'
        message:
          type: string
          description: The content of the comment.
          example: example_value
        order_id:
          type:
          - string
          - 'null'
          description: Only set for top-level comments. The number displayed with the comment in the UI.
          example: '500123'
        client_meta:
          $ref: '#/components/schemas/ClientMeta'
        reactions:
          type: array
          description: An array of emoji reactions to the comment.
          items:
            $ref: '#/components/schemas/Reaction_2'
          example: []
    SuccessResponse:
      type: object
      description: Generic success response.
      properties:
        error:
          type: boolean
          enum:
          - false
          example: false
        status:
          type: integer
          enum:
          - 200
          example: 200
    ClientMeta:
      type: object
      description: Position metadata for a pinned comment. Describes where the comment marker is located on the canvas.
      properties:
        x:
          type: number
          description: X coordinate of the comment pin.
          example: 42.5
        y:
          type: number
          description: Y coordinate of the comment pin.
          example: 42.5
        node_id:
          type: string
          description: The node ID the comment is pinned to.
          example: '500123'
        node_offset:
          type: object
          description: Offset from the node origin.
          properties:
            x:
              type: number
            y:
              type: number
          example: example_value
    GetCommentsResponse:
      type: object
      description: Response from the Get Comments endpoint.
      required:
      - comments
      properties:
        comments:
          type: array
          description: An array of comments on the file.
          items:
            $ref: '#/components/schemas/Comment_2'
          example: []
    GetReactionsResponse:
      type: object
      description: Response from the Get Reactions endpoint.
      required:
      - reactions
      properties:
        reactions:
          type: array
          items:
            $ref: '#/components/schemas/Reaction_2'
          example: []
        pagination:
          type: object
          properties:
            cursor:
              type: string
          example: example_value
    Reaction_2:
      type: object
      description: An emoji reaction left on a comment.
      required:
      - user
      - emoji
      - created_at
      properties:
        user:
          $ref: '#/components/schemas/User_2'
        emoji:
          type: string
          description: The emoji used for the reaction.
          example: example_value
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the reaction was left.
          example: '2026-01-15T10:30:00Z'
    PostCommentRequest:
      type: object
      description: Request body for posting a new comment.
      required:
      - message
      properties:
        message:
          type: string
          description: The text content of the comment.
          example: example_value
        comment_id:
          type: string
          description: The comment to reply to, if any. This must be a root comment. Creating a reply to a reply is not supported.
          example: '500123'
        client_meta:
          $ref: '#/components/schemas/ClientMeta'
  responses:
    InternalServerErrorResponseWithErrMessage:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 500
              required:
              - status
    DeleteCommentResponse:
      description: Response from the DELETE /v1/files/{file_key}/comments/{comment_id} endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: number
                description: The status of the request.
                enum:
                - 200
              error:
                type: boolean
                description: For successful requests, this value is always `false`.
                enum:
                - false
            required:
            - status
            - error
    PostCommentResponse:
      description: Response from the POST /v1/files/{file_key}/comments endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Comment'
    BadRequestErrorResponseWithErrorBoolean:
      description: 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.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 400
              required:
              - status
    ForbiddenErrorResponseWithErrMessage:
      description: 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.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 403
              required:
              - status
    TooManyRequestsErrorResponseWithErrMessage:
      description: In some cases API requests may be throttled or rate limited. Please wait a while before attempting the request again (typically a minute).
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 429
              required:
              - status
    NotFoundErrorResponseWithErrMessage:
      description: The requested file or resource was not found.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 404
              required:
              - status
    GetCommentsResponse:
      description: Response from the GET /v1/files/{file_key}/comments endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              comments:
                type: array
                description: An array of comments.
                items:
                  $ref: '#/components/schemas/Comment'
            required:
            - comments
    ForbiddenError:
      description: The authenticated user does not have the necessary permissions to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFoundError:
      description: The requested file, project, team, or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitError:
      description: Rate limit exceeded. The Figma API enforces rate limits on a per-user, per-app basis. Retry after the period indicated in the Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedError:
      description: Authentication token is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    FileKeyPathParam:
      name: file_key
      in: path
      description: 'The key of the Figma file. This can be found in the URL of the file: figma.com/file/{file_key}/...'
      required: true
      schema:
        type: string
      example: abc123xyz789
  securitySchemes:
    PersonalAccessToken:
      type: apiKey
      name: X-Figma-Token
      in: header
    PlanAccessToken:
      type: apiKey
      name: X-Figma-Token
      in: header
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          refreshUrl: https://api.figma.com/v1/oauth/refresh
          scopes:
            current_user:read: Read your name, email, and profile image.
            file_comments:read: Read the comments for files.
            file_comments:write: Post and delete comments and comment reactions in files.
            file_content:read: Read the contents of files, such as nodes and the editor type.
            file_dev_resources:read: Read dev resources in files.
            file_dev_resources:write: Write to dev resources in files.
            file_metadata:read: Read metadata of files.
            file_variables:read: 'Read variables in Figma file. Note: this is only available to members in Enterprise organizations.'
            file_variables:write: 'Write to variables in Figma file. Note: this is only available to members in Enterprise organizations.'
            file_versions:read: Read the version history for files you can access.
            files:read: Deprecated. Read files, projects, users, versions, comments, components & styles, and webhooks.
            library_analytics:read: Read library analytics data.
            library_assets:read: Read data of individual published components and styles.
            library_content:read: Read published components and styles of files.
            project_metadata:read: Read metadata of projects.
            projects:read: List projects and files in projects.
            folders:read: List folders and files in folders.
            folder_metadata:read: Read metadata of folders.
            team_library_content:read: Read published components and styles of teams.
            webhooks:read: Read metadata of webhooks.
            webhooks:write: Create and manage webhooks.
    OrgOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          refreshUrl: https://api.figma.com/v1/oauth/refresh
          scopes:
            org:activity_log_read: Read activity logs in the organization.
externalDocs:
  description: Figma REST API Documentation
  url: https://developers.figma.com/docs/rest-api/
x-refined-from:
- figma-openapi.yml
- figma-rest-api-openapi.yml