---
title: "Discover the pages of a site. Free 5 times a day per client address (at most 50 pages each) when the request carries no credential or key; then 0.05 USD per call. The page list is the response itself: nothing is recorded, so a lost response cannot be recovered and the charge stands."
method: POST
path: "/discover"
---

# Discover the pages of a site. Free 5 times a day per client address (at most 50 pages each) when the request carries no credential or key; then 0.05 USD per call. The page list is the response itself: nothing is recorded, so a lost response cannot be recovered and the charge stands.

`POST /discover`

## Request

- Base URL: `https://app.difficat.com/api/v1`
- URL: `https://app.difficat.com/api/v1/discover`
- Auth: one of:
  - HTTP payment
  - HTTP bearer

## Request body

- DiscoverRequest
  - `sourceUrl` string, uri, required
  - `targetUrl` string, uri
  - `sitemapUrl` string, uri
  - `maxPages` integer: Stop after this many pages (default and at most 5000).

## Response `200`

OK

- DiscoverResponse
  - `pages` object[], required
    - `sourceUrl` string, uri, required
    - `targetUrl` string, uri
    - `path` string, required
  - `strategy` string
  - `truncated` boolean: The page ceiling cut the list.
  - `payment` Payment: What this call was charged. The amount is a decimal USD string ("0.10"); by contrast, the x-payment-info.amount advertised on each paid operation is USD cents as an integer string ("10"). A call settled from a prepaid balance carries rail "prepaid" and the remaining balance. A call paid with a Pro account’s key carries rail "subscription", the captured pages drawn from the included allowance (2 per live pair) and the pages left; its amount is what any leftover balance and overage paid, "0.00" when the allowance covered the call.
    - `amount` string, required
    - `currency` string, required
    - `rail` 'prepaid' | 'subscription'
    - `balance` string: Remaining prepaid balance, decimal USD.
    - `pagesFromAllowance` integer: Pro key: captured pages covered by the allowance, 2 per live pair.
    - `allowanceRemaining` integer: Pro key: captured pages left in the period.
  - `sample` boolean: Present and true when the call ran under the free daily allowance; payment is then absent.
  - `allowanceRemaining` integer: Free run: the units of this kind left for the address today.

## Other responses

- `400`: Invalid input or blocked URL
- `401`: Unknown, expired or blocked prepaid key; nextSteps names the ways to pay
- `402`: Payment required: the free daily allowance for this kind of call is used up, or the request carried a credential. The WWW-Authenticate header carries the Machine Payments Protocol challenge; pay and retry the identical request with the credential in the Authorization header. The body is the one failure that is not `{ error }`: an RFC 9457 problem document (type, title, status, detail, challengeId) plus nextSteps, every way a human can pay. A Link header (rel="payment") points at the prepaid top-up page. A request carrying a prepaid key whose balance is short receives the application/json body instead, with no challenge.
- `429`: Too many unpaid requests from this address this hour; Retry-After is set. A prepaid key the service holds is not counted
- `500`: The discovery failed after the charge settled; the charge is final and the response is not recoverable
- `502`: Discovery failed
- `503`: The balance could not be read or debited; nothing was charged
- `504`: Discovery timed out

---

[API](https://skmtc.dev/difficat/apis/difficat-agent-api.md) · [All operations](https://skmtc.dev/difficat/apis/difficat-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/difficat/apis/difficat-agent-api/revisions/49c291e77659?raw)