{"openapi":"3.1.0","info":{"title":"Krawl","description":"Deep research API — autonomous agent with tool calling, 50+ verified sources, structured output with citations","version":"0.2.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/research":{"post":{"summary":"Research","description":"Execute deep research and stream events via SSE.","operationId":"research_research_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/research/upload":{"post":{"summary":"Research With Documents","description":"Execute research with uploaded document context and stream events via SSE.\n\nAccepts multipart form data with query, mode, and up to 5 files (10MB each).\nSupported formats: .pdf, .txt, .md, .csv, .json","operationId":"research_with_documents_research_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_research_with_documents_research_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/playground":{"post":{"summary":"Playground","description":"Run a REAL research stream with no API key — the homepage playground.\n\nThis is a marketing/activation surface, not a free API tier. It is locked\ndown hard: no auth, forced ``quick`` mode, a short query cap, a tiny\nper-request cost ceiling, and a tight per-IP rate limit. Results are NOT\npersisted. Anyone wanting more (deep mode, history, higher limits) gets a\nkey via ``/auth/demo-key`` or signs up.","operationId":"playground_playground_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaygroundRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/async":{"post":{"summary":"Submit Async Research","description":"Submit a research job to run in the background.\n\nReturns a task immediately (202); the pipeline runs server-side without an\nSSE connection. Poll ``GET /tasks/{id}`` for status, or pass ``webhook_url``\nto be notified on completion. Quota is enforced up front (same as /research)\nand a per-key cap bounds concurrent fan-out.","operationId":"submit_async_research_research_async_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResearchRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/tasks":{"get":{"summary":"List Async Tasks","description":"List the caller's async research tasks (newest first).","operationId":"list_async_tasks_tasks_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskResponse"},"title":"Response List Async Tasks Tasks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}":{"get":{"summary":"Get Async Task","description":"Poll an async research task's status. When ``status`` is ``done``,\nfetch the report via ``GET /results/{result_id}``.","operationId":"get_async_task_tasks__task_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/chat/completions":{"post":{"summary":"Chat Completions","description":"OpenAI-compatible Chat Completions endpoint.\n\nPoint any OpenAI SDK (or LangChain / LlamaIndex / etc.) at Krawl by setting\n``base_url`` to this server. The ``model`` selects the research mode\n(``krawl-deep`` default, ``krawl-quick``, ``krawl-crypto``, …) and the last\nuser message is the research query. Returns a fully-cited report as the\nassistant message. Supports both streaming and non-streaming.","operationId":"chat_completions_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/chat/completions":{"post":{"summary":"Chat Completions","description":"OpenAI-compatible Chat Completions endpoint.\n\nPoint any OpenAI SDK (or LangChain / LlamaIndex / etc.) at Krawl by setting\n``base_url`` to this server. The ``model`` selects the research mode\n(``krawl-deep`` default, ``krawl-quick``, ``krawl-crypto``, …) and the last\nuser message is the research query. Returns a fully-cited report as the\nassistant message. Supports both streaming and non-streaming.","operationId":"chat_completions_v1_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/models":{"get":{"summary":"List Openai Models","description":"OpenAI-compatible model listing — the krawl-* research models.","operationId":"list_openai_models_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/models":{"get":{"summary":"List Openai Models","description":"OpenAI-compatible model listing — the krawl-* research models.","operationId":"list_openai_models_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/templates":{"get":{"summary":"List Templates","description":"List all available research templates.","operationId":"list_templates_templates_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/templates/{template_id}":{"get":{"summary":"Get Template","description":"Get a specific research template by ID.","operationId":"get_template_templates__template_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/templates/{template_id}/research":{"post":{"summary":"Execute Template","description":"Execute a research template with filled-in variables.","operationId":"execute_template_templates__template_id__research_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteTemplateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/results":{"get":{"summary":"List Results","description":"List all persisted research results.","operationId":"list_results_results_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/results/{result_id}":{"get":{"summary":"Get Result","description":"Retrieve a specific research result.","operationId":"get_result_results__result_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"result_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Result Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/results/{result_id}/export":{"get":{"summary":"Export Result","description":"Export a research result as HTML, PDF, Markdown, DOCX, or slides.","operationId":"export_result_results__result_id__export_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"result_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Result Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["pdf","html","markdown","docx","slides"],"type":"string","default":"html","title":"Format"}},{"name":"theme","in":"query","required":false,"schema":{"enum":["light","dark"],"type":"string","default":"light","title":"Theme"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sessions/{session_id}":{"get":{"summary":"Get Session","description":"Return all research results in a session, ordered by created_at.","operationId":"get_session_sessions__session_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/compare":{"post":{"summary":"Compare Research","description":"Compare research results to detect changes over time.\n\nIf *result_ids* is provided (2+ IDs), compare those specific results.\nIf only *query* is provided, find the most recent 2 results for similar\nqueries and compare them automatically.\n\nReturns structured diff: new findings, removed claims, changed metrics,\nand a natural language summary.","operationId":"compare_research_research_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Compare Research Research Compare Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/search":{"post":{"summary":"Search","description":"Execute a single-source search and return JSON results.","operationId":"search_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Search Search Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/lookouts":{"post":{"summary":"Create Lookout Endpoint","description":"Create a new research lookout.","operationId":"create_lookout_endpoint_lookouts_post","security":[{"APIKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLookoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List Lookouts Endpoint","description":"List all lookouts.","operationId":"list_lookouts_endpoint_lookouts_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/lookouts/{lookout_id}":{"get":{"summary":"Get Lookout Endpoint","description":"Get a specific lookout.","operationId":"get_lookout_endpoint_lookouts__lookout_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"lookout_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Lookout Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Lookout Endpoint","description":"Delete a lookout.","operationId":"delete_lookout_endpoint_lookouts__lookout_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"lookout_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Lookout Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/lookouts/{lookout_id}/run":{"post":{"summary":"Run Lookout Endpoint","description":"Manually trigger a lookout run.","operationId":"run_lookout_endpoint_lookouts__lookout_id__run_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"lookout_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Lookout Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/{research_id}/steer":{"post":{"summary":"Steer Research","description":"Inject a steering instruction into an active research session.","operationId":"steer_research_research__research_id__steer_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"research_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Research Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SteerRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/audit/{result_id}":{"get":{"summary":"Get Audit Trail","description":"Get the audit trail for a research result.","operationId":"get_audit_trail_audit__result_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"result_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Result Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/memory":{"get":{"summary":"Search Memory","description":"Search the cross-session knowledge base for prior research findings.","operationId":"search_memory_memory_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":500,"description":"Search query for knowledge base","default":"","title":"Q"},"description":"Search query for knowledge base"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/memory/stats":{"get":{"summary":"Memory Stats","description":"Get statistics about the knowledge base.","operationId":"memory_stats_memory_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/memory/{memory_id}":{"delete":{"summary":"Delete Memory","description":"Delete a specific memory entry from the knowledge base.","operationId":"delete_memory_memory__memory_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9-]{36}$","title":"Memory Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ask":{"post":{"summary":"Nlweb Ask","description":"NLWeb-compatible natural language query endpoint.\n\nAccepts a natural-language question and returns a structured answer\npointing the caller to the appropriate research endpoint.\nWhen *streaming* is True, returns Server-Sent Events with NLWeb\nevent types (start, result, complete).","operationId":"nlweb_ask","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/demo-key":{"post":{"summary":"Generate Demo Key","description":"Generate a rate-limited demo API key for testing. No auth required.\n\nThe key is persisted (hashed) and expires in 24 hours. It is rate-limited\nto the demo plan and is enough to evaluate the API but not run production.","operationId":"generate_demo_key","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/keys":{"post":{"summary":"Create Api Key Endpoint","description":"Issue a new API key (admin-only). The raw key is returned exactly once.","operationId":"create_api_key","security":[{"APIKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List Api Keys Endpoint","description":"List API key metadata (admin-only). Never returns raw keys.","operationId":"list_api_keys","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"owner_email","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Owner Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Revoke Api Key Endpoint","description":"Revoke the API key presented in the X-API-Key header (self-service).","operationId":"revoke_api_key","security":[{"APIKeyHeader":[]}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/usage":{"get":{"summary":"Get Usage","description":"Return the caller's usage for the current (or given) month + plan quotas.\n\nRequires a ``krawl_`` API key. Reports tokens, cost, deep-krawl + search\ncredit consumption against the key's plan limits.","operationId":"get_usage","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"null"}],"title":"Period"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage/events":{"get":{"summary":"List Usage Events Endpoint","description":"Return recent per-request usage events for the caller's key.","operationId":"list_usage_events","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/checkout":{"post":{"summary":"Create Checkout","description":"Start a Stripe Checkout session to upgrade the caller's key to Pro.","operationId":"create_checkout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/billing/portal":{"post":{"summary":"Billing Portal","description":"Open the Stripe billing portal for the caller's linked customer.","operationId":"billing_portal","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/billing/webhook":{"post":{"summary":"Stripe Webhook","description":"Consume Stripe webhook events (signature-verified) and apply plan changes.","operationId":"stripe_webhook","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"summary":"Oauth Protected Resource","description":"OAuth 2.0 Protected Resource metadata (RFC 9728).\n\nCross-links to the authorization server (this same origin) so agents can\nfollow PRM → AS metadata → agent_auth endpoints.","operationId":"oauth_protected_resource","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"summary":"Oauth Authorization Server","description":"OAuth 2.0 Authorization Server metadata (RFC 8414) + WorkOS `agent_auth`\nblock so agents can discover how to register, claim, and revoke credentials.\n\nThe `agent_auth` endpoints resolve (OPTIONS preflight returns a non-404\nstatus), and the block points back at the published /auth.md skill.","operationId":"oauth_authorization_server","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/discovery/resources":{"get":{"summary":"Discovery Resources","description":"Agent-payable resource discovery for x402 / MPP.\n\nLists the API resources an agent can pay for per-request, with the price,\nnetwork, and asset — so an autonomous agent can discover what costs what\nwithout first triggering a 402. Mirrors the x402 / MPP discovery convention.","operationId":"discovery_resources","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AskRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"streaming":{"type":"boolean","title":"Streaming","default":false}},"type":"object","required":["query"],"title":"AskRequest"},"AsyncResearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"mode":{"$ref":"#/components/schemas/ResearchMode","default":"deep"},"perspectives":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Perspectives","description":"STORM perspective-guided research (None = server default)."},"webhook_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Webhook Url","description":"Optional URL to POST a completion notification to."}},"type":"object","required":["query"],"title":"AsyncResearchRequest","description":"Submit a research job to run in the background (no SSE connection held).\n\nPoll GET /tasks/{id} for status, or supply a webhook_url to be notified."},"Body_research_with_documents_research_upload_post":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"mode":{"type":"string","title":"Mode","default":"deep"},"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files","default":[]}},"type":"object","required":["query"],"title":"Body_research_with_documents_research_upload_post"},"ChatCompletionRequest":{"properties":{"model":{"type":"string","title":"Model","default":"krawl-deep"},"messages":{"items":{"$ref":"#/components/schemas/ChatMessage"},"type":"array","minItems":1,"title":"Messages"},"stream":{"type":"boolean","title":"Stream","default":false}},"additionalProperties":true,"type":"object","required":["messages"],"title":"ChatCompletionRequest","description":"Minimal OpenAI Chat Completions request.\n\nOnly the fields Krawl acts on are modeled; unknown fields (temperature,\ntop_p, tools, …) are accepted and ignored so existing OpenAI SDK callers\nwork unchanged."},"ChatMessage":{"properties":{"role":{"type":"string","title":"Role"},"content":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Content"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"type":"object","required":["role"],"title":"ChatMessage"},"CheckoutRequest":{"properties":{"email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Email"}},"type":"object","title":"CheckoutRequest"},"CompareRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"result_ids":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Result Ids"}},"type":"object","required":["query"],"title":"CompareRequest"},"CreateKeyRequest":{"properties":{"plan":{"type":"string","title":"Plan","description":"Plan name: free, payg, pro, test","default":"free"},"name":{"type":"string","maxLength":100,"title":"Name","description":"Human-readable label","default":""},"owner_email":{"anyOf":[{"type":"string","maxLength":255,"pattern":"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"},{"type":"null"}],"title":"Owner Email"}},"type":"object","title":"CreateKeyRequest"},"CreateLookoutRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"mode":{"$ref":"#/components/schemas/ResearchMode","default":"deep"},"schedule":{"type":"string","enum":["hourly","daily","weekly"],"title":"Schedule","default":"daily"},"webhook_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Webhook Url"}},"type":"object","required":["query"],"title":"CreateLookoutRequest"},"ExecuteTemplateRequest":{"properties":{"variables":{"additionalProperties":{"type":"string"},"type":"object","title":"Variables"}},"type":"object","title":"ExecuteTemplateRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded"],"title":"Status"},"version":{"type":"string","title":"Version"},"db":{"type":"string","enum":["ok","error"],"title":"Db"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"}},"type":"object","required":["status","version","db","uptime_seconds"],"title":"HealthResponse"},"PlaygroundRequest":{"properties":{"query":{"type":"string","maxLength":300,"minLength":1,"title":"Query"}},"type":"object","required":["query"],"title":"PlaygroundRequest"},"ResearchMode":{"type":"string","enum":["deep","quick","crypto","token-analysis","protocol-research","whale-tracking","narrative","risk-assessment","yield-strategy"],"title":"ResearchMode"},"ResearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"mode":{"$ref":"#/components/schemas/ResearchMode","default":"deep"},"depth":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Depth","default":75},"breadth":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Breadth","description":"Parallel queries per depth level","default":4},"depth_levels":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Depth Levels","description":"Recursion depth levels","default":3},"sources":{"items":{"$ref":"#/components/schemas/SourceType"},"type":"array","title":"Sources","description":"Allowed source types. Agent will only use tools matching these sources.","default":["exa","x","web"]},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Override LLM model for all phases. If None, uses server defaults."},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session ID for conversational follow-up research. If provided, loads prior context."},"prior_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Context","description":"Prior research markdown from a previous session result. Injected by the server."},"prior_learnings":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Prior Learnings","description":"Prior learnings from a previous session result. Injected by the server."},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"JSON Schema (Draft 7) defining the desired structured output. When provided, the research result includes a 'structured' field with per-field values, citations, confidence scores, and reasoning. The markdown report is still generated alongside the structured data."},"source_policy":{"anyOf":[{"$ref":"#/components/schemas/SourcePolicyModel"},{"type":"null"}],"description":"Request-level source policy: domain allow/deny lists and freshness filter."},"preferred_search_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Search Provider","description":"Preferred search provider for web searches. Options: 'exa', 'tavily', 'serper', 'brave', 'duckduckgo'. If None, uses server default (exa)."},"document_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Context","description":"Extracted text from uploaded documents. Injected by the server from /research/upload."},"perspectives":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Perspectives","description":"STORM perspective-guided research: discover 3-5 expert perspectives and steer query generation to cover each angle. None = use server default (PERSPECTIVES_ENABLED); True/False to force on/off per request."}},"type":"object","required":["query"],"title":"ResearchRequest"},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"source":{"$ref":"#/components/schemas/SourceType","default":"exa"},"options":{"additionalProperties":true,"type":"object","title":"Options"}},"type":"object","required":["query"],"title":"SearchRequest"},"SourcePolicyModel":{"properties":{"include_domains":{"items":{"type":"string"},"type":"array","title":"Include Domains","description":"Only use sources from these domains."},"exclude_domains":{"items":{"type":"string"},"type":"array","title":"Exclude Domains","description":"Never use sources from these domains."},"freshness":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freshness","description":"Only use sources from this time window. E.g. '7d', '30d', '90d', '1y'."}},"type":"object","title":"SourcePolicyModel","description":"Request-level source filtering."},"SourceType":{"type":"string","enum":["exa","x","github","crypto","web","academic","media","community"],"title":"SourceType"},"SteerRequest":{"properties":{"instruction":{"type":"string","maxLength":1000,"minLength":1,"title":"Instruction"}},"type":"object","required":["instruction"],"title":"SteerRequest"},"TaskResponse":{"properties":{"id":{"type":"string","title":"Id"},"query":{"type":"string","title":"Query"},"mode":{"type":"string","title":"Mode"},"status":{"$ref":"#/components/schemas/TaskStatus"},"result_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Id"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"}},"type":"object","required":["id","query","mode","status"],"title":"TaskResponse","description":"Status view of an async research task."},"TaskStatus":{"type":"string","enum":["queued","running","done","error"],"title":"TaskStatus"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"x-payment-info":{"protocols":["x402","mpp"],"scheme":"exact","network":"base","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","currency":"USDC","discovery":"https://api.krawl.sh/discovery/resources","prices_usd":{"deep":5.0,"quick":1.0},"description":"Keyless agents may pay per request. Call a research endpoint with no X-API-Key to receive HTTP 402 with PaymentRequirements (x402 v1, WWW-Authenticate: Payment for MPP), sign an EIP-3009 USDC authorization on Base, and retry with an X-PAYMENT header.","www_authenticate":"Payment","auth_docs":"https://krawl.sh/auth.md"},"x-mcp":{"transport":"streamable-http","url":"https://api.krawl.sh/mcp","manifest":"https://krawl.sh/.well-known/mcp/manifest.json"},"servers":[{"url":"https://api.krawl.sh","description":"Production"}]}