API Reference

Base URL: https://api.krawl.sh

Authentication

Optional API key via X-API-Key header. Only enforced when MOGRA_API_KEY is set on the server.

curl -H "X-API-Key: your-key" https://api.krawl.sh/health

When auth is enabled and the key is wrong or missing:

{"detail": "Invalid or missing API key"}

Rate limit: 5 requests/minute per IP (all endpoints).

Health

`GET /health`

Health check endpoint.

curl https://api.krawl.sh/health

Response:

{"status": "ok", "version": "0.2.0"}

Research

`POST /research`

Execute deep research and stream events via SSE. This is the primary endpoint.

Request body:

{
  "query": "What is the current state of AI agents?",
  "mode": "deep",
  "depth": 75,
  "breadth": 4,
  "depth_levels": 3,
  "sources": ["exa", "x", "web"],
  "model": null,
  "session_id": null,
  "output_schema": null,
  "source_policy": null
}

Field	Type	Default	Description
`query`	string	required	Research query (1–2000 chars)
`mode`	string	`"deep"`	Research mode. One of: `deep`, `quick`, `crypto`, `token-analysis`, `protocol-research`, `whale-tracking`, `narrative`, `risk-assessment`, `yield-strategy`
`depth`	integer	`75`	Research depth intensity (1–100)
`breadth`	integer	`4`	Parallel queries per depth level (1–10)
`depth_levels`	integer	`3`	Recursion depth levels (1–5)
`sources`	string[]	`["exa","x","web"]`	Allowed source types
`model`	string\|null	`null`	Override LLM model for all phases
`session_id`	string\|null	`null`	Session ID for follow-up research
`output_schema`	object\|null	`null`	JSON Schema for structured output extraction
`source_policy`	object\|null	`null`	Source filtering rules

Source policy:

{
  "source_policy": {
    "include_domains": ["arxiv.org", "nature.com"],
    "exclude_domains": ["medium.com"],
    "freshness": "30d"
  }
}

Response: SSE stream. See SSE Events for all event types.

curl -N -X POST https://api.krawl.sh/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "AI agents 2025", "mode": "deep"}'

`POST /research/upload`

Research with uploaded document context. Multipart form data.

Form fields:

Field	Type	Description
`query`	string	Research query (1–2000 chars)
`mode`	string	Research mode (default: `"deep"`)
`files`	File[]	Up to 5 files, 10MB each. Formats: `.pdf`, `.txt`, `.md`, `.csv`, `.json`

curl -N -X POST https://api.krawl.sh/research/upload \
  -H "X-API-Key: your-key" \
  -F "query=Analyze the findings in these documents" \
  -F "mode=deep" \
  -F "files=@report.pdf" \
  -F "files=@data.csv"

Response: SSE stream (same as /research).

`POST /research/compare`

Compare two research results to detect changes over time.

Request body:

{
  "query": "AI agents",
  "result_ids": ["uuid-1", "uuid-2"]
}

Field	Type	Description
`query`	string	Search query for finding similar results (used if `result_ids` is empty)
`result_ids`	string[]	Specific result IDs to compare (0–10). If 2+, compares those. If 1, finds a similar previous result. If 0, finds 2 most recent similar results.

curl -X POST https://api.krawl.sh/research/compare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "AI agents", "result_ids": ["uuid-old", "uuid-new"]}'

Response:

{
  "old_result_id": "...",
  "new_result_id": "...",
  "old_query": "...",
  "new_query": "...",
  "has_changes": true,
  "new_findings": ["Finding 1", "Finding 2"],
  "removed_claims": ["Old claim"],
  "changes": [{"metric": "price", "old_value": "$50k", "new_value": "$60k"}],
  "summary": "Since your last research: price increased 20%..."
}

`POST /research/\{research_id\}/steer`

Inject a steering instruction into an active research session.

Request body:

{
  "instruction": "Focus more on security vulnerabilities"
}

Field	Type	Description
`instruction`	string	Steering instruction (1–1000 chars)

curl -X POST https://api.krawl.sh/research/SESSION_ID/steer \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"instruction": "Focus more on security aspects"}'

Response:

{
  "status": "instruction_queued",
  "research_id": "...",
  "instruction": "..."
}

Returns 404 if no active research session with that ID.

Search

`POST /search`

Single-source search — returns JSON results without the full research pipeline.

Request body:

{
  "query": "AI agents 2025",
  "source": "exa",
  "options": {}
}

Field	Type	Default	Description
`query`	string	required	Search query (1–2000 chars)
`source`	string	`"exa"`	Source type: `exa`, `x`, `github`, `crypto`, `web`, `academic`, `media`
`options`	object	`{}`	Source-specific options

Options by source type:

exa: num_results, category ("news", "company", etc.), start_date, include_domains
x: from_date, to_date, include_handles, exclude_handles
github: num_results
crypto: token_id
web: url (browse a specific URL)
academic: num_results
media: url (direct YouTube transcript) or search query

curl -X POST https://api.krawl.sh/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "ethereum", "source": "crypto", "options": {"token_id": "ethereum"}}'

Results

`GET /results`

List all persisted research results.

Parameter	Type	Default	Description
`offset`	integer	`0`	Pagination offset
`limit`	integer	`50`	Results per page (1–100)

curl -H "X-API-Key: your-key" \
  "https://api.krawl.sh/results?offset=0&limit=10"

`GET /results/\{result_id\}`

Get a specific research result.

curl -H "X-API-Key: your-key" \
  https://api.krawl.sh/results/RESULT_UUID

`GET /results/\{result_id\}/export`

Export a research result as HTML, PDF, or Markdown.

