DEVELOPERS

One call before the money moves.

The Kleyr API is live. Send a merchant site or product page to api.kleyr.ai and get back a verdict, a trust score from 0 to 100 and the findings behind them. This page is the quickstart; the full reference is generated from the OpenAPI spec.

Base URLhttps://api.kleyr.ai
AuthX-API-Key
SpecOpenAPI 3.1

Full API reference → Get an API key

01Quickstart

One request, one verdict. POST /v1/verify holds the connection until the run is done, so it belongs in an agent tool call that can wait. Set the client timeout accordingly.

agent → api.kleyr.ai

curl -X POST https://api.kleyr.ai/v1/verify \
  -H "X-API-Key: $KLEYR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "backmarket.com", "buyer_country": "FR" }'

200 OK response

{
  "schema_version": 1,
  "request_id": "ver_2b7c9d1e4f60",
  "url": "https://www.backmarket.fr",
  "destination": { "mode": "site", "site_url": "https://www.backmarket.fr", … },
  "verdict": "CAUTION",
  "score": 68,
  "risk_flags": [],
  "veto": null,
  "conclusions": [
    "Legal notice found but no company registration number."
  ],
  "latency_ms": 171204,
  "report": { … every check, its score, status and evidence }
}

The verdict is the operational answer. score is the weighted trust score behind it, conclusions the findings in plain language, most important first, and report the full evidence: every check with what it saw.

02Wait for it, or follow along

Both routes run the same job and return the same envelope. The synchronous one is queue-and-wait on top of the asynchronous one.

SYNC

`POST /v1/verify`

Blocks until the verdict is ready. If the run outlives the server's wait limit you get a 504 carrying the job id and a status_url; the job keeps going, poll it instead.

ASYNC

`POST /v1/verifications`

Answers 202 at once with the job in queued state and a Location header. Poll the status resource or stream its events. Use it when a queue or a human sits in front of the call.

The event stream is Server-Sent Events: stage transitions and engine log lines as they happen, then the result. Send the last id seen as Last-Event-ID to resume a dropped connection; a finished job replays.

GET /v1/verifications/ver_2b7c9d1e4f60/events

id: 1
event: stage
data: {"at":"2026-08-28T14:02:11.812Z","stage":"navigation","state":"running"}

id: 2
event: log
data: {"at":"2026-08-28T14:02:12.004Z","stage":"navigation","level":"INFO","message":"Inspecting site: https://www.backmarket.fr"}

id: 187
event: result
data: {"request_id":"ver_2b7c9d1e4f60","verdict":"CAUTION","score":68,…}

03Endpoints

Four routes under /v1, all behind the API key.

Route	Does	Answers
`POST /v1/verify`	Verify a destination and wait for the verdict.	`200` with the verdict, or `504` with the job id if the wait ran out.
`POST /v1/verifications`	Queue a verification.	`202` with the job in `queued` state and a `Location` header.
`GET /v1/verifications/{id}`	Poll a verification.	Current state; `result` is set once `done`. Kept one hour after completion.
`GET /v1/verifications/{id}/events`	Stream a verification's progress.	A `text/event-stream` of `stage`, `log`, then `result` or `error`.

04Request and verdict

The body is the same for both submission routes. Only url is required.

Field	Type	Meaning
`url`	string	Site origin or product-page URL. The scheme is optional (`https://` is assumed); tracking parameters are stripped.
`buyer_country`	string, optional	Buyer jurisdiction as ISO 3166-1 alpha-2 with an optional region suffix, `FR` or `US-CA`. Selects the legal rules that apply; omit to skip jurisdiction-specific checks.
`mode`	enum, default `auto`	`auto` classifies the URL as a site or a product page; `site` or `product` forces it.

The verdict follows the score, unless a hard veto or a cross-check risk signature fires, in which case it is NO-GO whatever the score.

Verdict	Score	Read as
GO	75 to 100	Transact.
CAUTION	50 to 74	Transact with a human in the loop, or not at all for high-value baskets. Read `conclusions`.
NO-GO	0 to 49, or any veto / risk flag	Do not transact. `risk_flags` and `veto` say why.

05Keys, limits and errors

Send your key in the X-API-Key header on every /v1 route. Keys are issued to design partners: ask for one and say what you are building.

Capacity is bounded. When the queue is full a submission gets 503 with a Retry-After header in seconds. Results are kept for one hour after completion, then the id answers 404.

Status	Means	Do
`401`	`X-API-Key` missing or wrong.	Check the header.
`422`	The body fails validation; nothing is queued.	Read `detail`: it names the field and the fix.
`503`	Too many verifications waiting.	Wait `Retry-After` seconds, resubmit.
`504`	The synchronous wait ran out; the job continues.	Poll `detail.status_url`.
`500`	The run failed on our side.	Retry once; tell us if it repeats.

Every error body is { "detail": … }. The response envelope carries a schema_version, bumped only when a field changes meaning; additive fields do not bump it.

Full API reference → Get an API key