Figma Dev Resources API

openapi: 3.2.0
info:
  title: Figma Dev Resources API
  version: 0.45.0
  description: 'This is the OpenAPI specification for the Figma REST API.


    Note: we are releasing the OpenAPI specification as a beta given the large surface area and complexity of the REST API. If you notice any inaccuracies with the specification, please file an issue.'
  termsOfService: https://www.figma.com/developer-terms/
  contact:
    email: support@figma.com
servers:
- url: https://api.figma.com
tags:
- name: Dev Resources
  description: Interact with dev resources in Figma Dev Mode.
  externalDocs:
    description: Dev resource endpoints documentation
    url: https://developers.figma.com/docs/rest-api/dev-resources-endpoints/
paths:
  /v1/files/{file_key}/dev_resources:
    get:
      tags:
      - Dev Resources
      summary: Get dev resources
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - file_dev_resources:read
      description: Get dev resources in a file
      operationId: getDevResources
      parameters:
      - name: file_key
        in: path
        description: The file to get the dev resources from. This must be a main file key, not a branch key.
        required: true
        schema:
          type: string
      - name: node_ids
        in: query
        description: Comma separated list of nodes that you care about in the document. If specified, only dev resources attached to these nodes will be returned. If not specified, all dev resources in the file will be returned.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GetDevResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrorBoolean'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponseWithErrorBoolean'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrorBoolean'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrorBoolean'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrorBoolean'
  /v1/dev_resources:
    post:
      tags:
      - Dev Resources
      summary: Create dev resources
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - file_dev_resources:write
      description: 'Bulk create dev resources across multiple files.

        Dev resources that are successfully created will show up in the links_created array in the response.


        If there are any dev resources that cannot be created, you may still get a 200 response. These resources will show up in the errors array. Some reasons a dev resource cannot be created include:


        - Resource points to a `file_key` that cannot be found.

        - The node already has the maximum of 10 dev resources.

        - Another dev resource for the node has the same url.'
      operationId: postDevResources
      requestBody:
        description: A list of dev resources that you want to create.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dev_resources:
                  type: array
                  description: An array of dev resources.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the dev resource.
                      url:
                        type: string
                        description: The URL of the dev resource.
                      file_key:
                        type: string
                        description: The file key where the dev resource belongs.
                      node_id:
                        type: string
                        description: The target node to attach the dev resource to.
                    required:
                    - name
                    - url
                    - file_key
                    - node_id
              required:
              - dev_resources
      responses:
        '200':
          $ref: '#/components/responses/PostDevResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrorBoolean'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponseWithErrorBoolean'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrorBoolean'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrorBoolean'
    put:
      tags:
      - Dev Resources
      summary: Update dev resources
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - file_dev_resources:write
      description: 'Bulk update dev resources across multiple files.


        Ids for dev resources that are successfully updated will show up in the `links_updated` array in the response.


        If there are any dev resources that cannot be updated, you may still get a 200 response. These resources will show up in the `errors` array.'
      operationId: putDevResources
      requestBody:
        description: A list of dev resources that you want to update.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dev_resources:
                  type: array
                  description: An array of dev resources.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the dev resource
                      name:
                        type: string
                        description: The name of the dev resource.
                      url:
                        type: string
                        description: The URL of the dev resource.
                    required:
                    - id
              required:
              - dev_resources
      responses:
        '200':
          $ref: '#/components/responses/PutDevResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrorBoolean'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponseWithErrorBoolean'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrorBoolean'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrorBoolean'
  /v1/files/{file_key}/dev_resources/{dev_resource_id}:
    delete:
      tags:
      - Dev Resources
      summary: Delete dev resource
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - file_dev_resources:write
      description: Delete a dev resource from a file
      operationId: deleteDevResource
      parameters:
      - name: file_key
        in: path
        description: The file to delete the dev resource from. This must be a main file key, not a branch key.
        required: true
        schema:
          type: string
      - name: dev_resource_id
        in: path
        description: The id of the dev resource to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/DeleteDevResourceResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponseWithErrorBoolean'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrorBoolean'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrorBoolean'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrorBoolean'
components:
  responses:
    GetDevResourcesResponse:
      description: Response from the GET /v1/files/{file_key}/dev_resources endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              dev_resources:
                type: array
                description: An array of dev resources.
                items:
                  $ref: '#/components/schemas/DevResource'
            required:
            - dev_resources
    NotFoundErrorResponseWithErrorBoolean:
      description: The requested file or resource was not found.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 404
              required:
              - status
    TooManyRequestsErrorResponseWithErrorBoolean:
      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/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 429
              required:
              - status
    PutDevResourcesResponse:
      description: Response from the PUT /v1/dev_resources endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              links_updated:
                type: array
                description: An array of links updated.
                items:
                  $ref: '#/components/schemas/DevResource'
              errors:
                type: array
                description: An array of errors.
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The id of the dev resource.
                    error:
                      type: string
                      description: The error message.
                  required:
                  - error
            required:
            - links_created
    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
    PostDevResourcesResponse:
      description: Response from the POST /v1/dev_resources endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              links_created:
                type: array
                description: An array of links created.
                items:
                  $ref: '#/components/schemas/DevResource'
              errors:
                type: array
                description: An array of errors.
                items:
                  type: object
                  properties:
                    file_key:
                      type:
                      - string
                      - 'null'
                      description: The file key.
                    node_id:
                      type:
                      - string
                      - 'null'
                      description: The node id.
                    error:
                      type: string
                      description: The error message.
                  required:
                  - error
            required:
            - links_created
    UnauthorizedErrorResponseWithErrorBoolean:
      description: Token is missing or incorrect.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 401
              required:
              - status
    InternalServerErrorResponseWithErrorBoolean:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 500
              required:
              - status
    ForbiddenErrorResponseWithErrorBoolean:
      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/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 403
              required:
              - status
    DeleteDevResourceResponse:
      description: Response from the DELETE /v1/files/{file_key}/dev_resources/{dev_resource_id} endpoint.
  schemas:
    DevResource:
      type: object
      description: A dev resource in a file
      properties:
        id:
          type: string
          description: Unique identifier of the dev resource
        name:
          type: string
          description: The name of the dev resource.
        url:
          type: string
          description: The URL of the dev resource.
        file_key:
          type: string
          description: The file key where the dev resource belongs.
        node_id:
          type: string
          description: The target node to attach the dev resource to.
      required:
      - id
      - name
      - url
      - file_key
      - node_id
    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
  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/