openapi: 3.1.0
info:
  title: Figma Styles 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: Keys
  description: Operations that use unique style keys for identification

- name: Styles
  description: Operations for managing and retrieving design styles
paths:
  /v1/styles/{key}:
    get:
      tags:
      - Keys
      - Styles
      summary: Figma Get Style
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      description: Get metadata on a style by key.
      operationId: getStyle
      x-microcks-operation:
        dispatcher: URI_PARTS
        dispatcherRules: key
        defaultResponse: GetStyleSuccessExample
      parameters:
      - $ref: '#/components/parameters/StyleKeyPath'
      responses:
        '200':
          $ref: '#/components/responses/GetStyleResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '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:
    StyleKeyPath:
      name: key
      in: path
      description: The unique identifier of the style.
      required: true
      schema:
        type: string
      example: "style_abc123xyz789"

  schemas:
    StyleType:
      type: string
      description: The type of style.
      enum:
      - FILL
      - TEXT
      - EFFECT
      - GRID
      example: FILL

    User:
      type: object
      description: A description of a user.
      properties:
        id:
          type: string
          description: Unique stable id of the user.
          example: abc123
        handle:
          type: string
          description: Name of the user.
          example: example_value
        img_url:
          type: string
          description: URL link to the user's profile image.
          example: https://www.example.com
      required:
      - id
      - handle
      - img_url
      example:
        id: "1234567890"
        handle: "John Designer"
        img_url: "https://s3-alpha.figma.com/profile/abc123-xyz789"

    PublishedStyle:
      type: object
      description: A set of published properties that can be applied to nodes.
      properties:
        key:
          type: string
          description: The unique identifier for the style
          example: example_value
        file_key:
          type: string
          description: The unique identifier of the Figma file that contains the style.
          example: example_value
        node_id:
          type: string
          description: ID of the style node within the figma file
          example: '500123'
        style_type:
          $ref: '#/components/schemas/StyleType'
        thumbnail_url:
          type: string
          description: A URL to a thumbnail image of the style.
          example: https://www.example.com
        name:
          type: string
          description: The name of the style.
          example: Example Title
        description:
          type: string
          description: The description of the style as entered by the publisher.
          example: A sample description.
        created_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time when the style was created.
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: The UTC ISO 8601 time when the style was last updated.
          example: '2026-01-15T10:30:00Z'
        user:
          $ref: '#/components/schemas/User'
        sort_position:
          type: string
          description: A user specified order number by which the style can be sorted.
          example: example_value
      required:
      - key
      - file_key
      - node_id
      - style_type
      - name
      - description
      - created_at
      - updated_at
      - user
      - sort_position
      example:
        key: "style_abc123xyz789"
        file_key: "file_def456uvw012"
        node_id: "1:2"
        style_type: FILL
        thumbnail_url: "https://s3-alpha.figma.com/thumbnails/style-abc123"
        name: "Primary Brand Color"
        description: "Main brand color used for primary actions and highlights"
        created_at: "2024-01-15T09:00:00Z"
        updated_at: "2024-06-20T14:30:00Z"
        user:
          id: "1234567890"
          handle: "John Designer"
          img_url: "https://s3-alpha.figma.com/profile/abc123-xyz789"
        sort_position: "a0"

    GetStyleResponseBody:
      type: object
      description: Successful response containing style metadata.
      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
        meta:
          $ref: '#/components/schemas/PublishedStyle'
      required:
      - status
      - error
      - meta
      example:
        status: 200
        error: false
        meta:
          key: "style_abc123xyz789"
          file_key: "file_def456uvw012"
          node_id: "1:2"
          style_type: FILL
          thumbnail_url: "https://s3-alpha.figma.com/thumbnails/style-abc123"
          name: "Primary Brand Color"
          description: "Main brand color used for primary actions and highlights"
          created_at: "2024-01-15T09:00:00Z"
          updated_at: "2024-06-20T14:30:00Z"
          user:
            id: "1234567890"
            handle: "John Designer"
            img_url: "https://s3-alpha.figma.com/profile/abc123-xyz789"
          sort_position: "a0"

    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

    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

    BadRequestError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayloadWithErr'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 400
        required:
        - status
      example:
        status: 400
        err: "Invalid style key 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 style."

    NotFoundError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayloadWithMessage'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 404
        required:
        - status
      example:
        error: true
        status: 404
        message: "Style not found"

    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:
    GetStyleResponse:
      description: Response from the GET /v1/styles/{key} endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetStyleResponseBody'
          examples:
            GetStyleSuccessExample:
              summary: Successful style metadata response
              value:
                status: 200
                error: false
                meta:
                  key: "style_abc123xyz789"
                  file_key: "file_def456uvw012"
                  node_id: "1:2"
                  style_type: FILL
                  thumbnail_url: "https://s3-alpha.figma.com/thumbnails/style-abc123"
                  name: "Primary Brand Color"
                  description: "Main brand color used for primary actions and highlights"
                  created_at: "2024-01-15T09:00:00Z"
                  updated_at: "2024-06-20T14:30:00Z"
                  user:
                    id: "1234567890"
                    handle: "John Designer"
                    img_url: "https://s3-alpha.figma.com/profile/abc123-xyz789"
                  sort_position: "a0"

    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 style key error
              value:
                status: 400
                err: "Invalid style key 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 style."

    NotFoundErrorResponse:
      description: The requested file or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
          examples:
            NotFoundExample:
              summary: Style not found error
              value:
                error: true
                status: 404
                message: "Style 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:
    GetStyleSuccessExample:
      summary: Successful style metadata response
      value:
        status: 200
        error: false
        meta:
          key: "style_abc123xyz789"
          file_key: "file_def456uvw012"
          node_id: "1:2"
          style_type: FILL
          thumbnail_url: "https://s3-alpha.figma.com/thumbnails/style-abc123"
          name: "Primary Brand Color"
          description: "Main brand color used for primary actions and highlights"
          created_at: "2024-01-15T09:00:00Z"
          updated_at: "2024-06-20T14:30:00Z"
          user:
            id: "1234567890"
            handle: "John Designer"
            img_url: "https://s3-alpha.figma.com/profile/abc123-xyz789"
          sort_position: "a0"