agentready

API

Plain REST, authenticated with a Bearer key. We also expose our own WebMCP tools at /mcp.

Authentication

Authorization: Bearer ar_live_…

Create keys in the dashboard. Requires the Pro plan or higher.

Start a scan

curl -X POST https://agentreadyfunnel.com/v1/scans   -H "authorization: Bearer $AGENTREADY_KEY"   -H "content-type: application/json"   -d '{"url":"example.com","locale":"en","depth":1}'

→ 202 {"scan_id":"scan_…","status":"queued"}

The scheme is optional — example.com and https://example.com both work. Poll until scan.status is done.

Request body

FieldTypeDefaultWhat it does
url string required The page to scan. The scheme is optional.
locale "en" | "es" Accept-Language Language of the report text and the findings.
depth integer 1 How many pages to crawl. Silently clamped to the plan maximum rather than rejected.
tier 1 | 2 | 3 2 How hard to look. Asking for a tier above your plan returns 402 tier_not_entitled.
render boolean false Force tier 2 even when the static pass already answered. For pages whose fields are injected at runtime.
public boolean false Publish the result to the leaderboard and /v1/sites/:domain. Anonymous scans are always public.
fresh boolean false Skip the recent-scan dedupe and scan again. Still consumes quota.

Detection tiers

A scan escalates a tier only when the one below it could not answer whether the site registers WebMCP tools. The tier actually reached comes back in the report as tier_reached — it is not always the one you asked for.

TierHowWhat it sees, and what it misses
1 One HTTP request Declarative form[toolname], the polyfill, WebMCP signals in the bundles, and the headers that switch it off. Conclusive for static HTML; blind to any tool registered from JavaScript.
2 Real browser + shim A fake modelContext injected before page scripts run, so it catches the tools an SPA registers on hydration. It cannot verify the permissions policy or origin isolation, and it does not compile declarative forms to JSON Schema the way Chrome does — those get flagged unverified.
3 Native Chrome (container) Chrome with the WebMCP flag on — the only thing that actually verifies what tier 2 can merely assume. Not enabled in this deployment yet.
Tier 3, today: The Agency plan entitles you to tier 3, but native-Chrome verification is not switched on here yet. A tier 3 scan runs, bills like any other, returns the tier3_unavailable finding and marks the result partial — the data comes from the tier 2 shim. No plan loses detection because of this: tier 2 is the real ceiling for everyone right now.

Other endpoints

MethodPathWhat it does
GET /v1/me Account, plan and period usage
GET /v1/scans/:id The report for a scan
GET /v1/sites/:domain Latest public scan for a domain
GET /v1/leaderboard Public ranking
GET /v1/plans Plan catalogue and limits
POST /mcp MCP server (JSON-RPC)

What a report you do not own returns

A public scan is readable by anyone — that is what makes the leaderboard and /v1/sites/:domain work — but readable is not disclosed. The grade, the score and the pillar breakdown are public. The findings, the tool names, their schemas, the suggestions and the snippets belong to the workspace that ran the scan.

When it is not yours the response is still 200 with the summary, and meta.locked comes back true with meta.lockReason set to not_owner. Scan the domain yourself and the full report is yours.

{"scan":{"readiness_score":61,"readiness_grade":"C"},
 "suggestions":[],"findings":[],
 "meta":{"locked":true,"lockReason":"not_owner",
         "counts":{"suggestions":3,"blockers":1,"warnings":2}}}

A scan you started while logged out belongs to the anonymous workspace until you create an account from the report itself, at which point it becomes yours.

Errors

{"error":{"code":"scan_quota_exceeded","message":"…","limit":25,"plan":"free"}}

Plan limits return 402 (scan_quota_exceeded, concurrency_exceeded, tier_not_entitled, pages_exceeded), authentication 401, permissions 403 (api_not_entitled, forbidden), rate limiting 429.