Glyph Billing API

openapi: 3.2.0
info:
  title: Glyph Billing API
  description: 'A language for agents: encode content into the cheapest substrate the reading model can parse, with honest per-reader token math. Fillin is the retrieval product — a time-series index of the dev internet that closes the gap between an LLM''s training cutoff and now.'
  version: 0.1.0
tags:
- name: Billing
paths:
  /v1/billing/checkout:
    post:
      summary: Billing Checkout
      description: 'Mint a bearer + open a Stripe Checkout session.


        The bearer''s raw token is stashed in Stripe session metadata so the

        success page can reveal it once after payment. The hash is persisted on

        `checkout.session.completed` — see /v1/billing/webhook.'
      operationId: billing_checkout_v1_billing_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /v1/billing/subscribe:
    post:
      summary: Billing Subscribe
      description: 'Open a monthly-plan Stripe Checkout session (recurring card charge).


        Each paid invoice — first and every renewal — auto-credits the same

        bearer with the plan''s monthly query balance via the invoice.paid webhook.

        GET this route''s plan terms from /v1/billing/plan before subscribing.'
      operationId: billing_subscribe_v1_billing_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /v1/billing/plan:
    get:
      summary: Billing Plan
      description: Public terms of the flat monthly tier. No auth.
      operationId: billing_plan_v1_billing_plan_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Billing
  /v1/billing/webhook:
    post:
      summary: Billing Webhook
      description: 'Stripe webhook receiver. Verifies signature, credits the bearer ledger.


        Intentionally not rate-limited — Stripe retries on non-2xx and we already

        dedupe by event id, so a burst is harmless. The signature check rejects

        forged traffic before it touches any DB row.'
      operationId: billing_webhook_v1_billing_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Billing
  /v1/billing/transactions:
    get:
      summary: Billing Transactions
      description: 'Return the bearer''s purchase history — one row per Stripe credit event.


        Auth is "you must hold the bearer". 404 if unknown so a drive-by scanner

        can''t enumerate which keys exist by reading the response. Same hygiene as

        /v1/billing/balance.'
      operationId: billing_transactions_v1_billing_transactions_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /v1/billing/balance:
    get:
      summary: Billing Balance
      description: 'Return remaining balance for the bearer in the Authorization header.


        No auth ceremony beyond "you must hold the bearer". 404 if unknown so a

        drive-by scanner can''t enumerate which keys exist by reading the response.'
      operationId: billing_balance_v1_billing_balance_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /billing/success:
    get:
      summary: Billing Success
      description: 'One-shot reveal of the raw bearer key after a successful Stripe payment.


        Two layers of protection:

        - The Stripe session must be `paid` and livemode-matched.

        - The raw key is atomically claimed from the pending_reveal table — a

        second hit on this URL returns 410 Gone, so a leaked session_id

        (browser history, referrer header) can''t be replayed.'
      operationId: billing_success_billing_success_get
      parameters:
      - name: session_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SubscribeIn:
      properties:
        email:
          type: string
          maxLength: 320
          minLength: 3
          title: Email
      type: object
      required:
      - email
      title: SubscribeIn
    CheckoutIn:
      properties:
        email:
          type: string
          maxLength: 320
          minLength: 3
          title: Email
        usd_amount:
          type: number
          maximum: 10000.0
          exclusiveMinimum: 0.0
          title: Usd Amount
      type: object
      required:
      - email
      - usd_amount
      title: CheckoutIn
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer