Figma Teams API

openapi: 3.1.0
info:
  title: Figma Teams 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: [email protected]

servers:
- url: https://api.figma.com
  description: Figma Production API Server

tags:
- name: Teams
  description: Operations for managing and retrieving team information
- name: Webhooks
  description: Operations for managing webhook subscriptions and notifications

paths:
  /v2/teams/{team_id}/webhooks:
    get:
      tags:
      - Teams
      - Webhooks
      summary: Figma Get Team Webhooks
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      description: Returns all webhooks registered under the specified team.
      operationId: getTeamWebhooks
      x-microcks-operation:
        dispatcher: URI_PARTS
        dispatcherRules: team_id
        defaultResponse: GetTeamWebhooksSuccessExample
      parameters:
      - $ref: '#/components/parameters/TeamIdPath'
      responses:
        '200':
          $ref: '#/components/responses/GetTeamWebhooksResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '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:
    TeamIdPath:
      name: team_id
      in: path
      description: ID of team to get webhooks for
      required: true
      schema:
        type: string
      example: "team_12345678"

  schemas:
    WebhookV2Event:
      type: string
      description: The event type that triggers the webhook.
      enum:
      - FILE_UPDATE
      - FILE_DELETE
      - FILE_VERSION_UPDATE
      - LIBRARY_PUBLISH
      - FILE_COMMENT
      example: FILE_UPDATE

    WebhookV2Status:
      type: string
      description: The current status of the webhook.
      enum:
      - ACTIVE
      - PAUSED
      example: ACTIVE

    WebhookV2:
      type: object
      description: A description of an HTTP webhook (from Figma back to your application)
      properties:
        id:
          type: string
          description: The ID of the webhook
          example: abc123
        event_type:
          $ref: '#/components/schemas/WebhookV2Event'
        team_id:
          type: string
          description: The team id you are subscribed to for updates
          example: '500123'
        status:
          $ref: '#/components/schemas/WebhookV2Status'
        client_id:
          type:
          - string
          - 'null'
          description: >-
            The client ID of the OAuth application that registered this webhook,
            if any
          example: '500123'
        passcode:
          type: string
          description: The passcode that will be passed back to the webhook endpoint
          example: example_value
        endpoint:
          type: string
          description: The endpoint that will be hit when the webhook is triggered
          example: example_value
        description:
          type:
          - string
          - 'null'
          description: >-
            Optional user-provided description or name for the webhook. This is
            provided to help make maintaining a number of webhooks more
            convenient. Max length 140 characters.
          example: A sample description.
      required:
      - id
      - event_type
      - team_id
      - status
      - client_id
      - passcode
      - endpoint
      - description
      example:
        id: "webhook_abc123xyz789"
        event_type: FILE_UPDATE
        team_id: "team_12345678"
        status: ACTIVE
        client_id: "oauth_client_xyz"
        passcode: "secret_passcode_123"
        endpoint: "https://api.myapp.com/figma/webhooks"
        description: "Webhook for design file updates"

    GetTeamWebhooksResponseBody:
      type: object
      description: Successful response containing team webhooks.
      properties:
        webhooks:
          type: array
          description: An array of webhooks.
          items:
            $ref: '#/components/schemas/WebhookV2'
          example: []
      required:
      - webhooks
      example:
        webhooks:
        - id: "webhook_abc123xyz789"
          event_type: FILE_UPDATE
          team_id: "team_12345678"
          status: ACTIVE
          client_id: "oauth_client_xyz"
          passcode: "secret_passcode_123"
          endpoint: "https://api.myapp.com/figma/webhooks"
          description: "Webhook for design file updates"
        - id: "webhook_def456uvw012"
          event_type: FILE_COMMENT
          team_id: "team_12345678"
          status: PAUSED
          client_id:
          passcode: "another_passcode_456"
          endpoint: "https://api.myapp.com/figma/comments"
          description:

    ErrorResponsePayload:
      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

    ForbiddenError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - 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 team's webhooks."

    NotFoundError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 404
        required:
        - status
      example:
        status: 404
        err: "Team not found"

    TooManyRequestsError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - 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/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 500
        required:
        - status
      example:
        status: 500
        err: "Internal server error"

  responses:
    GetTeamWebhooksResponse:
      description: Response from the GET /v2/teams/{team_id}/webhooks endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetTeamWebhooksResponseBody'
          examples:
            GetTeamWebhooksSuccessExample:
              summary: Successful team webhooks response
              value:
                webhooks:
                - id: "webhook_abc123xyz789"
                  event_type: FILE_UPDATE
                  team_id: "team_12345678"
                  status: ACTIVE
                  client_id: "oauth_client_xyz"
                  passcode: "secret_passcode_123"
                  endpoint: "https://api.myapp.com/figma/webhooks"
                  description: "Webhook for design file updates"
                - id: "webhook_def456uvw012"
                  event_type: FILE_COMMENT
                  team_id: "team_12345678"
                  status: PAUSED
                  client_id:
                  passcode: "another_passcode_456"
                  endpoint: "https://api.myapp.com/figma/comments"
                  description:

    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 team's webhooks."

    NotFoundErrorResponse:
      description: The requested file or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
          examples:
            NotFoundExample:
              summary: Team not found error
              value:
                status: 404
                err: "Team not found"

    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:
    GetTeamWebhooksSuccessExample:
      summary: Successful team webhooks response
      value:
        webhooks:
        - id: "webhook_abc123xyz789"
          event_type: FILE_UPDATE
          team_id: "team_12345678"
          status: ACTIVE
          client_id: "oauth_client_xyz"
          passcode: "secret_passcode_123"
          endpoint: "https://api.myapp.com/figma/webhooks"
          description: "Webhook for design file updates"
        - id: "webhook_def456uvw012"
          event_type: FILE_COMMENT
          team_id: "team_12345678"
          status: PAUSED
          client_id:
          passcode: "another_passcode_456"
          endpoint: "https://api.myapp.com/figma/comments"
          description: