Getting Started

PrerequisitesCopy Anchor Link

• Python 3.12+
• PostgreSQL (for result persistence, memory, lookouts)
• API keys for search providers

Local DevelopmentCopy Anchor Link

# Clone and install
git clone https://github.com/ravidsrk/krawl.git
cd krawl/apps/api   # the API lives in apps/api
pip install -e ".[dev]"

Environment VariablesCopy Anchor Link

Create a .env file in apps/api/ (start from apps/api/.env.example). Krawl uses pydantic-settings and loads from .env automatically.

RequiredCopy Anchor Link

Required for LLM (at least one)Copy Anchor Link

OptionalCopy Anchor Link

Payments & Billing (optional)Copy Anchor Link

See Authentication and Payments & x402 for the full picture.

Tuning ParametersCopy Anchor Link

Model OverridesCopy Anchor Link

You can override the default models via env vars:

Run the ServerCopy Anchor Link

From apps/api/:

uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

Health CheckCopy Anchor Link

curl http://localhost:8080/health

{"status": "ok", "version": "0.2.0", "db": "ok", "uptime_seconds": 1234.5}

/health returns 200 when healthy and 503 (with "status": "degraded", "db": "error") when the database is unreachable.

First Research RequestCopy Anchor Link

curl -N -X POST http://localhost:8080/research \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the latest developments in AI agents?",
    "mode": "deep",
    "breadth": 4,
    "depth_levels": 3
  }'

The -N flag disables output buffering so you see SSE events as they arrive.

First Search RequestCopy Anchor Link

For a simple single-source search without the full research pipeline:

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI agents 2025",
    "source": "exa"
  }'

AuthenticationCopy Anchor Link

Krawl accepts three forms of authentication on its research endpoints:

1. API key — pass X-API-Key: krawl_live_…. Keys carry a plan with quotas and rate limits.
2. Demo key — grab one with no signup via POST /auth/demo-key, for trying the API.
3. Keyless x402 — an autonomous agent pays per request in USDC on Base, with no account at all (enabled when X402_PAY_TO is set).

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

# Use it
curl -H "X-API-Key: krawl_demo_…" -X POST https://api.krawl.sh/research \
  -H "Content-Type: application/json" \
  -d '{"query": "What is EIP-4844?", "mode": "quick"}'

The legacy KRAWL_DEV_KEY is a single shared key honored on the Krawl server for backward compatibility with internal tooling. When it is unset and no multi-user keys exist, the research endpoints are open and the server logs a warning on startup.

See Authentication for plans, quotas, and key management, and Payments & x402 for keyless agent payments.

CORSCopy Anchor Link

Default allowed origins:

• https://krawl.sh
• http://localhost:5173
• http://localhost:3000

Configure via CORS_ORIGINS env var (JSON array format).