Figma Component Sets API

openapi: 3.2.0
info:
  title: Figma Component Sets 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: Component Sets
  description: Get information about published component sets.
  externalDocs:
    description: Component endpoints documentation
    url: https://developers.figma.com/docs/rest-api/component-endpoints/
paths:
  /v1/teams/{team_id}/component_sets:
    get:
      tags:
      - Component Sets
      summary: Get team component sets
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - team_library_content:read
        - files:read
      description: Get a paginated list of published component sets within a team library.
      operationId: getTeamComponentSets
      parameters:
      - name: team_id
        in: path
        description: Id of the team to list component sets from.
        required: true
        schema:
          type: string
      - name: page_size
        in: query
        description: Number of items to return in a paged list of results. Defaults to 30.
        schema:
          type: number
          default: 30
      - name: after
        in: query
        description: Cursor indicating which id after which to start retrieving component sets for. Exclusive with before. The cursor value is an internally tracked integer that doesn't correspond to any Ids.
        schema:
          type: number
      - name: before
        in: query
        description: Cursor indicating which id before which to start retrieving component sets for. Exclusive with after. The cursor value is an internally tracked integer that doesn't correspond to any Ids.
        schema:
          type: number
      responses:
        '200':
          $ref: '#/components/responses/GetTeamComponentSetsResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrMessage'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrMessage'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrMessage'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrMessage'
  /v1/files/{file_key}/component_sets:
    get:
      tags:
      - Component Sets
      summary: Get file component sets
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - library_content:read
        - files:read
      description: Get a list of published component sets within a file library.
      operationId: getFileComponentSets
      parameters:
      - name: file_key
        in: path
        description: File to list component sets from. This must be a main file key, not a branch key, as it is not possible to publish from branches.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GetFileComponentSetsResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrMessage'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrMessage'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrMessage'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrMessage'
  /v1/component_sets/{key}:
    get:
      tags:
      - Component Sets
      summary: Get component set
      security:
      - PersonalAccessToken: []
      - PlanAccessToken: []
      - OAuth2:
        - library_assets:read
        - files:read
      description: Get metadata on a published component set by key.
      operationId: getComponentSet
      parameters:
      - name: key
        in: path
        description: The unique identifier of the component set.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GetComponentSetResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponseWithErrMessage'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponseWithErrMessage'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrMessage'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrMessage'
components:
  responses:
    GetFileComponentSetsResponse:
      description: Response from the GET /v1/files/{file_key}/component_sets endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: number
                description: The status of the request.
                enum:
                - 200
              error:
                type: boolean
                description: For successful requests, this value is always `false`.
                enum:
                - false
              meta:
                type: object
                properties:
                  component_sets:
                    type: array
                    items:
                      $ref: '#/components/schemas/PublishedComponentSet'
                required:
                - component_sets
            required:
            - status
            - error
            - meta
    InternalServerErrorResponseWithErrMessage:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 500
              required:
              - status
    GetComponentSetResponse:
      description: Response from the GET /v1/component_sets/{key} endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: number
                description: The status of the request.
                enum:
                - 200
              error:
                type: boolean
                description: For successful requests, this value is always `false`.
                enum:
                - false
              meta:
                $ref: '#/components/schemas/PublishedComponentSet'
            required:
            - status
            - error
            - meta
    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
    BadRequestErrorResponseWithErrMessage:
      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/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 400
              required:
              - status
    ForbiddenErrorResponseWithErrMessage:
      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/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 403
              required:
              - status
    TooManyRequestsErrorResponseWithErrMessage:
      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/ErrorResponsePayloadWithErrMessage'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 429
              required:
              - status
    GetTeamComponentSetsResponse:
      description: Response from the GET /v1/teams/{team_id}/component_sets endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: number
                description: The status of the request.
                enum:
                - 200
              error:
                type: boolean
                description: For successful requests, this value is always `false`.
                enum:
                - false
              meta:
                type: object
                properties:
                  component_sets:
                    type: array
                    items:
                      $ref: '#/components/schemas/PublishedComponentSet'
                  cursor:
                    $ref: '#/components/schemas/ResponseCursor'
                required:
                - component_sets
            required:
            - status
            - error
            - meta
  schemas:
    User:
      type: object
      description: A description of a user.
      properties:
        id:
          type: string
          description: Unique stable id of the user.
        handle:
          type: string
          description: Name of the user.
        img_url:
          type: string
          description: URL link to the user's profile image.
      required:
      - id
      - handle
      - img_url
    PublishedComponentSet:
      type: object
      description: A node containing a set of variants of a component.
      properties:
        key:
          type: string
          description: The unique identifier for the component set.
        file_key:
          type: string
          description: The unique identifier of the Figma file that contains the component set.
        node_id:
          type: string
          description: The unique identifier of the component set node within the Figma file.
        thumbnail_url:
          type: string
          description: A URL to a thumbnail image of the component set.
        name:
          type: string
          description: The name of the component set.
        description:
          type: string
          description: The description of the component set as entered by the publisher.
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time when the component set was created.
        updated_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time when the component set was last updated.
        user:
          $ref: '#/components/schemas/User'
          description: The user who last updated the component set.
        containing_frame:
          $ref: '#/components/schemas/FrameInfo'
          description: The containing frame of the component set.
      required:
      - key
      - file_key
      - node_id
      - name
      - description
      - created_at
      - updated_at
      - user
    ResponseCursor:
      type: object
      description: Pagination cursor
      properties:
        before:
          type: number
        after:
          type: number
    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
    ErrorResponsePayloadWithErrMessage:
      type: object
      description: A response indicating an error occurred.
      properties:
        status:
          type: number
          description: Status code
        err:
          type: string
          description: A string describing the error
      required:
      - status
      - err
    FrameInfo:
      type: object
      description: Data on the frame a component resides in.
      properties:
        nodeId:
          type: string
          description: The ID of the frame node within the file.
        name:
          type: string
          description: The name of the frame node.
        backgroundColor:
          type: string
          description: The background color of the frame node.
        pageId:
          type: string
          description: The ID of the page containing the frame node.
        pageName:
          type: string
          description: The name of the page containing the frame node.
        containingStateGroup:
          deprecated: true
          description: Deprecated - Use containingComponentSet instead.
          oneOf:
          - type: object
            properties:
              nodeId:
                type: string
                description: The ID of the state group node.
              name:
                type: string
                description: The name of the state group node.
          - type: 'null'
        containingComponentSet:
          description: The component set node that contains the frame node.
          oneOf:
          - type: object
            properties:
              nodeId:
                type: string
                description: The ID of the component set node.
              name:
                type: string
                description: The name of the component set node.
          - type: 'null'
      required:
      - pageId
      - pageName
  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/