Parameter	Type	Default	Description
`format`	string	`"html"`	Export format: `pdf`, `html`, `markdown`
`theme`	string	`"light"`	Theme for HTML export: `light`, `dark`

# Download as PDF
curl -H "X-API-Key: your-key" \
  "https://api.krawl.sh/results/RESULT_UUID/export?format=pdf" \
  -o report.pdf

# View as HTML
curl -H "X-API-Key: your-key" \
  "https://api.krawl.sh/results/RESULT_UUID/export?format=html&theme=dark"

# Download as Markdown
curl -H "X-API-Key: your-key" \
  "https://api.krawl.sh/results/RESULT_UUID/export?format=markdown" \
  -o report.md

Sessions

`GET /sessions/\{session_id\}`

Get all research results in a session, ordered by creation time. Used for session continuity / follow-up research.

curl -H "X-API-Key: your-key" \
  https://api.krawl.sh/sessions/SESSION_UUID

Response:

{
  "session_id": "...",
  "results": [
    {"id": "...", "query": "...", "markdown": "...", "created_at": "..."},
    {"id": "...", "query": "follow-up question", "markdown": "...", "created_at": "..."}
  ]
}

Templates

`GET /templates`

List all available research templates.

curl -H "X-API-Key: your-key" https://api.krawl.sh/templates

`GET /templates/\{template_id\}`

Get a specific template by ID.

curl -H "X-API-Key: your-key" \
  https://api.krawl.sh/templates/token-due-diligence

`POST /templates/\{template_id\}/research`

Execute a research template with filled-in variables. Returns an SSE stream.

Request body:

{
  "variables": {
    "token": "Ethereum"
  }
}

curl -N -X POST https://api.krawl.sh/templates/token-due-diligence/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"variables": {"token": "Ethereum"}}'

Lookouts

`POST /lookouts`

Create a scheduled research lookout.

Request body:

{
  "query": "Latest developments in AI agents",
  "mode": "deep",
  "schedule": "daily",
  "webhook_url": "https://your-webhook.example.com/notify"
}

Field	Type	Default	Description
`query`	string	required	Research query (1–2000 chars)
`mode`	string	`"deep"`	Research mode
`schedule`	string	`"daily"`	Schedule: `hourly`, `daily`, `weekly`
`webhook_url`	string\|null	`null`	Webhook URL for notifications (SSRF-validated)

Max 10 active lookouts per API key.

curl -X POST https://api.krawl.sh/lookouts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "AI agents news", "schedule": "daily"}'

`GET /lookouts`

List all lookouts.

Parameter	Type	Default	Description
`offset`	integer	`0`	Pagination offset
`limit`	integer	`50`	Results per page (1–100)

curl -H "X-API-Key: your-key" https://api.krawl.sh/lookouts

`GET /lookouts/\{lookout_id\}`

Get a specific lookout.

curl -H "X-API-Key: your-key" \
  https://api.krawl.sh/lookouts/LOOKOUT_UUID

`DELETE /lookouts/\{lookout_id\}`

Delete a lookout and stop its schedule.

curl -X DELETE -H "X-API-Key: your-key" \
  https://api.krawl.sh/lookouts/LOOKOUT_UUID

`POST /lookouts/\{lookout_id\}/run`

Manually trigger a lookout run. Rate limited to 2/minute. Respects the minimum interval cooldown (default 60 minutes).

curl -X POST -H "X-API-Key: your-key" \
  https://api.krawl.sh/lookouts/LOOKOUT_UUID/run

Audit Trail

`GET /audit/\{result_id\}`

Get the audit trail for a research result. Shows every search, extraction, synthesis, and verification step.

curl -H "X-API-Key: your-key" \
  https://api.krawl.sh/audit/RESULT_UUID

Response:

{
  "result_id": "...",
  "entries": [
    {
      "timestamp": "2025-01-15T10:30:00Z",
      "action": "search",
      "tool": "webSearch",
      "query": "AI agents 2025",
      "sources_found": 8,
      "learnings_extracted": 0,
      "model": "bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0",
      "tokens_used": 1200,
      "duration_ms": 2500
    }
  ]
}

Memory / Knowledge Base

`GET /memory`

Search the cross-session knowledge base.

Parameter	Type	Description
`q`	string	Search query (required, max 500 chars)
`limit`	integer	Max results (default 20, max 100)

curl -H "X-API-Key: your-key" \
  "https://api.krawl.sh/memory?q=ethereum%20merge&limit=10"

Response:

{
  "query": "ethereum merge",
  "count": 3,
  "memories": [
    {
      "id": "...",
      "content": "Ethereum transitioned to PoS in September 2022...",
      "source_query": "Ethereum merge impact",
      "source_urls": ["https://..."],
      "tags": ["ethereum", "proof-of-stake"],
      "created_at": "2025-01-10T..."
    }
  ]
}

`GET /memory/stats`

Get knowledge base statistics.

curl -H "X-API-Key: your-key" \
  https://api.krawl.sh/memory/stats

`DELETE /memory/\{memory_id\}`

Delete a specific memory entry.

curl -X DELETE -H "X-API-Key: your-key" \
  https://api.krawl.sh/memory/MEMORY_UUID

Error Responses

All errors return JSON:

Status	Description
400	Bad request (invalid parameters)
401	Invalid or missing API key
404	Resource not found
413	Request body too large (1MB / 50MB for uploads)
422	Validation error (invalid mode, schema, etc.)
429	Rate limit exceeded or lookout cooldown
500	Internal server error (sanitized)
503	Server busy (too many concurrent research sessions)

API Reference

On this page