{"openapi":"3.1.0","info":{"title":"Researcher","version":"1.0.0","description":"Article and video analysis, not scraping: any URL returns a cleanly formatted article — any YouTube link a full transcript with speaker-aware quotes — plus finished structured analysis (claims, facts, quantitative data, stakeholder positions, quotes with attribution). Deep multi-source research returns a synthesized, cited Research Report. Consult durable expert personas grounded in their own writing and talks.","x-guidance":"Researcher turns a calling agent into a researcher. Three things to know:\n1) Analyze one URL — POST /v1/analyze with {\"url\":\"…\"}. Any article returns reader-grade markdown; any YouTube / X video / Spotify / Apple Podcasts URL returns a full speaker-aware transcript. Both come back with finished structured analysis (claims, facts, quantitative data, stakeholder positions, quotes) so you don't burn your own context window parsing raw pages. Synchronous; $1.00 per call. The same run then continues to a full cited report on the returned viewerUrl.\n2) Deep research — POST /v1/runs with {\"topic\":\"…\"}. Asynchronous multi-source synthesis across web, video, and feeds; returns runId + watchUrl/viewerUrl immediately, then writes a cited Research Report. Priced $1–$25 by depth (narrow/standard/wide); set limits.maxCostUsd to cap it.\n3) Ask a persona — POST /v1/entities/{slug}/chat with {\"message\":\"…\"}. Consult durable expert personas (list them free at GET /public/entities) and get an answer in their voice, grounded in their actual corpus, with citations. $0.25 quick / $1.00 deep.\nPayment: no key and no signup required — point any x402 / MPP wallet client at this origin and it pays per request off the 402 challenge (method=tempo on Tempo USDC). The first paid call returns a durable rk_ key in the X-Researcher-Agent-Key header; reuse it as Authorization: Bearer for reads and future calls. Always surface the returned viewerUrl / watchUrl back to the end user — they are durable, shareable artifacts. Full contract: https://researcher.now/agent.txt and https://researcher.now/llms.txt.","contact":{"email":"j@horyzon.co","url":"https://researcher.now"}},"servers":[{"url":"https://researcher.now"}],"x-service-info":{"name":"Researcher","categories":["ai","search","data"],"docs":{"homepage":"https://researcher.now","apiReference":"https://researcher.now/agent/","llms":"https://researcher.now/llms.txt"}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Customer API key (rk_…) sent as `Authorization: Bearer rk_…` from https://researcher.now/account/. Reads require a key; get one free on your first keyless paid call from the X-Researcher-Agent-Key response header, or sign up."}}},"paths":{"/v1/analyze":{"post":{"operationId":"analyzeUrl","summary":"Article and video analysis for one URL","description":"Article/Video Analysis. Any article URL returns reader-grade markdown plus finished structured analysis (claims, facts, quantitative data, stakeholder positions, quotes with attribution) in seconds; any YouTube URL returns a full speaker-aware transcript with the same analysis. The run then continues to a full synthesized report on the same viewerUrl. Not a DOM dump — the analysis is included, so you don't burn your own context window. Funded accounts are billed like any run: a $5 budget session settled to actual usage at close-out (unused budget returned). Anonymous callers pay via the MPP Payment challenge (no account): intent \"charge\" for a one-off call, or intent \"session\" to open a payment channel once and pay each call off-chain. Unfunded keyed accounts still get the analysis as a free preview that parks as awaiting_funding; fund from the run page (or POST /v1/runs/:id/start) to finish the report.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"URL to analyze: article, YouTube video, X/Twitter video post, or Spotify / Apple Podcasts episode"},"lang":{"type":"string","description":"Preferred transcript language"},"defer":{"type":"boolean","description":"Media only: skip the synchronous transcript and create the asynchronous run immediately (responds fast with deferred=true and the run reference)"}}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.00"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}],"amount":"1000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Researcher URL analysis (POST /v1/analyze)","intent":"charge","method":"tempo","offers":[{"amount":"1000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Researcher URL analysis (POST /v1/analyze)","intent":"charge","method":"tempo"},{"amount":"1000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Researcher URL analysis (POST /v1/analyze) — open a payment session once, each call deducts the per-call price off-chain","intent":"session","method":"tempo"}]},"responses":{"200":{"description":"Formatted content plus structured analysis, with durable runId and viewerUrl. status=running means the full report is being written to viewerUrl; status=awaiting_funding means the free preview is stored and the report finishes after funding. Media too long for the synchronous window returns deferred=true with the same runId/viewerUrl and no inline transcript — the run transcribes and analyzes asynchronously. Podcast episodes always take that deferred path (reason=podcast): audio transcription takes minutes and never fits the synchronous window.","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"Durable run id"},"kind":{"type":"string","enum":["article","video"]},"title":{"type":"string"},"viewerUrl":{"type":"string","description":"Public, shareable run viewer URL — surface this to the user"},"watchUrl":{"type":"string","description":"Public run viewer URL"},"markdown":{"type":"string","description":"Reader-grade article markdown (kind=article)"},"transcript":{"type":"string","description":"Full speaker-aware transcript (kind=video)"},"analysis":{"type":"object","description":"Structured analysis: claims, facts, quantitativeFacts, stakeholderPositions, quotes"},"status":{"type":"string","enum":["running","awaiting_funding"]},"deferred":{"type":"boolean"}},"required":["runId","viewerUrl"]}}}},"402":{"description":"Payment Required — MPP Payment challenge in WWW-Authenticate, account signup guidance in body (anonymous callers only)"}}}},"/v1/runs":{"post":{"operationId":"createResearchRun","summary":"Deep multi-source research run","description":"Asynchronous deep research across web, video, and feeds: returns runId, watchUrl, and viewerUrl immediately, then synthesizes a cited Research Report. Priced by depth ($1 narrow, $10 standard, $25 wide) against an MPP session budget; set limits.maxCostUsd to cap the price. No key required — pay the MPP session challenge from your wallet and the first paid run returns a durable rk_ key in the X-Researcher-Agent-Key header. Keyed callers without funds get a free preview that parks as awaiting_funding.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic"],"properties":{"topic":{"type":"string","description":"Research question or topic"},"depth":{"type":"string","enum":["narrow","standard","wide"]},"instructions":{"type":"string","description":"Optional steering for the report"},"limits":{"type":"object","properties":{"maxCostUsd":{"type":"number","description":"Budget ceiling in USD; you are never charged above it"}}}}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"1.00","max":"25.00"},"protocols":[{"mpp":{"method":"tempo","intent":"session","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}],"amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Deep research run, $1-$25 by depth","intent":"session","method":"tempo","offers":[{"amount":"1000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Deep research run, depth \"narrow\"","intent":"session","method":"tempo"},{"amount":"10000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Deep research run, depth \"standard\"","intent":"session","method":"tempo"},{"amount":"25000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Deep research run, depth \"wide\"","intent":"session","method":"tempo"}]},"responses":{"202":{"description":"Run accepted — poll runId or open watchUrl","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string","description":"queued | running | awaiting_funding"},"watchUrl":{"type":"string","description":"Public run viewer URL — surface this to the user"},"viewerUrl":{"type":"string"},"priceUsd":{"type":"string","description":"Planner price estimate"},"budgetUsd":{"type":"string","description":"Authorized budget ceiling"}},"required":["runId","watchUrl"]}}}},"402":{"description":"Payment Required — MPP session challenge or funding guidance"}}}},"/v1/entities/{slug}/chat":{"post":{"operationId":"askPersona","summary":"Consult an expert persona","description":"Ask a durable expert persona — Paul Graham, Warren Buffett, Elon Musk, Patrick Collison, Jeff Bezos, and more — a question and get an answer in their voice, grounded in their actual writing, talks, and posts, with citations. List available personas free at GET /public/entities. No key required: pay the flat per-question MPP session challenge from your wallet ($0.25 quick, $1.00 deep). Pass an optional sessionId to continue a conversation; the persona remembers the thread.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Persona slug from GET /public/entities, e.g. warren-buffett"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"The question to ask the persona"},"depth":{"type":"string","enum":["quick","deep"],"description":"quick (default) or deep wider retrieval for hard questions"},"sessionId":{"type":"string","description":"Optional session id from a prior consult to continue the conversation"}}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.25","max":"1.00"},"protocols":[{"mpp":{"method":"tempo","intent":"session","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}],"amount":"250000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Persona consult, $0.25 quick / $1.00 deep","intent":"session","method":"tempo","offers":[{"amount":"250000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Persona consult (quick)","intent":"session","method":"tempo"},{"amount":"1000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Persona consult (deep)","intent":"session","method":"tempo"}]},"responses":{"200":{"description":"Answer in the persona's voice with citations and a sessionId","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","description":"The persona's answer in their voice"},"citations":{"type":"array","items":{"type":"object"},"description":"Source-grounded citations for the answer"},"sessionId":{"type":"string","description":"Carry into the next consult to continue the conversation"}},"required":["answer"]}}}},"402":{"description":"Payment Required — MPP session challenge for the flat per-question price (anonymous callers)"}}}},"/public/entities":{"get":{"operationId":"listPersonas","summary":"List consultable expert personas","description":"Free, public list of the durable expert personas you can consult with POST /v1/entities/{slug}/chat — each a research-grounded corpus of that person's own writing, talks, and posts. Returns slug, name, what they're known for, and corpus size.","security":[],"responses":{"200":{"description":"Public personas","content":{"application/json":{"schema":{"type":"object","properties":{"entities":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"subtitle":{"type":"string"},"avatarUrl":{"type":"string"}}}}}}}}}}}},"/v1/runs/{id}":{"get":{"operationId":"getResearchRun","summary":"Read a research run's status and results","description":"Progress, status, and results for a run by id, including the synthesized report and citations once terminal (succeeded, failed, cancelled). Surface any returned watchUrl/viewerUrl to the user.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Run id from POST /v1/analyze or POST /v1/runs"}],"responses":{"200":{"description":"Run object with status, watchUrl/viewerUrl, and (when terminal) report and usage"},"401":{"description":"Missing or invalid API key"}}}},"/v1/exports/pending":{"get":{"operationId":"listPendingExports","summary":"Agent inbox: unseen completed research runs","description":"Lists terminal runs (succeeded, failed, cancelled) no agent on the account has acknowledged yet — including runs started on the researcher.now web app, the API, or Discord. Free for authenticated keys. Acknowledge consumed entries with POST /v1/exports/ack {\"ids\":[...]} so they stop appearing.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum entries to return"}],"responses":{"200":{"description":"Pending export entries with id, runId, event, title, topic, and urls (watch, markdown, api)"}}}},"/v1/exports/ack":{"post":{"operationId":"ackExports","summary":"Acknowledge agent-inbox entries","description":"Marks pending agent-inbox export entries as seen so they stop appearing in GET /v1/exports/pending. Acknowledging is per-account; full run results stay available through the normal run endpoints.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Export entry ids from GET /v1/exports/pending"}}}}}},"responses":{"200":{"description":"Acknowledged count"}}}},"/v1/library/search":{"get":{"operationId":"searchLibrary","summary":"Search stored research memory","description":"Instantly recall stored Research Reports, claims, and evidence with citations. Free for authenticated keys — check research memory before paying for new work.","security":[{"apiKey":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Claim or topic to search for"}],"responses":{"200":{"description":"Matching claims and evidence with scores"}}}}}}