# Krawl

> Krawl is an autonomous deep-research agent API. It runs recursive
> breadth×depth tree search, synthesizes findings into a cited markdown
> report, and streams progress via Server-Sent Events. Built for AI agents.

## API

- Base URL: https://api.krawl.sh
- OpenAPI 3.1: https://docs.krawl.sh/openapi.json
- Docs site: https://docs.krawl.sh
- Long-form context (this site, plain text): https://docs.krawl.sh/llms-full.txt
- Auth (.md fragment): https://krawl.sh/auth.md
- Status: https://docs.krawl.sh/status and https://docs.krawl.sh/status.json

## Authentication

Two paths — pick one:
- API key on `X-API-Key` header. Mint a no-signup demo key:
  `curl -X POST https://api.krawl.sh/auth/demo-key`
- x402 keyless pay-per-request in USDC on Base. Hit a research endpoint
  without a key to receive a 402 challenge; sign + retry with `X-PAYMENT`.

## Primary endpoints

- POST https://api.krawl.sh/research                  (SSE, deep/quick)
- POST https://api.krawl.sh/research/upload           (SSE, multipart)
- POST https://api.krawl.sh/research/async            (queue + poll)
- POST https://api.krawl.sh/research/batch            (up to 20 jobs)
- POST https://api.krawl.sh/v1/chat/completions       (OpenAI shim)
- POST https://api.krawl.sh/search                    (single-shot)
- GET  https://api.krawl.sh/templates                 (8 prebuilt patterns)
- GET  https://api.krawl.sh/results/{id}              (fetch report)
- GET  https://api.krawl.sh/results/{id}/export       (pdf|html|md|docx|slides)
- GET  https://api.krawl.sh/audit/{id}                (full audit trail)
- GET  https://api.krawl.sh/usage                     (quota + spend)
- GET  https://api.krawl.sh/discovery/resources       (x402 catalog)

## MCP

Krawl exposes its research tools over the Model Context Protocol on three
surfaces:

- MCP (docs surface): https://docs.krawl.sh/mcp
- MCP server card:    https://docs.krawl.sh/.well-known/mcp/server-card.json
- MCP (product):      https://api.krawl.sh/mcp
- WebMCP (browser):   https://krawl.sh/webmcp.js
- Tools (current): research, quick_search, ask_krawl
- Tools (full v1): research, quick_search, ask_krawl, list_lookouts,
  get_lookout, run_lookout, export_result, get_usage, get_memory,
  compare_results
- Transport: Streamable HTTP (POST) + SSE (GET)
- Protocol version: 2025-06-18
- Claude Code install: `npx skills add ravidsrk/krawl-agents`

## SSE events

The /research SSE stream emits: session, plan, perspectives, thinking,
query, source, content, browse_page, x_search, node_started, node_completed,
learning, gap_detected, outline_updated, citation_verified, report_chunk,
review_pass, chart, structured_output, memory_recall, document, audit,
steer, usage, changes_since_last, result, done, error. Full catalog with
sample payloads: https://docs.krawl.sh/docs/sse-events.

## Cookbook (runnable recipes)

- OpenAI Agents SDK (Python):  https://docs.krawl.sh/docs/cookbook/openai-agents-sdk
- Anthropic via MCP (Python):  https://docs.krawl.sh/docs/cookbook/anthropic-via-mcp
- Vercel AI SDK streamText:    https://docs.krawl.sh/docs/cookbook/vercel-ai-sdk-streamtext
- LangChain BaseRetriever:     https://docs.krawl.sh/docs/cookbook/langchain-retriever
- CrewAI tool wrapper:         https://docs.krawl.sh/docs/cookbook/crewai-tool

## Trust & benchmarks

- Trust + methodology: https://docs.krawl.sh/docs/trust
- Benchmarks (FRAMES, SimpleQA, FinSearchComp + Krawl Crypto Research Bench):
  https://docs.krawl.sh/docs/benchmarks

## Pricing (x402, atomic USDC units)

- Quick krawl (mode=quick): 1000000 ($1.00)
- Deep krawl (mode=deep):   5000000 ($5.00)

## Rate limits

Default: 5 req/min/IP. 429 responses carry Retry-After. Honor it.