Figma Projects API

openapi: 3.2.0
info:
  title: Figma REST Projects 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: Projects
  description: Endpoints for listing team projects and project files.
  externalDocs:
    description: Projects Documentation
    url: https://developers.figma.com/docs/rest-api/projects-types/
paths:
  /v1/teams/{team_id}/projects:
    get:
      tags:
      - Projects
      summary: Figma Get Team Projects
      operationId: getTeamProjects
      description: Lists the projects for a specified team. Only projects visible to the authenticated user are returned.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - $ref: '#/components/parameters/TeamIdPathParam'
      responses:
        '200':
          description: Successfully retrieved team projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTeamProjectsResponse'
              examples:
                Getteamprojects200Example:
                  summary: Default getTeamProjects 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    projects:
                    - id: abc123
                      name: Example Title
        '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
  /v1/projects/{project_id}/files:
    get:
      tags:
      - Projects
      summary: Figma Get Project Files
      operationId: getProjectFiles
      description: Lists the files in a given project.
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      parameters:
      - name: project_id
        in: path
        description: The ID of the project to list files from.
        required: true
        schema:
          type: string
        example: '500123'
      - name: branch_data
        in: query
        description: Set to true to include branch metadata.
        required: false
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successfully retrieved project files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProjectFilesResponse'
              examples:
                Getprojectfiles200Example:
                  summary: Default getProjectFiles 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    files:
                    - key: example_value
                      name: Example Title
                      thumbnail_url: https://www.example.com
                      last_modified: '2026-01-15T10:30:00Z'
                      branches: {}
        '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:
  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'
    NotFoundError:
      description: The requested file, project, team, or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    Project:
      type: object
      description: A Figma project within a team.
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: The ID of the project.
          example: abc123
        name:
          type: string
          description: The name of the project.
          example: Example Title
    ProjectFile:
      type: object
      description: A file within a Figma project.
      required:
      - key
      - name
      - last_modified
      properties:
        key:
          type: string
          description: The file key.
          example: example_value
        name:
          type: string
          description: The name of the file.
          example: Example Title
        thumbnail_url:
          type: string
          format: uri
          description: A URL to a thumbnail image of the file.
          example: https://www.example.com
        last_modified:
          type: string
          format: date-time
          description: The UTC ISO 8601 time at which the file was last modified.
          example: '2026-01-15T10:30:00Z'
        branches:
          type: array
          description: Branches of this file, if branch_data was requested.
          items:
            $ref: '#/components/schemas/Branch'
          example: []
    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'
    GetProjectFilesResponse:
      type: object
      description: Response from the Get Project Files endpoint.
      required:
      - name
      - files
      properties:
        name:
          type: string
          description: The name of the project.
          example: Example Title
        files:
          type: array
          items:
            $ref: '#/components/schemas/ProjectFile'
          example: []
    GetTeamProjectsResponse:
      type: object
      description: Response from the Get Team Projects endpoint.
      required:
      - name
      - projects
      properties:
        name:
          type: string
          description: The name of the team.
          example: Example Title
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
          example: []
  parameters:
    TeamIdPathParam:
      name: team_id
      in: path
      description: The ID of the team.
      required: true
      schema:
        type: string
      example: '12345'
  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