{
  "name": "Krawl",
  "description": "Deep research agent API that produces multi-source cited reports in 90 seconds with full citations. Searches the web, X/Twitter, GitHub, academic papers, and crypto/DeFi in parallel.",
  "version": "0.2.0",
  "api_base": "https://api.krawl.sh",
  "openapi_spec": "https://api.krawl.sh/openapi.json",
  "documentation": "https://docs.krawl.sh",
  "homepage": "https://krawl.sh",
  "idempotency": {
    "header": "Idempotency-Key",
    "ttl_seconds": 86400,
    "policy": "Eligible successful JSON responses only. Auth/key issuance (including /agent/auth), session-cookie, Authorization and legacy or unknown X-API-Key requests run live. ZDR, ephemeral exports, SSE, no-store and Set-Cookie responses are not cached. Excluded mutations can execute again on retry.",
    "details": "https://api.krawl.sh/openapi.json"
  },
  "authentication": {
    "methods": [
      "api_key",
      "x402",
      "demo_key"
    ],
    "type": "api_key",
    "header": "X-API-Key",
    "key_prefixes": [
      "krawl_live_",
      "krawl_demo_",
      "krawl_test_"
    ],
    "signup_url": "https://krawl.sh",
    "demo_key_endpoint": "POST https://api.krawl.sh/auth/demo-key",
    "x402": {
      "description": "Keyless pay-per-request. Call a research endpoint with no X-API-Key to get HTTP 402 with {x402Version:1, error, accepts:[PaymentRequirements]} (top-level). Sign an EIP-3009 USDC authorization and retry with a base64 X-PAYMENT header; the response echoes X-PAYMENT-RESPONSE.",
      "network": "base",
      "asset": "USDC",
      "scheme": "exact",
      "prices_usdc": {
        "deep": 5.0,
        "quick": 1.0
      },
      "endpoints": [
        "/research",
        "/research/upload",
        "/templates/{id}/research"
      ]
    }
  },
  "endpoints": [
    {
      "method": "POST",
      "path": "/research",
      "description": "Execute deep multi-source research. Returns SSE event stream with real-time progress and final markdown report with citations. Accepts X-API-Key OR x402 payment."
    },
    {
      "method": "POST",
      "path": "/research/upload",
      "description": "Research with document uploads (PDF, DOCX, TXT). Multipart form data. Accepts X-API-Key OR x402 payment."
    },
    {
      "method": "POST",
      "path": "/ask",
      "description": "NLWeb natural language query endpoint. Returns structured JSON or SSE stream."
    },
    {
      "method": "POST",
      "path": "/search",
      "description": "Quick single-source search (web, X, GitHub, academic, crypto)."
    },
    {
      "method": "GET",
      "path": "/results",
      "description": "List past research results."
    },
    {
      "method": "GET",
      "path": "/results/{id}",
      "description": "Get a specific research result."
    },
    {
      "method": "GET",
      "path": "/results/{id}/export",
      "description": "Export result. ?format=html|pdf|markdown|docx|slides|run-record (docx=Word, slides=self-contained reveal.js deck). ?theme=light|dark for html."
    },
    {
      "method": "GET",
      "path": "/sessions/{id}",
      "description": "Get a research session by id."
    },
    {
      "method": "POST",
      "path": "/research/compare",
      "description": "Compare multiple research results."
    },
    {
      "method": "POST",
      "path": "/research/{id}/steer",
      "description": "Steer an active research session mid-run."
    },
    {
      "method": "GET",
      "path": "/templates",
      "description": "List available research templates."
    },
    {
      "method": "GET",
      "path": "/templates/{id}",
      "description": "Get a research template."
    },
    {
      "method": "POST",
      "path": "/templates/{id}/research",
      "description": "Run research from a template (SSE). Accepts X-API-Key OR x402 payment."
    },
    {
      "method": "POST",
      "path": "/lookouts",
      "description": "Create scheduled research (hourly/daily/weekly)."
    },
    {
      "method": "GET",
      "path": "/lookouts",
      "description": "List lookouts."
    },
    {
      "method": "GET",
      "path": "/lookouts/{id}",
      "description": "Get a lookout."
    },
    {
      "method": "DELETE",
      "path": "/lookouts/{id}",
      "description": "Delete a lookout."
    },
    {
      "method": "POST",
      "path": "/lookouts/{id}/run",
      "description": "Manually trigger a lookout (2/min)."
    },
    {
      "method": "GET",
      "path": "/memory",
      "description": "Search knowledge base."
    },
    {
      "method": "GET",
      "path": "/memory/stats",
      "description": "Knowledge base stats."
    },
    {
      "method": "DELETE",
      "path": "/memory/{id}",
      "description": "Delete a memory entry."
    },
    {
      "method": "GET",
      "path": "/audit/{id}",
      "description": "Get detailed audit trail for a research result."
    },
    {
      "method": "POST",
      "path": "/playground",
      "description": "Run a real research stream with NO API key (homepage demo): forced quick mode, query<=300 chars, tiny cost ceiling, 3/hour per IP, not persisted. Body {query}."
    },
    {
      "method": "POST",
      "path": "/research/async",
      "description": "Submit a research job to run in the background (no SSE held). Returns 202 + task {id,status}. Body {query, mode, perspectives?, webhook_url?}. Poll GET /tasks/{id}."
    },
    {
      "method": "GET",
      "path": "/tasks",
      "description": "List your async research tasks (newest first)."
    },
    {
      "method": "GET",
      "path": "/tasks/{id}",
      "description": "Poll an async research task's status; when done, fetch the report via GET /results/{result_id}."
    },
    {
      "method": "POST",
      "path": "/v1/chat/completions",
      "description": "OpenAI-compatible Chat Completions shim. Point any OpenAI SDK here; model (krawl-deep|krawl-quick|krawl-crypto|...) picks the research mode, last user message is the query. Streaming + non-streaming."
    },
    {
      "method": "GET",
      "path": "/v1/models",
      "description": "OpenAI-compatible model listing — the krawl-* research models."
    },
    {
      "method": "POST",
      "path": "/auth/demo-key",
      "description": "Get a free demo API key (no auth required; 3 deep krawls/mo, 5 req/hour, ~24h)."
    },
    {
      "method": "POST",
      "path": "/auth/keys",
      "description": "Create a managed API key (admin only, X-Admin-Key header)."
    },
    {
      "method": "GET",
      "path": "/auth/keys",
      "description": "List API key metadata (admin only, X-Admin-Key header)."
    },
    {
      "method": "DELETE",
      "path": "/auth/keys",
      "description": "Revoke the API key presented in the X-API-Key header (self-service)."
    },
    {
      "method": "GET",
      "path": "/usage",
      "description": "Current monthly usage rollup for the key (tokens, USD cost, quota)."
    },
    {
      "method": "GET",
      "path": "/usage/events",
      "description": "Paginated per-request usage events."
    },
    {
      "method": "POST",
      "path": "/billing/checkout",
      "description": "Create a Stripe Checkout session (upgrade to Pro)."
    },
    {
      "method": "POST",
      "path": "/billing/portal",
      "description": "Open the Stripe billing portal."
    },
    {
      "method": "POST",
      "path": "/billing/webhook",
      "description": "Stripe webhook (no auth; signature-verified)."
    },
    {
      "method": "GET",
      "path": "/.well-known/oauth-protected-resource",
      "description": "OAuth protected-resource metadata (RFC 9728)."
    },
    {
      "method": "GET",
      "path": "/.well-known/oauth-authorization-server",
      "description": "OAuth authorization-server metadata (RFC 8414) + WorkOS agent_auth block (register/claim/revocation URIs)."
    },
    {
      "method": "POST",
      "path": "/mcp",
      "description": "MCP Streamable HTTP transport (JSON-RPC 2.0): initialize, tools/list, tools/call. Tools: research, quick_search, ask_krawl."
    },
    {
      "method": "GET",
      "path": "/discovery/resources",
      "description": "x402/MPP payable-resource discovery: prices, network, asset."
    },
    {
      "method": "POST",
      "path": "/checkout_sessions",
      "description": "ACP checkout session create (agentic commerce)."
    },
    {
      "method": "POST",
      "path": "/checkout-sessions",
      "description": "UCP checkout session create (requires UCP-Agent + Idempotency-Key)."
    },
    {
      "method": "POST",
      "path": "/agentic_commerce/delegate_payment",
      "description": "ACP Delegate Payment — scoped, revocable vault token."
    },
    {
      "method": "GET",
      "path": "/health",
      "description": "API health check (no auth)."
    }
  ],
  "plans": {
    "demo": {
      "deep_per_month": 3,
      "search_credits_per_month": 100,
      "rate_limit": "5/hour",
      "price": "free"
    },
    "free": {
      "deep_per_month": 25,
      "search_credits_per_month": 1000,
      "rate_limit": "10/min",
      "price": "$0/month"
    },
    "payg": {
      "deep_per_month": "unlimited (metered)",
      "search_credits_per_month": "unlimited (metered)",
      "rate_limit": "60/min",
      "price": "metered via Stripe ($5.00/deep, $1.00/quick search)"
    },
    "pro": {
      "deep_per_month": "unlimited",
      "search_credits_per_month": "unlimited",
      "rate_limit": "120/min",
      "price": "$49/month"
    },
    "_per_request_cost_ceiling_usd": {
      "deep": 2.5,
      "quick": 0.4
    }
  },
  "quota_exceeded_response": {
    "status": 402,
    "body": {
      "error": "quota_exceeded",
      "plan": "free"
    }
  },
  "cost_ceiling_usd": {
    "deep": 2.5,
    "quick": 0.4
  },
  "research_modes": [
    "deep",
    "quick",
    "crypto",
    "token-analysis",
    "protocol-research",
    "whale-tracking",
    "narrative",
    "risk-assessment",
    "yield-strategy"
  ],
  "source_types": [
    "web",
    "x",
    "github",
    "academic",
    "crypto",
    "media",
    "community"
  ],
  "search_providers": [
    "exa",
    "tavily",
    "serper",
    "brave",
    "duckduckgo"
  ],
  "capabilities": [
    "streaming_sse",
    "structured_output",
    "file_upload",
    "session_memory",
    "research_templates",
    "scheduled_research",
    "knowledge_base",
    "citation_verification",
    "voice_input",
    "x402_payments",
    "usage_metering",
    "stripe_billing"
  ],
  "mcp_server": "https://api.krawl.sh/mcp",
  "mcp_manifest": "https://krawl.sh/.well-known/mcp/manifest.json",
  "mcp_tools": [
    "research",
    "quick_search",
    "ask_krawl"
  ],
  "llms_txt": "https://krawl.sh/llms.txt",
  "llms_full_txt": "https://krawl.sh/llms-full.txt",
  "auth_md": "https://krawl.sh/auth.md",
  "agents_md": "https://github.com/ravidsrk/krawl/blob/main/AGENTS.md",
  "comparison": "https://krawl.sh/compare",
  "skills": [
    "https://krawl.sh/skill.md",
    "https://krawl.sh/skill-crypto.md"
  ],
  "payment_protocols": {
    "x402": true,
    "mpp": true,
    "ucp": true,
    "acp": true,
    "discovery": "https://api.krawl.sh/discovery/resources"
  },
  "cli": {
    "name": "krawl-cli",
    "install": "npm install -g krawl-cli",
    "registry": "https://www.npmjs.com/package/krawl-cli",
    "bin": "krawl",
    "commands": [
      "research",
      "search",
      "ask",
      "demo",
      "login",
      "usage",
      "status"
    ]
  },
  "sdks": {
    "rest": "Generate from https://api.krawl.sh/openapi.json",
    "mcp": "Connect any MCP client to https://api.krawl.sh/mcp"
  },
  "repository": "https://github.com/ravidsrk/krawl",
  "evidence": {
    "version": 1,
    "documentation": "https://docs.krawl.sh/docs/trust#evidence-time-and-access",
    "source_fields": [
      "retrieved_at",
      "published_date",
      "updated_date",
      "published_date_provenance",
      "updated_date_provenance",
      "access_status",
      "source_record_id",
      "temporal_status"
    ],
    "access_states": [
      "unknown",
      "inspected_text",
      "partial_excerpt",
      "provider_summary",
      "metadata_only",
      "fetch_failed"
    ],
    "cutoff_parameter": "source_policy.as_of",
    "unknown_defaults": true,
    "retrieved_at_is_publication_time": false,
    "access_is_claim_support": false,
    "corroboration": {
      "field": "learnings[].corroboration",
      "method": "text-reuse-v1",
      "independent_origins": "unassessed",
      "claim_support": "unassessed",
      "confidence_boost": false,
      "unique_primary_sources": "retained"
    },
    "coverage": {
      "field": "evidence_coverage",
      "unit": "unique exact URLs",
      "stages": [
        "discovered",
        "fetch_requested",
        "fetched",
        "retained",
        "shown_to_model",
        "cited"
      ],
      "descriptive_only": true,
      "independent_origins": "unassessed"
    }
  },
  "run_record": {
    "version": 1,
    "export_format": "run-record",
    "schema": "https://krawl.sh/schemas/run-record/bundle.schema.json",
    "documentation": "https://docs.krawl.sh/docs/export#run-record",
    "claim_checks": "unassessed",
    "saved_copies": "unavailable for legacy hosted results"
  },
  "mcp_protocols": {
    "supportedVersions": [
      "2025-06-18"
    ],
    "experimentalProtocolVersion": "2026-07-28",
    "experimentalProtocolEnabledByDefault": false
  },
  "mcp_modern_documentation": "https://docs.krawl.sh/docs/agents-mcp#protocol-compatibility",
  "evidence_pack": {
    "version": 1,
    "export_format": "evidence-pack",
    "media_type": "application/zip",
    "schema": "https://krawl.sh/schemas/run-record/evidence-pack.schema.json",
    "documentation": "https://docs.krawl.sh/docs/export#evidence-pack",
    "inline_endpoint": "https://api.krawl.sh/exports/evidence-pack",
    "integrity": "sha256-exact-bytes",
    "publisher_authenticated": false,
    "claim_truth": "not_assessed",
    "hosted_saved_copies": "unavailable",
    "inline_retention": "none"
  },
  "audit_export": {
    "version": 1,
    "endpoint": "https://api.krawl.sh/auth/me/audit/export",
    "authentication": "account-session-cookie",
    "documentation": "https://docs.krawl.sh/docs/authentication#audit-export",
    "categories": [
      "account",
      "key",
      "research",
      "billing",
      "deletion"
    ],
    "content_included": false,
    "retention": "existing DATA_RETENTION_DAYS window; no new export storage"
  }
}