Pre-Check API

One read-only operation. Give it a public website address and it returns an Agent Readiness Score from 0 to 100, a letter grade, four weighted dimension sub-scores, and a per-file check list. No API key, no OAuth, no writes, no webhooks.

Quick start

This is the whole API:

curl "https://agentreadywebsite.io/api/v1/precheck?url=https://example.com"

The machine-readable contract is the OpenAPI 3.1 description. Our API surface is also listed in the RFC 9727 API catalog.

What you get back

The same payload that powers the Pre-Check form on our own homepage, so what you read is what we show a customer. The fields most callers want:

  • score and grade: the headline Agent Readiness Score and its letter band
  • score_model_version: compare scores over time only within one version
  • dimensions: the four weighted dimensions with sub-scores and their underlying checks
  • fileStatus: per-file results for the canonical package paths
  • recommendations: ordered remediation guidance for the failing checks
  • snapshot: the shareable snapshot stored for this run

The scoring model itself, including what each dimension weighs and why, is documented on the files hub.

Errors

Errors are RFC 9457 problem details served as application/problem+json. Every error carries a stable code to branch on, a human detail, and a resolution saying what to do next. Branch on code; the wording of title and detail can change.

  • missing_url (400): pass the site as the url query parameter.
  • invalid_url (400): pass a public http or https address for a single host.
  • method_not_allowed (405): this endpoint is read-only; retry with GET.
  • rate_limit_exceeded (429): honor Retry-After and retry.
  • scan_failed (502): the target site could not be read, usually because it blocks automated requests at the edge.

Rate limits

10 requests per 60 seconds per client IP. Exceeding it returns 429 with a Retry-After header in seconds. There is no paid tier that raises this. If you have a legitimate need for more, write to us and describe it rather than working around the limit.

Versioning

Stable operations carry a major version in the path, starting at /api/v1. We may add fields within v1; anything that breaks an existing request or response moves to a new major path. /precheck remains available as an unversioned alias because our own homepage form and every shared Pre-Check link use it. New integrations should use /api/v1/precheck.

Score changes are versioned separately. score_model_version increments whenever the dimensions, weights, or check formulas change, so a model revision never reads as a regression in your own trend data.

What this API does not do

Worth stating plainly so you do not build against something that is not there. There are no writes, no webhooks, no event subscriptions, and no authentication, because there is nothing to authenticate. There is one resource and no collection, so pagination and idempotency keys do not apply. Running a Pre-Check does not place an order or create an account.

It reads only publicly accessible paths on the target site and modifies nothing there. If a site blocks automated requests at its edge, we will tell you that in edgeAgentAccess rather than guessing.

Questions

A human reads every message at [email protected]. If you are building something on this and hit an edge we did not document, tell us and we will document it.