Glyph Probe API

openapi: 3.2.0
info:
  title: Glyph Probe 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: Probe
paths:
  /v1/probe:
    post:
      summary: Probe
      description: 'Free taste-test: one request per IP per UTC day, k=1, no payment.


        Pass model_id (catalog id) or cutoff (ISO-8601). Only documents with

        published_at strictly after that cutoff are returned. Omit both for the

        90-day default.


        Lets an agent verify the corpus has something useful for its question

        before opening a wallet. The quota is per-IP and per UTC day; the IP

        is resolved from CF-Connecting-IP (see real_client_ip). Burst is

        additionally capped by slowapi at 10/min as belt-and-suspenders.'
      operationId: probe_v1_probe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProbeIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Probe
components:
  schemas:
    Hit:
      properties:
        id:
          type: string
          title: Id
        source:
          type: string
          title: Source
        url:
          type: string
          title: Url
        published_at:
          type: string
          title: Published At
        title:
          type: string
          title: Title
        text:
          type: string
          title: Text
        score:
          anyOf:
          - type: number
          - type: 'null'
          title: Score
        severity_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Severity Score
        affected:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Affected
      type: object
      required:
      - id
      - source
      - url
      - published_at
      - title
      - text
      title: Hit
    ProbeIn:
      properties:
        cutoff:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cutoff
          description: ISO8601 training cutoff. Optional. Documents with published_at strictly after this instant are returned. Defaults to 90 days ago when both cutoff and model_id are omitted. An explicit cutoff wins if model_id is also set.
        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). When cutoff is omitted, retrieval uses that model's training cutoff. Unknown ids are rejected.
        query:
          type: string
          maxLength: 512
          minLength: 1
          title: Query
      type: object
      required:
      - query
      title: ProbeIn
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    QueryOut:
      properties:
        cutoff:
          type: string
          title: Cutoff
        query:
          type: string
          title: Query
        gap_days:
          type: number
          title: Gap Days
        results:
          items:
            $ref: '#/components/schemas/Hit'
          type: array
          title: Results
        top_score:
          type: number
          title: Top Score
          default: 0.0
        corpus_match:
          type: string
          title: Corpus Match
          default: none
        glyph:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Glyph
        substrate_estimate:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Substrate Estimate
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
        cutoff_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Cutoff Source
        model_cutoff:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Cutoff
        agent_next:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Agent Next
      type: object
      required:
      - cutoff
      - query
      - gap_days
      - results
      title: QueryOut
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer