Researcher Docs

export RESEARCHER_BASE_URL="https://researcher.now"
export RESEARCHER_TOKEN="${RESEARCHER_TOKEN:-$RESEARCHER_API_KEY}"

# Single URL: article, YouTube/X video, or podcast episode — answers in seconds
curl -sS -X POST "$RESEARCHER_BASE_URL/v1/analyze" \
  -H "Authorization: Bearer $RESEARCHER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

# Deep multi-source research — durable run, cited report
curl -sS -X POST "$RESEARCHER_BASE_URL/v1/runs" \
  -H "Authorization: Bearer $RESEARCHER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-123" \
  -d '{
    "source": {"type": "topic", "topic": "recent advances in battery recycling"},
    "instructions": "Return the main technical bottlenecks, best sources, and open questions.",
    "limits": {"maxCostUsd": 10}
  }'

POST /v1/analyze with {"url": "..."} responds in seconds. Article URLs return reader-grade formatted markdown plus the finished structured analysis (claims, facts, quantitative data, stakeholder positions, quotes with attribution). YouTube videos and X/Twitter video posts return the full transcript with speaker-aware quotes plus the same analysis. The run then continues to a full synthesized report on the same viewerUrl — always surface that link to the user, exactly as returned.

curl -sS -X POST "$RESEARCHER_BASE_URL/v1/analyze" \
  -H "Authorization: Bearer $RESEARCHER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/post"}'

• Podcasts defer. Spotify and Apple Podcasts episode URLs always answer fast with a deferred run (deferred: true, reason: "podcast") — audio transcription takes minutes. The response returns the resolved episode title and run reference; the transcript and analysis land on the run. Media too long for the synchronous window defers the same way, and "defer": true requests that behavior explicitly.
• Retries coalesce. Concurrent duplicate analyze calls (same caller + URL) coalesce onto one execution. If a call 502s, check GET /v1/runs before retrying — the run very likely exists and is processing.
• Billing is usage-settled. Each analyze call authorizes a $5 budget session and settles to actual usage at close-out (unused budget returned). The response's costUsd is only what was charged at response time (0 for budget sessions) — quote estimatedCostUsd and read the settled cost from the run.
• Status tells you what's next. "running" means the report is being written; "awaiting_funding" means the analysis was a free preview — relay the viewerUrl so the user can fund and finish the report, or POST /v1/runs/:id/start.

export RESEARCHER_TOKEN="rk_..."
codex mcp add researcher-now --url https://researcher.now/mcp --bearer-token-env-var RESEARCHER_TOKEN

Current tools: analyze_article, analyze_video, deep_research, research_status, and recall_research. analyze_article takes any article URL; analyze_video takes a YouTube video, X/Twitter video post, or Spotify / Apple Podcasts episode URL (podcast episodes answer fast with a deferred run — the transcript and analysis land on the run). Both return formatted markdown or a full transcript plus the finished structured analysis and a viewerUrl agents must share with the user; deep_research returns a cited, synthesized research report plus watchUrl/viewerUrl agents must share with the user, and takes a topic argument only in this production version.

Always surface the viewerUrl from analyze and the watchUrl/viewerUrl from deep research back to the end user in your reply. These are durable, shareable research artifacts the user expects to open, share, and revisit. Do not swallow these links.

Run Analyst chat, direct URL/feed/video run ingestion, source mutation, destructive controls, account-key creation, webhooks, entities, and admin/operator paths are intentionally left on REST or deferred until their billing and URL-safety invariants are complete.

1. Formulating plan. The worker turns the prompt into a structured plan and contract.
2. Acquiring sources. Search, direct URLs, YouTube transcripts, and library recall populate candidates.
3. Extracting evidence. Source-level LLM records capture claims, caveats, metrics, and diagnostics.
4. Analyzing corpus. Records are merged into claims, comparisons, gaps, and source coverage.
5. Writing report. The report follows the customer output contract and stores artifacts.
6. Completing or continuing. If budget is reached after usable evidence exists, Researcher writes the best budget-limited report and leaves continuation as the next paid action.