Start a comparison job. Free up to 40 pages a day per client address when the request carries no payment credential and no prepaid key: the response is the normal 201 with sample: true, pagesCharged: 0 and allowanceRemaining, and a job above the remaining allowance, or any request once it is used up, is challenged as usual with nextSteps in the 402 body. A sample report over three pages, produced by this API, is at https://difficat.com/agents/sample/report.json. Then 0.02 USD per compared pair (2 captured pages at 0.01 USD each) for the first 1000 pairs, 0.01 USD per pair beyond; a Pro account’s key draws 2 captured pages per pair from its monthly allowance instead. Compares Site A against Site B on page existence, content and visual regression. Visual captures cover the first 10,000 px of each page; a page cut there carries checks.visual.truncatedAt in the report. The job is priced on the pages it compares: the urls pairs, or the pages discovery finds, at most maxPages when given (an optional ceiling, not a reservation); there is no page limit, and the 402 challenge names the count and the exact amount. A single-page comparison is a urls list with one pair (preferred), or maxPages: 1 with the page URLs as sourceUrl and targetUrl; either is priced as one pair and runs no discovery. The discovery that prices a job without urls is not charged; POST /discover is a separate, optional purchase for callers who want the page list itself. Send dryRun: true to get the page count and exact amount without charging, using the free allowance or starting a job; without a credential or key the quote also carries allowanceRemaining and freeCovers, true when the same body would run free. Set maxPriceUsd to refuse a job priced above your budget before any challenge; a job the free allowance covers costs nothing and is not refused by it. A settled charge is final: cancelling, a failed job or partial results do not reduce it. POST /jobs/recover returns a job or screenshot whose create response was lost, given the same payment credential (a /discover response is not recoverable). A body names at most 20 distinct hosts, and a caller runs at most 3 jobs at once. Then GET /jobs/{id}?wait=<seconds> holds the response until the job ends (at most 300 s), or give callbackUrl to receive one JSON POST when it does; a terminal status read carries summary.issuesBySeverity, the verdict. Read /jobs/{id}/report?failedOnly=true first for the pages that failed, then the rest in pages.

post/jobs

Request

  • Base URL: https://app.difficat.com/api/v1
  • URL: https://app.difficat.com/api/v1/jobs
  • Auth: one of:
    • HTTP payment
    • HTTP bearer

Headers

Idempotency-Keystring

For a prepaid key: a retry of the same request (same route and body) carrying the same value within 24 hours is not debited again and is answered 409 naming the job the first request created; the same value on another body is a new request (draft-ietf-httpapi-idempotency-key-header).

Request body

OR

Response

Dry run: the quote, with nothing charged and no job started

dryRuntrue required
pagesPricedinteger required

The page count the job would be charged for.

amountstring required

The exact amount the same body without dryRun is charged.

currency'USD' required
allowanceRemaininginteger

For a request with no credential and no prepaid key: the comparison pages the client address may still run free today, read without consuming any.

freeCoversboolean

For a request with no credential and no prepaid key: true when the same body sent now without dryRun would run free (the priced pages are within allowanceRemaining and the shared daily pool).

Changes

No recorded changes to this operation across all 1 revision of this API.