Glyph Encode API

openapi: 3.2.0
info:
  title: Glyph Encode 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: Encode
paths:
  /v1/encode:
    post:
      summary: Encode Route
      description: 'Bring your own text -> the cheapest substrate for your reader, with the

        honest per-reader-class token manifest. Billed at the flat /query rate

        regardless of which substrate is chosen (text and glyph cost the same

        here — there is no differential ''answer'' substrate to charge-then-refund

        for, unlike /v1/retrieve).'
      operationId: encode_route_v1_encode_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncodeIn'
        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:
      - Encode
  /v1/encode/sample:
    post:
      summary: Encode Sample Route
      description: 'Free, no-auth, no-corpus proof: paste YOUR OWN text, see it encoded and

        the honest token math, before paying anything. Byte-capped against abuse.

        Same lesson as /v1/glyph/sample: a stranger needs to see a real artifact

        of their own content, not a canned demo, to trust the pricing.'
      operationId: encode_sample_route_v1_encode_sample_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncodeIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Encode
components:
  schemas:
    EncodeIn:
      properties:
        text:
          anyOf:
          - type: string
            maxLength: 40000
          - type: 'null'
          title: Text
          description: Text to encode. Provide this or `texts`, not both.
        texts:
          anyOf:
          - items:
              type: string
              maxLength: 40000
            type: array
            maxItems: 50
          - type: 'null'
          title: Texts
          description: Multiple texts, joined as one document. Provide this or `text`, not both. Each item and the joined total are still bounded by the same character cap as `text`.
        reader:
          anyOf:
          - type: string
          - type: 'null'
          title: Reader
          description: Your reader model (e.g. 'claude', 'gemini', 'qwen2.5-vl', 'gpt-4o'). If omitted, inferred from the 'X-Reader-Model' request header or the User-Agent; an unidentified caller is treated as pixel-billed (text).
        substrate:
          type: string
          title: Substrate
          description: '''auto'' (default; picks the cheapest legible substrate for `reader`) | ''text'' | ''glyph''.'
          default: auto
        verbatim:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Verbatim
          description: Set true if this text must stay exact (code, hashes, quotes) — auto then never picks glyph, which paraphrases. None auto-detects fenced code blocks.
        tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier
          description: 'Glyph density tier override for substrate=''glyph'': ''6x'' | ''10x'' | ''15x''. Ignored for substrate=''auto'' — the picker''s own tier is used there so the claimed token estimate always matches the rendered artifact.'
      type: object
      title: EncodeIn
    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