DiffiCat Discover API

openapi: 3.2.0
info:
  title: Difficat Com Discover API
  version: 3.149.0
  description: 'Operations tagged Discover across 2 of this provider''s published API definitions: difficat-com-agent-api-openapi.json, difficat-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.difficat.com/api/v1
tags:
- name: Discover
paths:
  /discover:
    post:
      operationId: discoverPages
      summary: Discover the pages of a site.
      security:
      - payment: []
      - prepaidKey: []
      x-payment-info:
        amount: '5'
        currency: USD
        intent: charge
        description: 0.05 USD per call
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoverRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverResponse'
              example:
                pages:
                - path: /
                  sourceUrl: https://old.difficat.com/
                  targetUrl: https://new.difficat.com/
                - path: /pricing.html
                  sourceUrl: https://old.difficat.com/pricing.html
                  targetUrl: https://new.difficat.com/pricing.html
                strategy: sitemap-xml
                payment:
                  amount: '0.05'
                  currency: USD
        '400':
          description: Invalid input or blocked URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unknown, expired or blocked prepaid key; nextSteps names the ways to pay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRefusal'
        '402':
          description: 'Payment required: the free 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.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/PrepaidRefusal'
        '429':
          description: Too many unpaid requests from this address this hour; Retry-After is set. A prepaid key the service holds is not counted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The discovery failed after the charge settled; the charge is final and the response is not recoverable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Discovery failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The balance could not be read or debited; nothing was charged
        '504':
          description: Discovery timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Discover
    servers:
    - url: https://app.difficat.com/api/v1
components:
  schemas:
    NextSteps:
      type: object
      description: 'Carried by every 401 and 402: how to pay (a prepaid key topped up on the account page, a Pro account, or the wallet rail the challenge names) and where to send feedback. No address, credential or price beyond the offered top-up amounts.'
      required:
      - pro
      - feedback
      properties:
        prepaid:
          type: object
          description: Present while prepaid is offered.
          required:
          - topUp
          - amountsUsd
          properties:
            topUp:
              type: string
              format: uri
              description: The account page, where a signed-in human tops up.
            amountsUsd:
              type: array
              items:
                type: integer
        pro:
          type: string
          format: uri
          description: The Pro account page.
        wallet:
          type: string
          description: The configured wallet rail; absent without one.
        feedback:
          type: object
          required:
          - url
          - tool
          properties:
            url:
              type: string
              format: uri
              description: POST /feedback, absolute.
            tool:
              type: string
              enum:
              - send_feedback
        allowanceResetsAt:
          type: string
          format: date-time
          description: When the caller’s free allowance for this kind of call next resets; absent when the allowance store did not answer.
        free:
          type: string
          description: 'On an unpaid call naming a published example host only: says your user''s own URLs and the demo sites run on the one-time free allowance with no key.'
    PrepaidRefusal:
      type: object
      required:
      - error
      - balance
      - amount
      - topUp
      - nextSteps
      properties:
        error:
          type: string
          enum:
          - Insufficient prepaid balance
        balance:
          type: string
          description: The key’s balance, decimal USD.
        amount:
          type: string
          description: The priced amount, decimal USD.
        topUp:
          type: string
          format: uri
          description: The top-up page.
        nextSteps:
          $ref: '#/components/schemas/NextSteps'
    DiscoverRequest:
      type: object
      required:
      - sourceUrl
      properties:
        sourceUrl:
          type: string
          format: uri
          maxLength: 2048
        targetUrl:
          type: string
          format: uri
          maxLength: 2048
        sitemapUrl:
          type: string
          format: uri
          maxLength: 2048
        maxPages:
          type: integer
          minimum: 1
          maximum: 5000
          description: Stop after this many pages (default and at most 5000).
    KeyRefusal:
      type: object
      required:
      - error
      - nextSteps
      properties:
        error:
          type: string
        nextSteps:
          $ref: '#/components/schemas/NextSteps'
    Payment:
      type: object
      description: 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.
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          example: '0.50'
        currency:
          type: string
        rail:
          type: string
          enum:
          - prepaid
          - subscription
        balance:
          type: string
          description: Remaining prepaid balance, decimal USD.
        pagesFromAllowance:
          type: integer
          description: 'Pro key: captured pages covered by the allowance, 2 per live pair.'
        allowanceRemaining:
          type: integer
          description: 'Pro key: captured pages left in the period.'
    DiscoverResponse:
      type: object
      required:
      - pages
      properties:
        pages:
          type: array
          items:
            type: object
            required:
            - sourceUrl
            - path
            properties:
              sourceUrl:
                type: string
                format: uri
                maxLength: 2048
              targetUrl:
                type: string
                format: uri
                maxLength: 2048
              path:
                type: string
        strategy:
          type: string
        truncated:
          type: boolean
          description: The page ceiling cut the list.
        payment:
          $ref: '#/components/schemas/Payment'
        sample:
          type: boolean
          description: Present and true when the call ran under the free allowance; payment is then absent.
        allowanceRemaining:
          type: integer
          description: 'Free run: the units of this kind left for the address today.'
    Problem:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - challengeId
      - nextSteps
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          enum:
          - 402
        detail:
          type: string
        challengeId:
          type: string
        nextSteps:
          $ref: '#/components/schemas/NextSteps'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  securitySchemes:
    payment:
      type: http
      scheme: Payment
      description: 'Machine Payments Protocol (mpp.dev). A first request without a credential is answered with 402 and a WWW-Authenticate: Payment challenge; the paid retry carries Authorization: Payment <credential>. Successful responses carry a Payment-Receipt header. x402 clients are accepted on the same routes for USDC on Base.'
    jobToken:
      type: http
      scheme: bearer
      description: The jobToken returned when the job or screenshot was created. The prepaid key that paid a job is accepted in its place.
    prepaidKey:
      type: http
      scheme: bearer
      description: A prepaid key (dck_…) from the account page at /account, where a signed-in human tops up by card through Stripe Checkout and copies the key. On a paid call the priced amount is debited from its balance instead of a 402 challenge; on job reads it stands in for the jobToken of the jobs it paid.
    shareToken:
      type: http
      scheme: bearer
      description: A share token (dcs_…) a snapshot’s owner issued in the web app. It reads that one snapshot and starts live compares against it; it never lists, manages or pays.
    shareTokenHeader:
      type: apiKey
      in: header
      name: X-DiffiCat-Share
      description: The same share token, sent beside a paying Authorization credential (a prepaid or Pro key, or a payment credential) on the two compare routes.
x-refined-from:
- difficat-com-agent-api-openapi.json
- difficat-com-openapi.yml
x-service-info:
  categories:
  - web
  - testing
  - monitoring
  docs:
    homepage: https://difficat.com
    llms: https://difficat.com/llms.txt
    apiReference: https://app.difficat.com/api/v1/openapi.json
  x-prepaid:
    topUp: https://app.difficat.com/account
    amountsUsd:
    - 5
    - 10
    - 25
  x-sample:
    report: https://difficat.com/agents/sample/report.json
    freePages: 40
    freeDiscoveries: 5
    freeScreenshots: 5