Scanning

Submit one URL with POST /UrlCheck, or up to 50 in one call with POST /UrlCheck/batch. Either way you get an analyzeId to poll, or a webhook when the scan is done.

One URL

POST /UrlCheck answers 200 with the finished result when the URL was scanned recently (a cache hit), or 202 with an analyzeId to poll with GET /UrlCheck/{analyzeId}. The quickstart walks through it.

Many URLs: `POST /UrlCheck/batch`

For a pipeline that finds URLs in bulk (a mail gateway, a crawler, a ticket queue). The body is an items array of 1 to 50 scan requests, each the same object you would send to POST /UrlCheck:

curl -X POST https://api.urlyze.io/UrlCheck/batch \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "items": [
      { "url": "https://login-example.com/verify" },
      { "url": "https://example.org", "visibility": "Unlisted" },
      { "url": "https://login-example.com/verify" },
      { "url": "not a url" }
    ]
  }'

The call needs authentication; anonymous batches are refused. The answer is 200 with one result per item, in input order:

{
  "results": [
    { "index": 0, "url": "https://login-example.com/verify", "status": 202,
      "analyzeId": "3f6c0f2e-…", "scanState": "queued", "fromCache": false,
      "error": null, "duplicateOf": null },
    { "index": 1, "url": "https://example.org", "status": 200,
      "analyzeId": "9b21d4a0-…", "scanState": "completed", "fromCache": true,
      "error": null, "duplicateOf": null },
    { "index": 2, "url": "https://login-example.com/verify", "status": 202,
      "analyzeId": "3f6c0f2e-…", "scanState": "queued", "fromCache": false,
      "error": null, "duplicateOf": 0 },
    { "index": 3, "url": "not a url", "status": 400,
      "analyzeId": null, "scanState": null, "fromCache": false,
      "error": "…", "duplicateOf": null }
  ]
}

field	meaning
`index`	zero-based position of the item in your request
`url`	the URL as you submitted it
`status`	what `POST /UrlCheck` would have answered for this item: `200` (cached), `202` (queued), `400`, `401`, `429` or `500`
`analyzeId`	set on `200` and `202`: the id to poll, and the one the webhook names
`scanState`	as on the single endpoint; `null` when the item was rejected
`fromCache`	`true` when the answer is an existing scan: no new scan ran
`error`	why the item was rejected; `null` when it was accepted
`duplicateOf`	set when the same URL appeared earlier in the batch: that item's `index`. The URL is submitted once and the repeat carries the first item's outcome.

What a batch does not change

Every item is handled exactly like POST /UrlCheck. The same validation, the same cache, the same visibility rules.
Quota and the per-minute limit count each URL. A batch of 50 uses 50 scans of quota (cache hits stay free) and 50 of your per-minute allowance. When the limit runs out partway through, the remaining items answer 429 while the earlier ones are already queued. Resubmit only the items that were refused. See Rate limits.
One item failing does not fail the batch. The call answers 200 and each item carries its own status. Check every item's status, not only the HTTP status of the call.

A cached item (fromCache: true) carries no result body. Fetch it with GET /UrlCheck/{analyzeId}. It also sends no scan.completed webhook, because no scan runs.

Knowing when a scan is done

Poll GET /UrlCheck/{analyzeId} every 3–5 seconds, or turn on the scan.completed webhook and let Urlyze call you when each scan your workspace submitted finishes. With a webhook, read the cached items of a batch right away and wait for the event on the rest.

Scanning

One URL

Many URLs: POST /UrlCheck/batch

What a batch does not change

Knowing when a scan is done

Many URLs: `POST /UrlCheck/batch`