DiffiCat Screenshots API

openapi: 3.2.0
info:
  title: Difficat Com Screenshots API
  version: 3.149.0
  description: 'Operations tagged Screenshots 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: Screenshots
paths:
  /screenshots:
    post:
      operationId: captureScreenshot
      summary: Capture a full-page screenshot.
      security:
      - payment: []
      - prepaidKey: []
      x-payment-info:
        amount: '2'
        currency: USD
        intent: charge
        description: 0.02 USD per call
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 255
        description: '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).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenshotRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenshotResponse'
              example:
                jobId: web-shot-5b1c0f0e-2d3a-4c4b-9d6e-7f8a9b0c1d2e
                filename: new-difficat-com.png
                url: https://new.difficat.com/
                dimensions:
                  width: 1280
                  height: 2400
                jobToken: dct_Qm9x2kL7pW3nR8vT1yB6cH0jF5sD2aG9eZ4uK7iN3oXb1
                links:
                  file: https://app.difficat.com/api/v1/jobs/web-shot-5b1c0f0e-2d3a-4c4b-9d6e-7f8a9b0c1d2e/files/new-difficat-com.png
                payment:
                  amount: '0.02'
                  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'
        '409':
          description: 'A prepaid request repeated its Idempotency-Key; jobId names the job already created. Without jobId the first request was charged but recorded no job (still running, or failed): list the key’s jobs with GET /jobs, or retry under a new Idempotency-Key'
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                  jobId:
                    type: string
        '422':
          description: The page could not be measured, so it was not captured, after the charge settled; the charge is final and the refused capture is recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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 work failed after the charge settled; the charge is final. A job or screenshot is still recorded under the credential (status failed), so POST /jobs/recover finds it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The balance could not be read or debited; nothing was charged
        '504':
          description: The capture timed out after the charge settled; the charge is final and the failed capture is recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Screenshots
    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'
    KeyRefusal:
      type: object
      required:
      - error
      - nextSteps
      properties:
        error:
          type: string
        nextSteps:
          $ref: '#/components/schemas/NextSteps'
    VisualRules:
      type: object
      description: Capture rules applied to both sides.
      additionalProperties: false
      properties:
        masks:
          type: array
          maxItems: 50
          description: CSS selectors of elements hidden on both sites before the screenshot (at most 50, each up to 200 characters). The layout keeps its place.
          items:
            type: string
            minLength: 1
            maxLength: 200
        freeze:
          type: object
          additionalProperties: false
          properties:
            animations:
              type: boolean
              description: Stop CSS animations and transitions before the screenshot.
            clock:
              type: boolean
              description: Pause timers and the clock after load; a page that needs a timer to render may stay empty.
            clockSeconds:
              type: integer
    ScreenshotRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          maxLength: 2048
        auth:
          $ref: '#/components/schemas/BasicAuth'
        viewportWidth:
          type: integer
          minimum: 320
          maximum: 2560
        visual:
          $ref: '#/components/schemas/VisualRules'
    BasicAuth:
      type: object
      required:
      - username
      - password
      properties:
        username:
          type: string
          description: Username for HTTP basic auth.
        password:
          type: string
          description: Password for HTTP basic auth.
    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.'
    ScreenshotResponse:
      type: object
      required:
      - jobId
      - jobToken
      - filename
      - url
      - dimensions
      - links
      properties:
        jobId:
          type: string
        jobToken:
          type: string
          description: Bearer token for the file link. Shown once.
        filename:
          type: string
        url:
          type: string
          format: uri
          maxLength: 2048
        dimensions:
          type: object
          properties:
            width:
              type: integer
            height:
              type: integer
        links:
          type: object
          properties:
            file:
              type: string
        payment:
          $ref: '#/components/schemas/Payment'
        pagesCharged:
          type: integer
          description: 0 on a free run.
        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