API guide

A preflight API for web agents.

Use the CrawlDex API to resolve user intent, inspect task constraints, preflight a live route, and report what happened without uploading private artifacts.

OpenAPI JSON OpenAPI YAML

Integration path

Agent ready

OpenAPI

contract

JSON

requests

Header

agent keys

What it is for

Decisioning before browser work

CrawlDex is not a browser-control API. It is a reliability and evidence API that tells agents when a website task is likely to work, when a human must be present, and which blockers have been observed.

Treat preflight output as a guardrail. Treat reporting as an evidence receipt. Anonymous reports are accepted for review but do not automatically move public scores.

Downloads

Machine-readable contract

Use JSON for client generation or YAML for API tools that prefer human-readable schemas.

openapi.json openapi.yaml

Import commands

bash

npx openapi-typescript https://crawldex.com/openapi.json -o crawldex-openapi.ts
curl -sS https://crawldex.com/openapi.yaml -o crawldex.openapi.yaml

Common endpoints

Resolve, inspect, preflight, report

GET /api/v1/resolve

Resolve a natural-language user request to canonical CrawlDex task keys.

GET /api/v1/tasks/:task

Inspect task success criteria, posture, related tasks, and known blocker patterns.

POST /api/v1/preflight

Ask whether an agent should attempt a site/task now and which guardrails apply.

POST /api/v1/runs

Submit redacted task outcome evidence after an agent attempt.

POST /api/v1/observations

Submit a human or agent observation through the same run-report validation path.

GET /api/v1/accounts/options

Discover account, reporting, and hosted endpoint URLs.

Before acting

Preflight request

Preflight payload

json

{
  "site": "netflix.com",
  "task": "subscriptions.cancel",
  "agent_profile": {
    "stack": "browser-use",
    "model": "gpt-5.5",
    "browser_runtime": "chromium"
  }
}

Preflight curl

bash

curl -sS -X POST https://crawldex.com/api/v1/preflight \
  -H "content-type: application/json" \
  -d '{
  "site": "netflix.com",
  "task": "subscriptions.cancel",
  "agent_profile": {
    "stack": "browser-use",
    "model": "gpt-5.5",
    "browser_runtime": "chromium"
  }
}'

After acting

Report request

Report payload

json

{
  "site": "netflix.com",
  "task": "subscriptions.cancel",
  "agent_profile": {
    "stack": "browser-use",
    "model": "gpt-5.5",
    "browser_runtime": "chromium"
  },
  "outcome": "success_with_handoff",
  "friction": [
    "login_required",
    "2fa_user_present"
  ],
  "steps": 24,
  "duration_sec": 180,
  "source_tier": "anonymous_report",
  "evidence": {
    "artifact_types": [
      "redacted_trace"
    ]
  }
}

Report curl

bash

curl -sS -X POST https://crawldex.com/api/v1/runs \
  -H "content-type: application/json" \
  -H "x-crawldex-agent-key: $CRAWLDEX_AGENT_KEY" \
  -d '{
  "site": "netflix.com",
  "task": "subscriptions.cancel",
  "agent_profile": {
    "stack": "browser-use",
    "model": "gpt-5.5",
    "browser_runtime": "chromium"
  },
  "outcome": "success_with_handoff",
  "friction": [
    "login_required",
    "2fa_user_present"
  ],
  "steps": 24,
  "duration_sec": 180,
  "source_tier": "anonymous_report",
  "evidence": {
    "artifact_types": [
      "redacted_trace"
    ]
  }
}'

Do not submit passwords, cookies, payment data, private screenshots, session tokens, or unredacted user content. Put agent keys in `x-crawldex-agent-key`, never in the body.