QueryIn

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/glyphapi-dev/json-schema/glyphapi-dev-query-in-schema.json",
  "title": "QueryIn",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/glyphapi-dev-openapi.json#/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"
  ]
}