Glyph Retrieve API

openapi: 3.2.0
info:
  title: Glyph Retrieve 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: Retrieve
paths:
  /v1/retrieve:
    post:
      summary: Retrieve Route
      description: 'One retrieval, one substrate out. Pass `model_id` or `cutoff` (explicit

        cutoff wins). `substrate` selects the form:


        - "text" (default): raw result pieces — identical payload to POST /query.

        - "glyph" : result pieces rendered as a VLM-readable photo-glyph.

        - "answer" : a citation-rich synthesized answer (needs an LLM key).

        - "auto" : pick the cheapest *legible* substrate for `reader`''s token

        billing (text on pixel-billed readers like Claude/GPT, dense

        glyph on flat-tile readers like Gemini/Qwen, answer for weak

        tool-callers). The response always carries a `selection`

        object {substrate, reader, rationale, estimates} explaining

        the choice from the honest token math.


        Pricing (kept consistent with the dedicated endpoints): resolving to text or glyph

        bills the flat /query rate; resolving to answer bills the answer rate. Because the

        auth dependency must charge before the substrate is known, this route charges the

        (higher) answer rate up front and REFUNDS the delta when the chosen substrate is

        text/glyph — to the x402 payer or the Stripe-funded bearer alike — so the caller pays

        exactly the right rate on either rail and is never undercharged. "Sign for the max,

        settle down" is also the only model x402 allows: a nonce authorizes exactly one spend,

        so a post-hoc answer upcharge would need a second signed handshake or an unsigned

        debit (a trust-on-header regression). The existing refund-on-error pattern is

        preserved for failures.'
      operationId: retrieve_route_v1_retrieve_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Retrieve
components:
  schemas:
    QueryIn:
      properties:
        cutoff:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cutoff
          description: ISO8601 training cutoff. Documents with published_at strictly after this instant are returned. Optional when model_id is set; an explicit cutoff wins if both are sent.
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
          description: Catalog model id (for example claude-sonnet-5, gpt-5.4, gemini-2.5-pro, llama-4-scout, grok-4.6). Resolves to that model's training cutoff when cutoff is omitted. See data/model_cutoffs.json.
        query:
          type: string
          maxLength: 512
          minLength: 1
          title: Query
          description: What topic / question
        k:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: K
          default: 10
        glyph:
          type: boolean
          title: Glyph
          description: If true, also return the result pieces rendered as a photo glyph (a dense, VLM-readable image) under the `glyph` field. Lets a vision model read results as one image. See /v1/glyph for image bytes.
          default: false
        glyph_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Glyph Tier
          description: 'Glyph density tier: ''6x'' | ''10x'' | ''15x''. Default ''10x''.'
        sources:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Sources
          description: 'Optional list of source names to restrict retrieval. Each must be a known source from the ingest registry (e.g. ''cves'', ''papers'', ''frontier'', ''arena'', ''arxiv'', ''rss'', ''hackernews'', ''github_releases''). When omitted, all sources are searched. Pricing is unchanged: a filtered /query is billed at the flat /query rate. For per-slice pricing, use the dedicated /query/{slice} routes.'
        substrate:
          type: string
          title: Substrate
          description: 'Delivery substrate for POST /v1/retrieve: ''text'' | ''glyph'' | ''answer'' | ''auto''. ''auto'' runs one retrieval and returns whichever substrate is cheapest for your reader model''s token billing (text on Claude/GPT pixel billing, dense glyph on Gemini/Qwen flat-tile billing, a synthesized answer for weak tool-callers). Ignored by /query, /answer, /v1/glyph.'
          default: text
        reader:
          anyOf:
          - type: string
          - type: 'null'
          title: Reader
          description: Your reader model, used by substrate='auto' to pick the cheapest legible form (e.g. 'claude', 'gemini', 'qwen2.5-vl', 'gpt-4o', 'llama-3.3'). If omitted, the server auto-detects it from the 'X-Reader-Model' request header (declare it once at the transport layer) or the User-Agent; an unidentified caller is treated as pixel-billed (the safe default — auto returns text rather than overclaim a saving). Ignored unless substrate='auto'.
        verbatim:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Verbatim
          description: 'For substrate=''auto'': set true if you need exact/verbatim text or code (auto then never picks glyph, which paraphrases). None auto-detects from the result sources/content. Ignored unless substrate=''auto''.'
      type: object
      required:
      - query
      title: QueryIn
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer