API guide
Read the trust record before web agents act.
Use the CrawlDex API as the checkpoint: fetch the Agent Trust Record, echo the decision, then report only redacted outcome evidence.
Integration path
Agent readyWhat it is for
The checkpoint call
CrawlDex is not a browser-control API. It returns a dated Agent Trust Record so an agent can decide whether to proceed, keep a human present, avoid the route, or choose an alternative.
Echoes measure whether the record changed the agent decision. Reporting is separate evidence intake. 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.
Common endpoints
Trust record first, echo second
Fetch the citable Agent Trust Record before an agent attempts a public website task.
Send a decision echo after reading a trust record: followed, overrode, or partially used; add x-crawldex-agent-key for private dashboard attribution.
Send a free-text-free ATR outcome status with record_id, outcome, task_attempted, and optional redaction_status.
Read the authenticated agent key's memory-v0 decision echoes and override rate.
Resolve a natural-language user request to canonical CrawlDex task keys.
Inspect task success criteria, posture, related tasks, and known blocker patterns.
Ask whether an agent should attempt a site/task now and which guardrails apply.
Submit redacted task outcome evidence after an agent attempt.
Submit a human or agent observation through the same run-report validation path.
Fetch public trust records in batches with tiered caps: 500 anonymous/free, 2,000 partner, 5,000 paid.
Discover account, reporting, and hosted endpoint URLs.
Read the current agent account, resolved API tier, effective rate limit, window, and batch cap.
Read self-scoped in-memory usage counters for the presented agent key.
List principal-owned linked agent identities with key prefixes only.
Verified read
Fetch an Agent Trust Record
This copy-paste command is the only rendered curl on this page because it can be verified against production without mutating public state.
GET /api/v1/trust-record/:site/:task
bash
curl -i https://crawldex.vercel.app/api/v1/trust-record/netflix.com/subscriptions.cancel✓ verified working 2026-07-03 · https://crawldex.vercel.app · api-atr-curl · 2026-07-03T10:04:15.000Z
All examples on this page are execution-verified against the origin shown. The same paths will be served unchanged at https://api.crawldex.com once the custom domain is attached.
Tiered keys
Capacity is assigned by humans
Agent keys can resolve to free, partner, or paid API tiers. Tiers change rate-limit capacity and batch size only; scores, verdicts, confidence, rankings, and evidence weighting never read API tier state.
Partner and paid tiers are assigned after human review. Start through the pricing page.
Self-scoped usage
Account and usage responses
`GET /api/v1/accounts/me` returns the account handle, resolved `api_tier`, API key prefix, and limits: `rate_limit_max`, `rate_limit_window_ms`, and `batch_max_pairs`.
`GET /api/v1/usage/me` returns self-scoped counters with persistence `in_memory_v0`, including `total_requests`, `rate_limited_requests`, `batch_requests`, and `batch_pairs_submitted`.
`GET /api/v1/echoes/me` returns self-scoped decision echoes and override rate for the active agent key. `GET /api/v1/principals/me/agents` returns linked identities with key prefixes only.
Add `x-crawldex-agent-key` to `POST /api/v1/echo` when a decision echo should appear in the private dashboard. Attribution never changes scores, verdicts, confidence, rankings, or evidence weighting.
curl -X POST $BASE/api/v1/echo \
-H "content-type: application/json" \
-H "x-crawldex-agent-key: $AGENT_KEY" \
-d '{"record_id":"atr_0123456789abcdef","action_taken":"followed","task_attempted":true}'Rate limits
429 response body
Rate-limit responses use `rate_limited` with `tier`, `limit`, and `retry_after_ms` so callers can back off without guessing.
Batch caps
413 response body
Over-cap batch requests use `batch_cap_exceeded` with `tier`, `max_pairs`, and `received_pairs`.
Before acting
Compatibility preflight
`POST /api/v1/preflight` remains available for existing clients. New integrations should read the Agent Trust Record first, then treat preflight language as the compatibility path.
After acting
Report request
`POST /api/v1/feedback/outcome` accepts exactly `record_id`, `outcome`, `task_attempted`, and optional `redaction_status`. It accepts no free text. An optional `x-crawldex-instance` value is salted and stored only as a hash; the raw instance is never stored. Add an optional valid `x-crawldex-agent-key` when the accepted response should return `attributed: true`; no actor identifier is returned.
The response contains `status` and `attributed`. This signal never affects scores, verdicts, confidence, rankings, evidence weighting, or reputation. Use `POST /api/v1/runs` or `POST /api/v1/observations` only for fuller redacted evidence, and never submit passwords, cookies, payment data, session tokens, private screenshots, or unredacted user content.