Figma Dev Resources API

openapi: 3.1.0
info:
  title: Figma Activity Logs Dev Resources 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: Dev Resources
  description: Operations for managing dev resources attached to design nodes
paths:
  /v1/dev_resources:
    post:
      tags:
      - Dev Resources
      summary: Figma Create Dev Resources
      security:
      - PersonalAccessToken: []
      - 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.
      operationId: postDevResources
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"PostDevResourcesSuccessExample\"\n}\n"
      requestBody:
        $ref: '#/components/requestBodies/CreateDevResourcesRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/PostDevResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    put:
      tags:
      - Dev Resources
      summary: Figma Update Dev Resources
      security:
      - PersonalAccessToken: []
      - 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.
      operationId: putDevResources
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"PutDevResourcesSuccessExample\"\n}\n"
      requestBody:
        $ref: '#/components/requestBodies/UpdateDevResourcesRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/PutDevResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v1/files/{file_key}/dev_resources/{dev_resource_id}:
    delete:
      tags:
      - Dev Resources
      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'
components:
  examples:
    InternalServerErrorExample:
      summary: Internal server error
      value:
        error: true
        status: 500
        message: An internal server error occurred
    DeleteDevResourceSuccessExample:
      summary: Successful dev resource deletion
      value:
        status: 200
        error: false
    NotFoundExample:
      summary: Not found error
      value:
        error: true
        status: 404
        message: File or dev resource not found
    PutDevResourcesSuccessExample:
      summary: Successful update dev resources response
      value:
        linksUpdated:
        - id: dev_res_123
          name: Updated Button Component
          url: https://github.com/myorg/design-system/blob/main/src/components/Button/index.tsx
          fileKey: abc123xyz789
          nodeId: '1:1'
        - id: dev_res_456
          name: Button Documentation
          url: https://storybook.myorg.com/?path=/story/button
          fileKey: abc123xyz789
          nodeId: '1:1'
        errors: []
    CreateDevResourcesRequestExample:
      summary: Create dev resources request
      value:
        devResources:
        - name: Button Component Code
          url: https://github.com/myorg/design-system/blob/main/src/components/Button.tsx
          fileKey: abc123xyz789
          nodeId: '1:1'
        - name: Button Storybook
          url: https://storybook.myorg.com/?path=/story/button
          fileKey: abc123xyz789
          nodeId: '1:1'
    BadRequestExample:
      summary: Bad request error
      value:
        error: true
        status: 400
        message: 'Invalid parameter: url format is incorrect'
    UnauthorizedExample:
      summary: Unauthorized error
      value:
        error: true
        status: 401
        message: Token is missing or incorrect
    TooManyRequestsExample:
      summary: Rate limit error
      value:
        error: true
        status: 429
        message: Rate limit exceeded. Please wait before making another request
    ForbiddenExample:
      summary: Forbidden error
      value:
        error: true
        status: 403
        message: You do not have permission to modify dev resources for this file
    UpdateDevResourcesRequestExample:
      summary: Update dev resources request
      value:
        devResources:
        - id: dev_res_123
          name: Updated Button Component
          url: https://github.com/myorg/design-system/blob/main/src/components/Button/index.tsx
        - id: dev_res_456
          name: Button Documentation
    PostDevResourcesSuccessExample:
      summary: Successful create dev resources response
      value:
        linksCreated:
        - id: dev_res_123
          name: Button Component Code
          url: https://github.com/myorg/design-system/blob/main/src/components/Button.tsx
          fileKey: abc123xyz789
          nodeId: '1:1'
        - id: dev_res_456
          name: Button Storybook
          url: https://storybook.myorg.com/?path=/story/button
          fileKey: abc123xyz789
          nodeId: '1:1'
        errors: []
  requestBodies:
    UpdateDevResourcesRequestBody:
      description: A list of dev resources that you want to update.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateDevResourcesRequest'
          examples:
            UpdateDevResourcesExample:
              $ref: '#/components/examples/UpdateDevResourcesRequestExample'
    CreateDevResourcesRequestBody:
      description: A list of dev resources that you want to create.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateDevResourcesRequest'
          examples:
            CreateDevResourcesExample:
              $ref: '#/components/examples/CreateDevResourcesRequestExample'
  responses:
    ForbiddenErrorResponse:
      description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponsePayload'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
    DeleteDevResourceResponse:
      description: Response from the DELETE /v1/files/{file_key}/dev_resources/{dev_resource_id} endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeleteDevResourceResponseBody'
          examples:
            DeleteDevResourceSuccessExample:
              $ref: '#/components/examples/DeleteDevResourceSuccessExample'
    PostDevResourcesResponse:
      description: Response from the POST /v1/dev_resources endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostDevResourcesResponseBody'
          examples:
            PostDevResourcesSuccessExample:
              $ref: '#/components/examples/PostDevResourcesSuccessExample'
    BadRequestErrorResponse:
      description: Bad request. Parameters are invalid or malformed. Please check the input formats.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponsePayload'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    TooManyRequestsErrorResponse:
      description: API requests may be throttled or rate limited. Please wait a while before attempting the request again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponsePayload'
          examples:
            TooManyRequestsExample:
              $ref: '#/components/examples/TooManyRequestsExample'
    NotFoundErrorResponse:
      description: The requested file or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponsePayload'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    UnauthorizedErrorResponse:
      description: Token is missing or incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponsePayload'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    InternalServerErrorResponse:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponsePayload'
          examples:
            InternalServerErrorExample:
              $ref: '#/components/examples/InternalServerErrorExample'
    PutDevResourcesResponse:
      description: Response from the PUT /v1/dev_resources endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PutDevResourcesResponseBody'
          examples:
            PutDevResourcesSuccessExample:
              $ref: '#/components/examples/PutDevResourcesSuccessExample'
  schemas:
    CreateDevResourcesRequest:
      type: object
      properties:
        devResources:
          type: array
          description: An array of dev resources to create.
          items:
            $ref: '#/components/schemas/CreateDevResourceItem'
          example: []
      required:
      - devResources
    UpdateDevResourcesRequest:
      type: object
      properties:
        devResources:
          type: array
          description: An array of dev resources to update.
          items:
            $ref: '#/components/schemas/UpdateDevResourceItem'
          example: []
      required:
      - devResources
    DevResourceUpdateError:
      type: object
      properties:
        id:
          type: string
          description: The id of the dev resource.
          example: abc123
        error:
          type: string
          description: The error message.
          example: example_value
      required:
      - error
    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
    PostDevResourcesResponseBody:
      type: object
      properties:
        linksCreated:
          type: array
          description: An array of links created.
          items:
            $ref: '#/components/schemas/DevResource'
          example: []
        errors:
          type: array
          description: An array of errors.
          items:
            $ref: '#/components/schemas/DevResourceCreateError'
          example: []
      required:
      - linksCreated
    CreateDevResourceItem:
      type: object
      properties:
        name:
          type: string
          description: The name of the dev resource.
          example: Example Title
        url:
          type: string
          description: The URL of the dev resource.
          example: https://www.example.com
        fileKey:
          type: string
          description: The file key where the dev resource belongs.
          example: example_value
        nodeId:
          type: string
          description: The target node to attach the dev resource to.
          example: '500123'
      required:
      - name
      - url
      - fileKey
      - nodeId
    DevResource:
      type: object
      description: A dev resource in a file
      properties:
        id:
          type: string
          description: Unique identifier of the dev resource
          example: abc123
        name:
          type: string
          description: The name of the dev resource.
          example: Example Title
        url:
          type: string
          description: The URL of the dev resource.
          example: https://www.example.com
        fileKey:
          type: string
          description: The file key where the dev resource belongs.
          example: example_value
        nodeId:
          type: string
          description: The target node to attach the dev resource to.
          example: '500123'
      required:
      - id
      - name
      - url
      - fileKey
      - nodeId
    PutDevResourcesResponseBody:
      type: object
      properties:
        linksUpdated:
          type: array
          description: An array of links updated.
          items:
            $ref: '#/components/schemas/DevResource'
          example: []
        errors:
          type: array
          description: An array of errors.
          items:
            $ref: '#/components/schemas/DevResourceUpdateError'
          example: []
      required:
      - linksUpdated
    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
    UpdateDevResourceItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the dev resource
          example: abc123
        name:
          type: string
          description: The name of the dev resource.
          example: Example Title
        url:
          type: string
          description: The URL of the dev resource.
          example: https://www.example.com
      required:
      - id
    DevResourceCreateError:
      type: object
      properties:
        fileKey:
          type:
          - string
          - 'null'
          description: The file key.
          example: example_value
        nodeId:
          type:
          - string
          - 'null'
          description: The node id.
          example: '500123'
        error:
          type: string
          description: The error message.
          example: example_value
      required:
      - error
  parameters:
    FileKeyPathParam:
      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
      example: abc123xyz789
    DevResourceIdPathParam:
      name: dev_resource_id
      in: path
      description: The id of the dev resource to delete.
      required: true
      schema:
        type: string
      example: dev_res_123456
  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