CueFrame Fonts API

openapi: 3.2.0
info:
  title: Cueframe Ai Fonts API
  version: v1
  contact:
    name: CueFrame
    url: https://cueframe.ai
    email: support@cueframe.ai
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged fonts across 2 of this provider''s published API definitions: cueframe-ai-openapi.json, cueframe-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cueframe.ai
  description: Production
tags:
- name: fonts
paths:
  /v1/fonts/search:
    post:
      operationId: searchFonts
      tags:
      - fonts
      summary: Search web font families by name/style
      description: 'Search the Google Fonts web-font catalog by keyword. Returns matching font families (family name + category + available variants + a css2 stylesheet URL). DISCOVERY ONLY, and this is NOT the set the renderer can draw: a cloud render draws only the faces GET /v1/fonts lists, or a face sealed in a brand kit font asset. Naming any other family in captions/params fails validate_composition with font_not_reproducible. Read GET /v1/fonts to choose a family AND an admitted weight and style before authoring. Read-only and free; results are cached server-side. An empty `results` array means no match (or the upstream catalog was unavailable).'
      security:
      - bearerAuth: []
      - oauth2:
        - media:read
      - x402: []
      x-permissions:
        media:
        - read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FontSearchRequest'
      responses:
        '200':
          description: Matching web font families.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FontSearchResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: 'Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).'
          headers:
            Payment-Required:
              description: Base64 x402 v2 PaymentRequired envelope — the same challenge as the body, for clients that read it off the header.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402PaymentRequired'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/fonts:
    get:
      operationId: listRenderFonts
      tags:
      - fonts
      summary: List the font faces the renderer can actually draw
      description: 'The renderer''s admitted font set: per family the exact name authoring accepts, the weight ranges a shipped file declares, the styles bytes exist for, the caption default weights, and whether the bytes are bundled or an aliased metric-compatible stand-in. Choose from here and validate_composition will not refuse the face. Unlike POST /fonts/search (which searches the GOOGLE catalog) this is what the render page can rasterize. `manifestVersion` identifies the exact table and moves only when the admitted set does. Covers the BUNDLED set only — a brand kit''s sealed faces are per-org and per-render.'
      security:
      - bearerAuth: []
      - oauth2:
        - media:read
      - x402: []
      x-permissions:
        media:
        - read
      responses:
        '200':
          description: The renderer's admitted font faces.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderFontsResponse'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: 'Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).'
          headers:
            Payment-Required:
              description: Base64 x402 v2 PaymentRequired envelope — the same challenge as the body, for clients that read it off the header.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402PaymentRequired'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
components:
  schemas:
    FontSearchRequest:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 200
        perPage:
          type: integer
          exclusiveMinimum: 0
          maximum: 50
      required:
      - query
      additionalProperties: false
      description: POST /fonts/search body.
    FontSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              family:
                type: string
              category:
                type: string
              variants:
                type: array
                items:
                  type: string
              cssUrl:
                type: string
              previewText:
                type: string
            required:
            - family
            additionalProperties: false
      required:
      - results
      additionalProperties: false
      description: POST /fonts/search response.
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable machine-readable error code per §Error Model.
            message:
              type: string
              description: Human-readable message.
            contract:
              type: string
              description: Contract version that produced this verdict. If it differs between two calls, the rules changed underneath you, not your request.
            contractVersion:
              type: string
              description: 'Version of the published `@cueframe/api-contract` this server implements. Compare it with the `contractVersion` of the package your client was generated from: a higher value here means the server has moved ahead of your document.'
            details:
              description: Optional context (currentEtag, projectIds, retryAfter, …).
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          - contract
          - contractVersion
          description: Standard API error envelope.
      required:
      - error
      description: Error envelope used by every non-2xx response.
    X402PaymentRequired:
      type: object
      title: X402PaymentRequired
      description: x402 v2 PaymentRequired challenge — the body of a 402 on a priced operation.
      properties:
        x402Version:
          type: integer
          const: 2
        accepts:
          type: array
          description: Accepted payment requirements. Read `accepts[0]` for scheme (`exact` for a fixed price, `upto` for a measured one), network (CAIP-2), asset, amount and payTo.
          items:
            type: object
        error:
          type: string
          description: Human-readable reason.
      required:
      - x402Version
      - accepts
    RenderFontsResponse:
      type: object
      properties:
        manifestVersion:
          type: string
          description: Identifies this exact face table. Derived from the table's own content, so it moves when and only when the admitted set moves. Record it beside a composition to state which face table a font choice was validated against.
        families:
          type: array
          items:
            type: object
            properties:
              family:
                type: string
                description: The family name authoring accepts VERBATIM — card, caption and scene text alike.
              weights:
                type: array
                items:
                  type: object
                  properties:
                    min:
                      type: number
                    max:
                      type: number
                  required:
                  - min
                  - max
                  additionalProperties: false
                description: The weights a shipped file declares. A static face has min === max; a variable face gives its declared wght axis range. Any weight inside a range renders; anything outside every range is REFUSED, never synthesised.
              styles:
                type: array
                items:
                  type: string
                  enum:
                  - normal
                  - italic
                description: The styles bytes exist for in this family. Request italic only when this list includes 'italic'; the renderer refuses synthetic slant.
              captionDefaults:
                type: object
                properties:
                  base:
                    type: number
                  emphasis:
                    type: number
                required:
                - base
                - emphasis
                additionalProperties: false
                description: The weights a caption is drawn at when the style names none.
              origin:
                type: string
                enum:
                - bundled
                - aliased
                description: '''bundled'' = bytes ship in the render bundle. ''aliased'' = a metric-compatible binary stands in for the named family.'
            required:
            - family
            - weights
            - styles
            - captionDefaults
            - origin
            additionalProperties: false
      required:
      - manifestVersion
      - families
      additionalProperties: false
      description: 'GET /fonts response — the renderer''s admitted font set. Derived from the same table the font gate refuses by, so any family/weight/style here passes validation by construction. Covers the BUNDLED set only: a brand kit''s sealed faces are per-org and per-render.'
  securitySchemes:
    oauth2:
      type: oauth2
      description: Authorization code with PKCE (S256). Request explicit resource scopes for least privilege; identity-only grants retain account-level access.
      flows:
        authorizationCode:
          authorizationUrl: https://api.cueframe.ai/api/auth/mcp/authorize
          tokenUrl: https://api.cueframe.ai/api/auth/mcp/token
          scopes:
            media:read: Read media
            media:write: Modify media
            sessions:read: Read sessions
            sessions:write: Modify sessions
            projects:read: Read projects
            projects:write: Modify projects
            renders:read: Read renders
            renders:write: Modify renders
            webhooks:read: Read webhooks
            webhooks:write: Modify webhooks
            billing:read: Read billing
            billing:write: Modify billing
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cf_live_* or cf_test_*
      description: API key auth. Prefix `cf_live_` for production orgs, `cf_test_` for sandbox.
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment header (EIP-3009 USDC on Base; base64 PaymentPayload). Returned 402 Payment-Required if absent on priced endpoints.
x-refined-from:
- cueframe-ai-openapi.json
- cueframe-ai-openapi.yml