# know.fast — agent contract

Send a link. Know it. know.fast turns any URL (article, YouTube, X post,
podcast, paper, PDF) into a durable knowledge page plus a token-efficient
markdown packet built for agent relay — and links are unique, so anything
anyone has ever known answers instantly and free.

## The whole flow

1) POST https://know.fast/            (aliases: /v1/know, /v1/analyze)
   Content-Type: application/json
   Body: {"url": "<link>", "lang": "en"?, "defer": true?, "fresh": true?}

   LINKS ARE UNIQUE. A link anyone has already known answers INSTANTLY and
   FREE: {"cached": true, "costUsd": 0, "packet": "<markdown>", viewerUrl,
   markdownUrl}. When `packet` is present, ANSWER DIRECTLY FROM IT — no
   second fetch needed. Pass "fresh": true to re-read changed content
   (paid).

   First-ever links get known once, for everyone:
   - Articles usually return synchronously in seconds.
   - Video/podcast ALWAYS defers (transcription takes minutes):
     {"deferred": true, "viewerUrl": ...}. Relay viewerUrl immediately —
     it is the live page.

2) Deferred runs: poll GET https://know.fast/v1/runs/<runId>/job until
   {"status": "succeeded"}, then fetch the packet:
   GET https://know.fast/<slug>.md   (slug = the viewerUrl path)

   The packet: title, source URL, summary, key claims/facts inline, and
   pointers into the knowledge files below. Relay it directly.

## Knowledge files (per source, from the packet)

   GET https://know.fast/public/research-runs/by-slug/<slug>/sources/<id>/package
   - files/source/source.md          clean full text
   - files/evidence.json             graded claims / facts / quotes
   - files/transcript/transcript.md  timestamped transcript (media)
   - files/metadata.json             creator, type, word count, citation handle
   The package URL itself returns the manifest (all files + sha256).

## Auth + payment

- Cache hits and all knowledge reads are FREE, no key, no wallet.
- First-ever links: pay per call from a wallet (the 402 carries an x402/MPP
  session challenge; authorize it and the call proceeds; your first paid
  call returns a durable key in X-Researcher-Agent-Key — store it and send
  it as a Bearer token), or use a funded key. Articles quote ~$1.00; media
  costs more (transcription).

## Notes

- Idempotency-Key header is honored for 7 days — safe to retry.
- Every knowledge page is a durable, citable run; citation handle format:
  researcher:source:<sourceId>.
- MCP: connect to https://know.fast/mcp (streamable HTTP, keyless x402
  supported) — the server identifies as know.fast.
- Deep multi-source research, standing topics, and persona consults live on
  the parent stack: https://researcher.now/agent.txt