retrieve_auto
Read-onlyIdempotent
One retrieval, auto-picked substrate — the MCP twin of HTTP POST /v1/retrieve with substrate="auto".
Requires $0.01–$0.05 USDC (x402) or an Authorization Bearer trial/paid key.
On payment_required, call fillin_probe then fillin_signup (POST /v1/signup)
for a free 20-query trial, or fillin_payment_challenge then retry with
X-Payer-Address, X-Payer-Nonce, X-Payer-Signature (or Bearer).
POST /v1/probe for 1 free taste/IP/day.
Runs a single post-cutoff retrieval, then returns whichever delivery substrate is
cheapest AND legible for your `reader` model's token billing:
- text — raw result pieces (Claude/GPT pixel billing, or any unknown reader).
- glyph — a dense photo-glyph image (Gemini/Qwen flat-tile billing) you read with
vision; the raw pieces ride along as a citation index.
- answer — a pre-cited synthesized paragraph (weak tool-callers; needs a server LLM key).
The trailing JSON block always carries a `selection` object
{substrate, reader, reader_class, tier, rationale, estimates} so the choice is
auditable from the honest token math — the same object the HTTP route returns. When the
pick is glyph, the page image(s) precede that JSON block.
Pricing matches /v1/retrieve: text/glyph bill the flat /query rate, answer bills the
answer rate. The answer rate is charged up front and the delta is refunded when the
pick resolves to text/glyph, so you always pay exactly the right rate.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | Number of documents to retrieve (1-12). | |
| query | Yes | Natural-language search query, max 512 chars. | |
| cutoff | Yes | Training cutoff as ISO-8601 date (e.g. 2026-01-01). Documents on or before this date are excluded. | |
| reader | No | Your reader model — used to auto-pick the cheapest legible substrate. Flat-tile billers ('gemini', 'qwen') can get a dense glyph; pixel billers ('claude', 'gpt-4o') get text; weak tool-callers ('llama', 'mistral', 'gemini-flash') get a synthesized answer. Unknown/None is treated as pixel-billed — the safe default (text), never an overclaimed saving. | |
| verbatim | No | Set true if you need exact/verbatim text or code (auto then never picks glyph, which paraphrases). None (default) auto-detects from result sources/content. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |