Figma Files API

openapi: 3.2.0
info:
  title: Figma REST Files API
  version: 2.0.0
  description: The Figma REST API provides programmatic access to Figma files, comments, components, and related resources. It enables developers to read and interact with design data, export assets, manage comments and reactions, and query published components and styles from team libraries. Authentication is done via personal access tokens or OAuth 2.0.
  termsOfService: https://www.figma.com/developer-terms/
  contact:
    name: Figma Developer Support
    url: https://www.figma.com/developers
    email: support@figma.com
  license:
    name: Figma Developer Terms
    url: https://www.figma.com/developer-terms/
  externalDocs:
    description: Figma REST API Documentation
    url: https://developers.figma.com/docs/rest-api/
servers:
- url: https://api.figma.com
  description: Figma Production API Server
tags:
- name: Files
  description: Endpoints for retrieving Figma file data including document trees, nodes, images, and version history.
  externalDocs:
    description: File Endpoints Documentation
    url: https://developers.figma.com/docs/rest-api/file-endpoints/
paths:
  /v1/files/{file_key}:
    get:
      tags:
      - Files
      summary: Figma Get File
      operationId: getFile
      description: Returns the document tree for a given Figma file. If the file is large, the response may be paginated. The file_key can be found in the Figma file URL after figma.com/file/.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: version
        in: query
        description: A specific version ID to get. Omitting this will get the current version.
        required: false
        schema:
          type: string
        example: example_value
      - name: ids
        in: query
        description: Comma-separated list of nodes that you want to receive. If not set, all nodes are returned.
        required: false
        schema:
          type: string
        example: example_value
      - name: depth
        in: query
        description: Positive integer representing how deep into the document tree to traverse. For example, setting depth=1 returns only pages.
        required: false
        schema:
          type: integer
          minimum: 1
        example: 10
      - name: geometry
        in: query
        description: Set to "paths" to export vector data.
        required: false
        schema:
          type: string
          enum:
          - paths
        example: paths
      - name: plugin_data
        in: query
        description: Comma-separated list of plugin IDs or the string "shared" for data present in all plugins.
        required: false
        schema:
          type: string
        example: example_value
      - name: branch_data
        in: query
        description: Set to true to include branch metadata in the response.
        required: false
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successfully retrieved the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFileResponse'
              examples:
                Getfile200Example:
                  summary: Default getFile 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    role: owner
                    lastModified: '2026-01-15T10:30:00Z'
                    editorType: figma
                    thumbnailUrl: https://www.example.com
                    version: example_value
                    document:
                      id: abc123
                      name: Example Title
                      type: DOCUMENT
                      children:
                      - {}
                    components: example_value
                    componentSets: example_value
                    schemaVersion: 10
                    styles: example_value
                    mainFileKey: example_value
                    branches:
                    - key: example_value
                      name: Example Title
                      thumbnail_url: https://www.example.com
                      last_modified: '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'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/files/{file_key}/nodes:
    get:
      tags:
      - Files
      summary: Figma Get File Nodes
      operationId: getFileNodes
      description: Returns the nodes referenced by ids as a JSON object. The nodes are retrieved from the document referred to by file_key. The node ID and file key for a given node can be parsed from any Figma node URL.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: ids
        in: query
        description: Comma-separated list of node IDs to retrieve.
        required: true
        schema:
          type: string
        example: example_value
      - name: version
        in: query
        description: A specific version ID to get.
        required: false
        schema:
          type: string
        example: example_value
      - name: depth
        in: query
        description: Positive integer for how deep into the node tree to traverse.
        required: false
        schema:
          type: integer
          minimum: 1
        example: 10
      - name: geometry
        in: query
        description: Set to "paths" to export vector data.
        required: false
        schema:
          type: string
          enum:
          - paths
        example: paths
      - name: plugin_data
        in: query
        description: Comma-separated list of plugin IDs or "shared".
        required: false
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully retrieved the file nodes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFileNodesResponse'
              examples:
                Getfilenodes200Example:
                  summary: Default getFileNodes 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    lastModified: '2026-01-15T10:30:00Z'
                    version: example_value
                    role: owner
                    nodes: example_value
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/images/{file_key}:
    get:
      tags:
      - Files
      summary: Figma Get Image Renders
      operationId: getImages
      description: Renders images from a file. If no error occurs, the response includes a mapping from node IDs to URLs of the rendered images. The image assets are stored temporarily and expire after 14 days.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: ids
        in: query
        description: Comma-separated list of node IDs to render.
        required: true
        schema:
          type: string
        example: example_value
      - name: scale
        in: query
        description: A number between 0.01 and 4, the image scaling factor.
        required: false
        schema:
          type: number
          minimum: 0.01
          maximum: 4
        example: 42.5
      - name: format
        in: query
        description: Image output format.
        required: false
        schema:
          type: string
          enum:
          - jpg
          - png
          - svg
          - pdf
        example: jpg
      - name: svg_include_id
        in: query
        description: Whether to include id attributes for all SVG elements.
        required: false
        schema:
          type: boolean
        example: '500123'
      - name: svg_simplify_stroke
        in: query
        description: Whether to simplify inside/outside strokes and use stroke attribute.
        required: false
        schema:
          type: boolean
        example: true
      - name: use_absolute_bounds
        in: query
        description: Use the full dimensions of the node regardless of cropping.
        required: false
        schema:
          type: boolean
        example: true
      - name: version
        in: query
        description: A specific version ID to get.
        required: false
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully rendered images.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetImagesResponse'
              examples:
                Getimages200Example:
                  summary: Default getImages 200 response
                  x-microcks-default: true
                  value:
                    err: example_value
                    images: example_value
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/files/{file_key}/image_fills:
    get:
      tags:
      - Files
      summary: Figma Get Image Fills
      operationId: getImageFills
      description: Returns a mapping of image references to URLs of the image contents. Image URLs expire after no more than 14 days.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      responses:
        '200':
          description: Successfully retrieved image fill URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetImageFillsResponse'
              examples:
                Getimagefills200Example:
                  summary: Default getImageFills 200 response
                  x-microcks-default: true
                  value:
                    error: true
                    status: 10
                    meta:
                      images: example_value
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/files/{file_key}/versions:
    get:
      tags:
      - Files
      summary: Figma Get File Version History
      operationId: getFileVersions
      description: Returns a list of the version history of a file. The version history consists of versions, auto-save entries, and named versions.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - name: page_size
        in: query
        description: Number of items to return per page. Defaults to 30.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        example: 10
      - name: before
        in: query
        description: Version ID before which to start listing versions. Used for pagination.
        required: false
        schema:
          type: string
        example: example_value
      - name: after
        in: query
        description: Version ID after which to start listing versions. Used for pagination.
        required: false
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully retrieved version history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFileVersionsResponse'
              examples:
                Getfileversions200Example:
                  summary: Default getFileVersions 200 response
                  x-microcks-default: true
                  value:
                    versions:
                    - id: abc123
                      created_at: '2026-01-15T10:30:00Z'
                      label: Example Title
                      description: A sample description.
                    pagination:
                      before: 42.5
                      after: 42.5
        '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:
    Pagination:
      type: object
      description: Cursor-based pagination metadata.
      properties:
        before:
          type: number
          description: Cursor value for the page before the current one.
          example: 42.5
        after:
          type: number
          description: Cursor value for the page after the current one.
          example: 42.5
    GetImageFillsResponse:
      type: object
      description: Response from the Get Image Fills endpoint.
      properties:
        error:
          type: boolean
          example: true
        status:
          type: integer
          example: 10
        meta:
          type: object
          properties:
            images:
              type: object
              description: A mapping from image references to image download URLs.
              additionalProperties:
                type: string
          example: example_value
    Component:
      type: object
      description: Metadata about a main component in a Figma file. Components are reusable design elements.
      required:
      - key
      - name
      - description
      - documentationLinks
      - remote
      properties:
        key:
          type: string
          description: The globally unique key of the component.
          example: example_value
        name:
          type: string
          description: Name of the component.
          example: Example Title
        description:
          type: string
          description: The description of the component as entered in the editor.
          example: A sample description.
        componentSetId:
          type:
          - string
          - 'null'
          description: The ID of the component set this component belongs to, if any.
          example: '500123'
        documentationLinks:
          type: array
          description: An array of documentation links attached to this component.
          items:
            $ref: '#/components/schemas/DocumentationLink'
          example: []
        remote:
          type: boolean
          description: Whether this component is a remote component that was pulled from an external library.
          example: true
    Style:
      type: object
      description: A published style that can be applied to nodes in Figma.
      required:
      - key
      - name
      - description
      - remote
      - style_type
      properties:
        key:
          type: string
          description: The globally unique key of the style.
          example: example_value
        name:
          type: string
          description: Name of the style.
          example: Example Title
        description:
          type: string
          description: Description of the style.
          example: A sample description.
        remote:
          type: boolean
          description: Whether this style is a remote style from an external library.
          example: true
        style_type:
          type: string
          description: The type of style.
          enum:
          - FILL
          - TEXT
          - EFFECT
          - GRID
          example: FILL
    DocumentationLink:
      type: object
      description: A link to documentation associated with a component.
      required:
      - uri
      properties:
        uri:
          type: string
          format: uri
          description: The URI of the documentation link.
          example: https://www.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
    GetFileResponse:
      type: object
      description: Response from the Get File endpoint.
      required:
      - name
      - role
      - lastModified
      - editorType
      - version
      - document
      - components
      - componentSets
      - schemaVersion
      - styles
      properties:
        name:
          type: string
          description: The name of the file as it appears in the editor.
          example: Example Title
        role:
          type: string
          enum:
          - owner
          - editor
          - viewer
          description: The role of the requesting user in relation to the file.
          example: owner
        lastModified:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the file was last modified.
          example: '2026-01-15T10:30:00Z'
        editorType:
          type: string
          enum:
          - figma
          - figjam
          description: The type of editor associated with this file.
          example: figma
        thumbnailUrl:
          type: string
          format: uri
          description: A URL to a thumbnail image of the file.
          example: https://www.example.com
        version:
          type: string
          description: The version number of the file.
          example: example_value
        document:
          $ref: '#/components/schemas/DocumentNode'
        components:
          type: object
          description: A mapping from component IDs to component metadata.
          additionalProperties:
            $ref: '#/components/schemas/Component'
          example: example_value
        componentSets:
          type: object
          description: A mapping from component set IDs to component set metadata.
          additionalProperties:
            $ref: '#/components/schemas/ComponentSet'
          example: example_value
        schemaVersion:
          type: integer
          description: The schema version of the file format.
          example: 10
        styles:
          type: object
          description: A mapping from style IDs to style metadata.
          additionalProperties:
            $ref: '#/components/schemas/Style'
          example: example_value
        mainFileKey:
          type: string
          description: The key of the main file, if this is a branch.
          example: example_value
        branches:
          type: array
          description: A list of branches for this file.
          items:
            $ref: '#/components/schemas/Branch'
          example: []
    GetImagesResponse:
      type: object
      description: Response from the Get Images endpoint.
      properties:
        err:
          type:
          - string
          - 'null'
          description: If present, indicates an error rendering the images.
          example: example_value
        images:
          type: object
          description: A mapping from node IDs to URLs of the rendered images. Image URLs expire after 14 days.
          additionalProperties:
            type:
            - string
            - 'null'
          example: example_value
    GetFileNodesResponse:
      type: object
      description: Response from the Get File Nodes endpoint.
      required:
      - name
      - lastModified
      - version
      - nodes
      properties:
        name:
          type: string
          description: The name of the file.
          example: Example Title
        lastModified:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        version:
          type: string
          example: example_value
        role:
          type: string
          enum:
          - owner
          - editor
          - viewer
          example: owner
        nodes:
          type: object
          description: A mapping from node IDs to node data. Each value contains a document subtree and optionally the component metadata for that node.
          additionalProperties:
            type: object
            properties:
              document:
                type: object
                description: The node subtree.
              components:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Component'
              schemaVersion:
                type: integer
              styles:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Style'
          example: example_value
    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
    ComponentSet:
      type: object
      description: A component set groups variants of a component together. Useful for organizing different states or configurations of a design element.
      required:
      - key
      - name
      - description
      properties:
        key:
          type: string
          description: The globally unique key of the component set.
          example: example_value
        name:
          type: string
          description: Name of the component set.
          example: Example Title
        description:
          type: string
          description: The description of the component set as entered in the editor.
          example: A sample description.
        documentationLinks:
          type: array
          description: Documentation links attached to this component set.
          items:
            $ref: '#/components/schemas/DocumentationLink'
          example: []
        remote:
          type: boolean
          description: Whether this is a remote component set.
          example: true
    Branch:
      type: object
      description: Information about a branch of a Figma file.
      required:
      - key
      - name
      - thumbnail_url
      - last_modified
      properties:
        key:
          type: string
          description: The key of the branch file.
          example: example_value
        name:
          type: string
          description: The name of the branch.
          example: Example Title
        thumbnail_url:
          type: string
          format: uri
          description: A URL to a thumbnail image of the branch.
          example: https://www.example.com
        last_modified:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the branch was last modified.
          example: '2026-01-15T10:30:00Z'
    DocumentNode:
      type: object
      description: The root node of a Figma document.
      required:
      - id
      - name
      - type
      - children
      properties:
        id:
          type: string
          description: A string uniquely identifying this node within the document.
          example: abc123
        name:
          type: string
          description: The name given to the node by the user in the tool.
          example: Example Title
        type:
          type: string
          enum:
          - DOCUMENT
          description: The type of the node.
          example: DOCUMENT
        children:
          type: array
          description: An array of canvases (pages) attached to the document.
          items:
            $ref: '#/components/schemas/CanvasNode'
          example: []
    Version:
      type: object
      description: A recorded version in the file's version history.
      required:
      - id
      - created_at
      - label
      - description
      - user
      properties:
        id:
          type: string
          description: Unique identifier for the version.
          example: abc123
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the version was created.
          example: '2026-01-15T10:30:00Z'
        label:
          type:
          - string
          - 'null'
          description: The label given to the version in the editor.
          example: Example Title
        description:
          type:
          - string
          - 'null'
          description: The description of the version as entered in the editor.
          example: A sample description.
        user:
          $ref: '#/components/schemas/User'
    CanvasNode:
      type: object
      description: A canvas (page) in the Figma document.
      required:
      - id
      - name
      - type
      properties:
        id:
          type: string
          description: A string uniquely identifying this node within the document.
          example: abc123
        name:
          type: string
          description: The name given to the page by the user.
          example: Example Title
        type:
          type: string
          enum:
          - CANVAS
          description: The type of the node.
          example: CANVAS
        backgroundColor:
          $ref: '#/components/schemas/Color'
        children:
          type: array
          description: An array of top-level layers on the canvas.
          items:
            type: object
          example: []
    GetFileVersionsResponse:
      type: object
      description: Response from the Get File Versions endpoint.
      required:
      - versions
      properties:
        versions:
          type: array
          description: An array of version history entries.
          items:
            $ref: '#/components/schemas/Version'
          example: []
        pagination:
          $ref: '#/components/schemas/Pagination'
    Color:
      type: object
      description: An RGBA color value with channels ranging from 0 to 1.
      required:
      - r
      - g
      - b
      - a
      properties:
        r:
          type: number
          minimum: 0
          maximum: 1
          description: Red channel value, between 0 and 1.
          example: 42.5
        g:
          type: number
          minimum: 0
          maximum: 1
          description: Green channel value, between 0 and 1.
          example: 42.5
        b:
          type: number
          minimum: 0
          maximum: 1
          description: Blue channel value, between 0 and 1.
          example: 42.5
        a:
          type: number
          minimum: 0
          maximum: 1
          description: Alpha channel value, between 0 and 1.
          example: 42.5
  responses:
    ForbiddenError:
      description: The authenticated user does not have the necessary permissions to access this resource.
      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'
    InternalServerError:
      description: An unexpected error occurred on the Figma server.
      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'
  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: http
      scheme: bearer
      bearerFormat: Figma Personal Access Token
      description: Personal access tokens can be generated from the Figma account settings page. They provide full access to the Figma REST API on behalf of the user.
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow for Figma. Applications must be registered on the Figma developer portal.
      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:
            files:read: Read access to files the user can view
            file_variables:read: Read access to variables in files
            file_variables:write: Write access to variables in files
            file_comments:write: Post and delete comments on files
            file_dev_resources:read: Read dev resources on files
            file_dev_resources:write: Write dev resources on files
            webhooks:write: Create and manage webhooks