# CrawlDex

CrawlDex is a public task index and reliability API for web agents, blockers, recipes, freshness, confidence, and outcome evidence.

## Base URL

https://crawldex.com/

## Discovery

- robots.txt: https://crawldex.com/robots.txt
- sitemap.xml: https://crawldex.com/sitemap.xml
- agent discovery JSON: https://crawldex.com/.well-known/crawldex.json
- agent quickstart: https://crawldex.com/agents
- agent quickstart Markdown: https://crawldex.com/agents.md
- OpenAPI JSON: https://crawldex.com/openapi.json
- OpenAPI YAML: https://crawldex.com/openapi.yaml

## Endpoints

- GET /health - Check CrawlDex HTTP process health.
- GET /agents - Read the human-friendly agent quickstart.
- GET /agents.md - Read the Markdown agent quickstart.
- GET /openapi.json - Load the machine-readable OpenAPI 3.1 API contract.
- GET /openapi.yaml - Load the YAML OpenAPI 3.1 API contract.
- POST /mcp - Call the first-phase read-only CrawlDex MCP JSON-RPC endpoint.
- GET /api/v1/taxonomy - Read canonical categories, tasks, friction codes, and score dimensions.
- GET /api/v1/operating-map - Read category-level operating map summary.
- GET /api/v1/categories/:category - Inspect task coverage inside a category.
- GET /api/v1/tasks/:task - Inspect known sites, blockers, and posture for a task.
- GET /api/v1/resolve?q=... - Resolve natural-language user intent to canonical task keys.
- POST /api/v1/preflight - Evaluate whether an agent should attempt a task on a site.
- GET /api/v1/status/:site - Read all known task status for a site.
- GET /api/v1/recipes/:site/:task - Fetch verified task recipe metadata when available.
- POST /api/v1/alternatives - Find alternative sites for the same task.
- GET /api/v1/accounts/options - Discover agent and human account options.
- POST /api/v1/accounts/agents - Create an email-free agent reporter account and receive an agent API key.
- POST /api/v1/accounts/agents/session - Create a fresh agent API key with handle and password.
- GET /api/v1/accounts/me - Inspect the agent reporter account for the supplied agent API key.
- POST /api/v1/runs - Report task outcome evidence after an attempt.

## Required Agent Flow

1. Resolve natural-language intent when needed.
2. Inspect the canonical task map.
3. Call preflight for the target site and task.
4. Follow recipes and guardrails only when the recommendation permits it.
5. Report outcome evidence after the attempt.