Figma Files API

openapi: 3.2.0
info:
  title: Figma Activity Logs Files 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: Files
  description: Operations for managing Figma files and their resources
paths:
  /v1/files/{file_key}/dev_resources/{dev_resource_id}:
    delete:
      tags:
      - Files
      summary: Figma Delete Dev Resource
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - file_dev_resources:write
      description: Delete a dev resource from a file
      operationId: deleteDevResource
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"DeleteDevResourceSuccessExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/FileKeyPathParam'
      - $ref: '#/components/parameters/DevResourceIdPathParam'
      responses:
        '200':
          $ref: '#/components/responses/DeleteDevResourceResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v1/images/{file_key}:
    get:
      tags:
      - Files
      summary: Figma Render Images of File Nodes
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      description: 'Renders images from a file.

        If no error occurs, `"images"` will be populated with a map from node IDs to URLs of the rendered images, and `"status"` will be omitted. The image assets will expire after 30 days. Images up to 32 megapixels can be exported. Any images that are larger will be scaled down.

        Important: the image map may contain values that are `null`. This indicates that rendering of that specific node has failed. This may be due to the node id not existing, or other reasons such has the node having no renderable components. It is guaranteed that any node that was requested for rendering will be represented in this map whether or not the render succeeded.

        To render multiple images from the same file, use the `ids` query parameter to specify multiple node ids.

        ``` GET /v1/images/:key?ids=1:2,1:3,1:4 ```

        '
      operationId: getImages
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"URI_PARTS\",\n  \"dispatcherRules\": \"file_key\"\n}\n"
        defaultResponse: GetImagesSuccessExample
      parameters:
      - $ref: '#/components/parameters/FileKeyPath'
      - $ref: '#/components/parameters/NodeIdsQuery'
      - $ref: '#/components/parameters/VersionQuery'
      - $ref: '#/components/parameters/ScaleQuery'
      - $ref: '#/components/parameters/FormatQuery'
      - $ref: '#/components/parameters/SvgOutlineTextQuery'
      - $ref: '#/components/parameters/SvgIncludeIdQuery'
      - $ref: '#/components/parameters/SvgIncludeNodeIdQuery'
      - $ref: '#/components/parameters/SvgSimplifyStrokeQuery'
      - $ref: '#/components/parameters/ContentsOnlyQuery'
      - $ref: '#/components/parameters/UseAbsoluteBoundsQuery'
      responses:
        '200':
          $ref: '#/components/responses/GetImagesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse_2'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse_2'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse_2'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse_2'
  /v1/projects/{project_id}/files:
    get:
      tags:
      - Files
      summary: Figma Get Files in a Project
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      description: Get a list of all the Files within the specified project.
      operationId: getProjectFiles
      x-microcks-operation:
        dispatcher: URI_PARTS
        dispatcherRules: project_id
        defaultResponse: GetProjectFilesSuccessExample
      parameters:
      - $ref: '#/components/parameters/ProjectIdPath'
      - $ref: '#/components/parameters/BranchDataQuery'
      responses:
        '200':
          $ref: '#/components/responses/GetProjectFilesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse_2'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse_3'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse_3'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse_3'
  /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_2'
      - 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_2'
      - 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/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_2'
      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_2'
      - 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:
    TooManyRequestsError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayloadWithErr'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 429
        required:
        - status
      example:
        status: 429
        err: Rate limit exceeded. Please wait before retrying.
    ForbiddenError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayloadWithErr'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 403
        required:
        - status
      example:
        status: 403
        err: Access denied. You do not have permission to access this project.
    InternalServerError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayloadWithErr'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 500
        required:
        - status
      example:
        status: 500
        err: Internal server error
    GetProjectFilesResponseBody:
      type: object
      description: Successful response containing project files.
      properties:
        name:
          type: string
          description: The project's name.
          example: Example Title
        files:
          type: array
          description: An array of files.
          items:
            $ref: '#/components/schemas/ProjectFile'
          example: []
      required:
      - name
      - files
      example:
        name: Mobile App Design
        files:
        - key: abc123XYZ789
          name: Design System Components
          thumbnail_url: https://s3-alpha.figma.com/thumbnails/abc123-xyz789
          last_modified: '2024-06-20T10:30:00Z'
        - key: def456UVW012
          name: App Screens
          thumbnail_url: https://s3-alpha.figma.com/thumbnails/def456-uvw012
          last_modified: '2024-06-19T15:45:00Z'
    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
    ErrorResponsePayloadWithMessage:
      type: object
      description: A response indicating an error occurred.
      properties:
        error:
          type: boolean
          description: For erroneous requests, this value is always `true`.
          enum:
          - true
          example: true
        status:
          type: number
          description: Status code
          example: 42.5
        message:
          type: string
          description: A string describing the error
          example: example_value
      required:
      - error
      - status
      - message
    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
    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
    ErrorResponsePayload_2:
      type: object
      description: A response indicating an error occurred.
      properties:
        status:
          type: number
          description: Status code
          example: 42.5
        err:
          type: string
          description: A string describing the error
          example: example_value
      required:
      - status
      - err
    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
    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
    BadRequestError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload_2'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 400
        required:
        - status
      example:
        status: 400
        err: 'Invalid parameter: scale must be between 0.01 and 4'
    ErrorResponsePayloadWithErr:
      type: object
      description: A response indicating an error occurred.
      properties:
        status:
          type: number
          description: Status code
          example: 42.5
        err:
          type: string
          description: A string describing the error
          example: example_value
      required:
      - status
      - err
    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: []
    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
    GetImagesResponseBody:
      type: object
      description: Successful response containing rendered image URLs.
      properties:
        err:
          type: 'null'
          description: For successful requests, this value is always `null`.
          example: example_value
        images:
          type: object
          description: A map from node IDs to URLs of the rendered images.
          additionalProperties:
            type:
            - string
            - 'null'
            description: A URL to the requested image.
            format: uri
          example: example_value
      required:
      - err
      - images
      example:
        err: null
        images:
          '1:2': https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/abc123
          '1:3': https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/def456
          '1:4': null
    InternalServerError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload_2'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 500
        required:
        - status
      example:
        status: 500
        err: Internal server error
    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
    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
    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
    DeleteDevResourceResponseBody:
      type: object
      description: Response body for successful dev resource deletion.
      properties:
        status:
          type: number
          description: The status of the request.
          enum:
          - 200
          example: 200
        error:
          type: boolean
          description: For successful requests, this value is always `false`.
          enum:
          - false
          example: false
      required:
      - status
      - error
    TooManyRequestsError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload_2'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 429
        required:
        - status
      example:
        status: 429
        err: Rate limit exceeded. Please wait before retrying.
    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: []
    BadRequestError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayloadWithMessage'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 400
        required:
        - status
      example:
        error: true
        status: 400
        message: Invalid project ID format
    ErrorResponsePayload:
      type: object
      description: A response indicating an error occurred.
      properties:
        error:
          type: boolean
          description: For erroneous requests, this value is always `true`.
          enum:
          - true
          example: true
        status:
          type: number
          description: Status code
          example: 42.5
        message:
          type: string
          description: A string describing the error
          example: example_value
      required:
      - error
      - status
      - message
    ProjectFile:
      type: object
     

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/figma/refs/heads/main/openapi/figma-files-api-openapi.yml