openapi: 3.1.0
info:
  title: Figma Projects 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 related to Figma file resources

- name: Projects
  description: Operations for managing and retrieving project information
paths:
  /v1/projects/{project_id}/files:
    get:
      tags:
      - Files
      - Projects
      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'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'

components:
  securitySchemes:
    PersonalAccessToken:
      type: http
      scheme: bearer
      description: Personal access token for authentication
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://www.figma.com/api/oauth/token
          scopes:
            files:read: Read access to files

  parameters:
    ProjectIdPath:
      name: project_id
      in: path
      description: ID of the project to list files from
      required: true
      schema:
        type: string
      example: "12345678"

    BranchDataQuery:
      name: branch_data
      in: query
      description: >-
        Returns branch metadata in the response for each main file with a
        branch inside the project.
      schema:
        type: boolean
        default: false
      example: false

  schemas:
    ProjectFile:
      type: object
      description: A file within a project.
      properties:
        key:
          type: string
          description: The file's key.
          example: example_value
        name:
          type: string
          description: The file's name.
          example: Example Title
        thumbnail_url:
          type: string
          description: The file's thumbnail URL.
          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'
      required:
      - key
      - name
      - last_modified
      example:
        key: "abc123XYZ789"
        name: "Design System Components"
        thumbnail_url: "https://s3-alpha.figma.com/thumbnails/abc123-xyz789"
        last_modified: "2024-06-20T10:30:00Z"

    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"

    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

    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

    BadRequestError:
      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"

    ForbiddenError:
      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."

    TooManyRequestsError:
      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."

    InternalServerError:
      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"

  responses:
    GetProjectFilesResponse:
      description: Response from the GET /v1/projects/{project_id}/files endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetProjectFilesResponseBody'
          examples:
            GetProjectFilesSuccessExample:
              summary: Successful project files response
              value:
                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"

    BadRequestErrorResponse:
      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:
            $ref: '#/components/schemas/BadRequestError'
          examples:
            BadRequestExample:
              summary: Invalid project ID error
              value:
                error: true
                status: 400
                message: "Invalid project ID format"

    ForbiddenErrorResponse:
      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:
            $ref: '#/components/schemas/ForbiddenError'
          examples:
            ForbiddenExample:
              summary: Access denied error
              value:
                status: 403
                err: "Access denied. You do not have permission to access this project."

    TooManyRequestsErrorResponse:
      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:
            $ref: '#/components/schemas/TooManyRequestsError'
          examples:
            TooManyRequestsExample:
              summary: Rate limit exceeded error
              value:
                status: 429
                err: "Rate limit exceeded. Please wait before retrying."

    InternalServerErrorResponse:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
          examples:
            InternalServerErrorExample:
              summary: Internal server error
              value:
                status: 500
                err: "Internal server error"

  examples:
    GetProjectFilesSuccessExample:
      summary: Successful project files response
      value:
        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"