openapi: 3.1.0
info:
  title: Google Fonts Developer API
  description: >-
    The Google Fonts Developer API provides programmatic access to the metadata
    for all font families served by Google Fonts. It allows applications to query
    for available font families, retrieve details about variants, subsets,
    categories, and file URLs, and supports filtering, sorting, and variable font
    metadata.
  version: 1.0.0
  contact:
    name: Google Fonts
    url: https://developers.google.com/fonts
  license:
    name: Google APIs Terms of Service
    url: https://developers.google.com/terms
externalDocs:
  description: Google Fonts Developer API Documentation
  url: https://developers.google.com/fonts/docs/developer_api
servers:
  - url: https://www.googleapis.com
    description: Google Fonts API Server
tags:
  - name: Fonts
    description: Retrieve font family metadata
paths:
  /webfonts/v1/webfonts:
    get:
      operationId: listWebfonts
      summary: Google Fonts Developer List Web Fonts
      description: >-
        Retrieves the list of font families available from Google Fonts with
        metadata including variants, subsets, version, and file URLs.
      tags:
        - Fonts
      parameters:
        - name: key
          in: query
          description: API key for authentication
          required: true
          schema:
            type: string
        - name: sort
          in: query
          description: Sort order for the font list.
          schema:
            type: string
            enum:
              - alpha
              - date
              - popularity
              - style
              - trending
        - name: family
          in: query
          description: Filter by font family name.
          schema:
            type: string
        - name: subset
          in: query
          description: Filter by character subset (e.g., latin, greek, cyrillic).
          schema:
            type: string
        - name: category
          in: query
          description: Filter by font category.
          schema:
            type: string
            enum:
              - serif
              - sans-serif
              - monospace
              - display
              - handwriting
        - name: capability
          in: query
          description: >-
            Request additional capabilities like WOFF2, variable fonts (VF), or
            family tags.
          schema:
            type: string
            enum:
              - WOFF2
              - VF
              - FAMILY_TAGS
      responses:
        '200':
          description: Successful response with list of font families.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebfontList'
components:
  schemas:
    WebfontList:
      type: object
      properties:
        kind:
          type: string
          description: The type of resource (webfonts#webfontList).
        items:
          type: array
          items:
            $ref: '#/components/schemas/Webfont'
    Webfont:
      type: object
      properties:
        family:
          type: string
          description: The name of the font family.
        variants:
          type: array
          items:
            type: string
          description: Available font variants (e.g., regular, italic, 700).
        subsets:
          type: array
          items:
            type: string
          description: Supported character subsets.
        version:
          type: string
          description: The version of the font family.
        lastModified:
          type: string
          format: date
          description: Date the font was last modified.
        files:
          type: object
          additionalProperties:
            type: string
            format: uri
          description: Map of variant name to font file URL.
        category:
          type: string
          description: The category of the font family.
        kind:
          type: string
          description: The type of resource (webfonts#webfont).
        axes:
          type: array
          items:
            $ref: '#/components/schemas/Axis'
          description: Variable font axes (when capability=VF).
        tags:
          type: array
          items:
            type: string
          description: Font tags (when capability=FAMILY_TAGS).
    Axis:
      type: object
      properties:
        tag:
          type: string
          description: The axis tag (e.g., wght, wdth).
        start:
          type: number
          description: The minimum value of the axis.
        end:
          type: number
          description: The maximum value of the axis.