# Krawl

> Deep research API that produces 50+ source reports in 90 seconds with full citations.

## Overview

Krawl is an autonomous research agent API. It searches the web, X/Twitter, GitHub, academic papers, crypto/DeFi data, and community sources in parallel, then synthesizes findings into a comprehensive markdown report with inline citations and source verification.

## When to Use Krawl

- You need comprehensive research with cited sources on any topic
- You want to analyze crypto tokens, DeFi protocols, or on-chain activity
- You need to monitor topics with scheduled research (lookouts)
- You want structured data extraction with confidence scores
- You need to research across multiple source types simultaneously
- You want a research API your agents or apps can call programmatically

## When NOT to Use Krawl

- Simple factual queries (use a search engine instead)
- Real-time price data (use CoinGecko/CoinMarketCap directly)
- Image or video search
- Personal data lookups

## Key Capabilities

- Deep multi-source research (web, X, GitHub, academic, crypto, media, community)
- 50+ verified sources per report with inline citations
- 90-second report generation with real-time SSE streaming
- Structured output with JSON Schema — per-field citations and confidence scores
- Conversational follow-up research with session memory
- Document upload + research (PDF, DOCX, TXT)
- Research templates for repeatable workflows
- Lookout scheduling (hourly/daily/weekly automated research)
- Knowledge base / persistent memory
- Voice input and text-to-speech output

## API Reference

