Figma Comments API

openapi: 3.1.0
info:
  title: Figma Activity Logs Comments API
  version: 0.21.0
  description: 'Figma allows designers to create and prototype their digital experiences -

    together in real-time and in one place - helping them turn their ideas and

    visions into products, faster. Figma''s mission is to make design

    accessible to everyone. The Figma API is one of the ways we aim to do that.'
  termsOfService: https://www.figma.com/developer-terms/
  contact:
    email: support@figma.com
servers:
- url: https://api.figma.com
  description: Figma Production API Server
tags:
- name: Comments
  description: Endpoints for managing comments and reactions on Figma files, including creating, listing, and deleting comments.
  externalDocs:
    description: Comments Endpoints Documentation
    url: https://developers.figma.com/docs/rest-api/comments-endpoints/
paths:
  /v1/files/{file_key}/comments:
    get:
      tags:
      - Comments
      summary: Figma Get Comments
      operationId: getComments
      description: Gets a list of comments left on the file. Comments are returned in order of creation, with the most recent comments first. By default, only root-level comments and their direct replies are returned.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: as_md
        in: query
        description: If set to true, comment message content will be returned as Markdown instead of plain text.
        required: false
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successfully retrieved comments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCommentsResponse'
              examples:
                Getcomments200Example:
                  summary: Default getComments 200 response
                  x-microcks-default: true
                  value:
                    comments:
                    - id: abc123
                      file_key: example_value
                      parent_id: '500123'
                      created_at: '2026-01-15T10:30:00Z'
                      resolved_at: '2026-01-15T10:30:00Z'
                      message: example_value
                      order_id: '500123'
                      reactions: {}
        '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
    post:
      tags:
      - Comments
      summary: Figma Post Comment
      operationId: postComment
      description: Posts a new comment on the file. The body of the request should contain the comment text and optionally the position (client_meta) where the comment should be pinned.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - file_comments:write
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCommentRequest'
            examples:
              PostcommentRequestExample:
                summary: Default postComment request
                x-microcks-default: true
                value:
                  message: example_value
                  comment_id: '500123'
                  client_meta:
                    x: 42.5
                    y: 42.5
                    node_id: '500123'
                    node_offset:
                      x: 42.5
                      y: 42.5
      responses:
        '200':
          description: Successfully posted the comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              examples:
                Postcomment200Example:
                  summary: Default postComment 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    file_key: example_value
                    parent_id: '500123'
                    user:
                      id: abc123
                      handle: example_value
                      img_url: https://www.example.com
                      email: user@example.com
                    created_at: '2026-01-15T10:30:00Z'
                    resolved_at: '2026-01-15T10:30:00Z'
                    message: example_value
                    order_id: '500123'
                    client_meta:
                      x: 42.5
                      y: 42.5
                      node_id: '500123'
                      node_offset:
                        x: 42.5
                        y: 42.5
                    reactions:
                    - emoji: example_value
                      created_at: '2026-01-15T10:30:00Z'
        '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
  /v1/files/{file_key}/comments/{comment_id}:
    delete:
      tags:
      - Comments
      summary: Figma Delete Comment
      operationId: deleteComment
      description: Deletes a specific comment. Only the comment creator or file owner can delete a comment.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - file_comments:write
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: comment_id
        in: path
        description: The ID of the comment to delete.
        required: true
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successfully deleted the comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                Deletecomment200Example:
                  summary: Default deleteComment 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
  /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
components:
  schemas:
    User:
      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
    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'
    SuccessResponse:
      type: object
      description: Generic success response.
      properties:
        error:
          type: boolean
          enum:
          - false
          example: false
        status:
          type: integer
          enum:
          - 200
          example: 200
    GetReactionsResponse:
      type: object
      description: Response from the Get Reactions endpoint.
      required:
      - reactions
      properties:
        reactions:
          type: array
          items:
            $ref: '#/components/schemas/Reaction'
          example: []
        pagination:
          type: object
          properties:
            cursor:
              type: string
          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'
          example: []
    Comment:
      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'
        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'
          example: []
    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
    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
    Reaction:
      type: object
      description: An emoji reaction left on a comment.
      required:
      - user
      - emoji
      - created_at
      properties:
        user:
          $ref: '#/components/schemas/User'
        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'
  responses:
    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:
    OrgOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          scopes:
            org:activity_log_read: Read organization activity logs