- Base URL: [https://api.krawl.sh](https://api.krawl.sh)
- Auth: API key via `X-API-Key` header
- OpenAPI spec: [https://api.krawl.sh/openapi.json](https://api.krawl.sh/openapi.json)
- Interactive docs: [https://api.krawl.sh/docs](https://api.krawl.sh/docs)
- Full documentation: [https://docs.krawl.sh](https://docs.krawl.sh)

## Primary Endpoints

- `POST /research` — Execute deep research, returns SSE event stream
- `POST /research/upload` — Research with document uploads
- `POST /ask` — NLWeb natural language query endpoint
- `POST /search` — Single-source search
- `GET /results` — List past research results
- `GET /results/{id}` — Get a specific result
- `GET /results/{id}/export` — Export as PDF or markdown
- `POST /auth/demo-key` — Get a free demo API key (no auth required)
- `POST /auth/keys` / `GET /auth/keys` — API key management (admin only, `X-Admin-Key`); `DELETE /auth/keys` — self-service revoke of the `X-API-Key` key
- `GET /usage` — Current monthly usage rollup (tokens, USD cost, quota)
- `GET /usage/events` — Paginated per-request usage events
- `POST /billing/checkout` — Stripe Checkout (upgrade to Pro)
- `POST /billing/portal` — Stripe billing portal
- `GET /health` — API health check

## Authentication

Three ways to authenticate:

1. **API key** — issued instantly at [https://krawl.sh](https://krawl.sh) or via `POST /auth/demo-key` (no signup). Keys look like `krawl_live_...`, `krawl_demo_...`, `krawl_test_...`. Include as header:

   ```
   X-API-Key: your_api_key_here
   ```

2. **x402 pay-per-request** — autonomous agents can pay per request in USDC on Base with no account. Call a research endpoint with no `X-API-Key` → `HTTP 402` with `{x402Version:1, error, accepts:[...]}` → sign an EIP-3009 USDC authorization → retry with a base64 `X-PAYMENT` header → receive the stream plus an `X-PAYMENT-RESPONSE` header. Prices: $5.00 deep / $1.00 quick (USDC, network `base`, scheme `exact`). `POST /research`, `POST /research/upload`, and `POST /templates/{id}/research` accept either an API key or x402.

## Example API Call

```bash
# Get a demo key
curl -X POST https://api.krawl.sh/auth/demo-key

# Run research
curl -X POST https://api.krawl.sh/research \
  -H "X-API-Key: demo_xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"query": "DeFi lending protocol comparison", "mode": "crypto"}'
```

## Research Modes

- `deep` — Full multi-source recursive research (default)
- `quick` — Fast single-pass research
- `crypto` — Cryptocurrency/DeFi focused
- `token-analysis` — Token-specific deep analysis
- `protocol-research` — DeFi protocol analysis
- `whale-tracking` — On-chain whale activity
- `narrative` — Market narrative detection
- `risk-assessment` — Risk analysis
- `yield-strategy` — DeFi yield optimization

## Source Types

- `web` — Exa, Tavily, Serper, Brave, DuckDuckGo
- `x` — X/Twitter via xAI
- `github` — GitHub code and repos
- `academic` — PubMed, arXiv
- `crypto` — CoinGecko, DeFiLlama
- `media` — News outlets
- `community` — Reddit, Hacker News

## Plans & Rate Limits

Quotas are per month; rate limits are per plan.

| Plan | Deep krawls/mo | Search credits/mo | Rate limit |
|------|----------------|-------------------|------------|
| demo | 5 | 100 | 5/hour (≈24h key) |
| free | 25 | 1,000 | 10/min |
| payg | unlimited (metered) | unlimited (metered) | 60/min |
| pro | unlimited | unlimited | 120/min |

Quota exhausted (demo/free) → `HTTP 402 {"error":"quota_exceeded", ...}`. payg/pro never hit quota. Usage is queryable via `GET /usage` and streamed as a terminal `usage` SSE event (includes `cost_usd` and `ceiling_hit`). Each request has a hard LLM cost ceiling: $2.50 deep / $0.40 quick.

## Error Handling

All errors return structured JSON:
```json
{
  "error_code": "NOT_FOUND",
  "message": "Resource not found",
  "detail": "Result abc123 not found",
  "retry_after": null
}
```

Error codes: `NOT_FOUND`, `RATE_LIMITED`, `VALIDATION_ERROR`, `INTERNAL_ERROR`

## SDKs & CLI

- Python SDK: `pip install krawl`
- Node.js SDK: `npm install @krawl/sdk`
- CLI: `pip install krawl-cli`

## MCP Server

MCP server (Streamable HTTP / JSON-RPC 2.0) for Claude, ChatGPT, Cursor, and other AI agents.

- Server URL: [https://api.krawl.sh/mcp](https://api.krawl.sh/mcp)
- Manifest: [https://krawl.sh/.well-known/mcp/manifest.json](https://krawl.sh/.well-known/mcp/manifest.json)
- Server card: [https://krawl.sh/.well-known/mcp/server-card.json](https://krawl.sh/.well-known/mcp/server-card.json)
- Tools: `research` (deep cited report), `quick_search` (single-source), `ask_krawl` (capability routing)

## How Agents Should Interact

1. Discover via this file, [agent.json](https://krawl.sh/agent.json), and the [OpenAPI spec](https://api.krawl.sh/openapi.json).
2. Authenticate: free demo key via `POST /auth/demo-key`, or keyless x402 — see [auth.md](https://krawl.sh/auth.md).
3. Call the MCP server or `POST /research`; stream SSE to the terminal `result` event.

Full agent manual: [llms-full.txt](https://krawl.sh/llms-full.txt). Per-area context: [api/llms.txt](https://krawl.sh/api/llms.txt).

## Links

- Website: [https://krawl.sh](https://krawl.sh)
- API Docs: [https://docs.krawl.sh](https://docs.krawl.sh)
- GitHub: [https://github.com/ravidsrk/krawl](https://github.com/ravidsrk/krawl)
- AGENTS.md (coding-agent guide): [https://github.com/ravidsrk/krawl/blob/main/AGENTS.md](https://github.com/ravidsrk/krawl/blob/main/AGENTS.md)
- OpenAPI: [https://api.krawl.sh/openapi.json](https://api.krawl.sh/openapi.json)
- Agent Mode: [https://krawl.sh/?mode=agent](https://krawl.sh/?mode=agent)
- Auth guide: [https://krawl.sh/auth.md](https://krawl.sh/auth.md)
- Full manual: [https://krawl.sh/llms-full.txt](https://krawl.sh/llms-full.txt)
- Comparison: [https://krawl.sh/compare](https://krawl.sh/compare)
- Skills: [https://krawl.sh/skill.md](https://krawl.sh/skill.md), [https://krawl.sh/skill-crypto.md](https://krawl.sh/skill-crypto.md)