Screenshot Endpoints

Screenshots are part of All tools. A start needs the relevant scope and enough credits, and the tool must be available in /v1/health. Free credits also follow the free limits. Accepted starts return 202 Accepted.

The endpoint is preview. Preview means the contract may still evolve before stable release.

Shared Access

• Access: Paid plans that include this family, or free credits (guest trial or verified account) within the free limits.
• Operation family: Screenshots
• Scope: api:screenshot:write
• Live idempotency: Idempotency-Key header required
• Dry run: no Idempotency-Key required, and any supplied key is ignored
• Target URLs: absolute http or https URLs only

Chab rejects private, local, metadata-service, credential-bearing, and secret-query target URLs before operation work starts. For screenshot capture, Chab validates and pre-resolves the submitted url before browser handoff and relies on provider egress isolation after that handoff.

Unsupported fields are rejected with validation_failed. Screenshot endpoints do not accept cookies, login/session/auth fields, proxy settings, custom scripts, multi-step browsing, crawling/sitemap controls, video capture, visual diff controls, or scrape-specific fields such as wait_for_selector.

Pricing

Viewport and element screenshots reserve 10 credits. Full-page screenshots reserve 15 credits.

If capture succeeds, Chab settles the reserved amount. URL-safety failures before browser work are not charged. Capture timeouts and capture engine failures after browser work starts are charged at the reserved screenshot estimate. If Chab cannot persist the screenshot artifact after a successful capture, the operation fails with artifact_creation_failed and releases the hold.

See Credits and Billing.

Dry Run

Set dry_run=true to validate the request, target, callback settings, plan, usage limits, provider readiness, token budget, spend threshold, and credit availability without creating an operation or reserving credits.

Dry runs return 200 OK with meta.dry_run=true. They do not create idempotency rows, operation rows, billing holds, callback secrets, provider tasks, artifacts, risk signals, notifications, or rate-bucket hits. Live requests still require Idempotency-Key.

curl -X POST https://www.chab.ai/v1/screenshots/url \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "full_page": true,
    "format": "png",
    "dry_run": true
  }'

Example dry-run response:

{
  "data": {
    "operation_key": "screenshots.url",
    "family": "screenshots",
    "estimated_credits": 15,
    "currency": "credit",
    "capture_mode": "full_page",
    "target": {
      "url": "https://example.com/report",
      "validated": true,
      "safety_posture": "initial_url_preflight"
    },
    "viewport": {
      "width": 1280,
      "height": 720
    },
    "device_scale_factor": 1,
    "full_page": true,
    "element_selector": null,
    "format": "png",
    "headers": {
      "accepted_names": [],
      "values_redacted": true
    },
    "callback": {
      "requested": false,
      "enabled": false,
      "url": null,
      "events": [],
      "notify_on_expiration": false,
      "secret_staged": false
    },
    "live_request": {
      "requires_idempotency_key": true
    }
  },
  "meta": {
    "request_id": "req_123",
    "dry_run": true
  }
}

POST/v1/screenshots/url

Creates a screenshot capture operation for one URL.

Required Access

• Credits: 10 viewport or element credits, or 15 full-page credits reserved on acceptance
• Scope: api:screenshot:write

Request

{
  "url": "https://example.com/report",
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "device_scale_factor": 1,
  "full_page": false,
  "format": "png"
}

Curl example:

curl -X POST https://www.chab.ai/v1/screenshots/url \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: screenshot-report-001" \
  -d '{
    "url": "https://example.com/report",
    "viewport": { "width": 1440, "height": 900 },
    "format": "png"
  }'

CLI-shaped client example:

screenshot url https://example.com/report \
  --viewport 1440x900 \
  --format png \
  --idempotency-key screenshot-report-001 \
  --wait

Fields:

• url: required absolute http or https URL.
• dry_run: optional boolean. When true, validates and estimates without side effects.
• viewport.width: optional integer from 320 to 1920; defaults to 1280.
• viewport.height: optional integer from 240 to 1080; defaults to 720.
• device_scale_factor: optional 1 or 2; defaults to 1.
• full_page: optional boolean; defaults to false.
• element_selector: optional CSS selector for element-only capture. Cannot be used with full_page=true.
• wait_until: optional load, domcontentloaded, or networkidle; defaults to networkidle.
• wait_ms: optional integer from 0 to 10000 for extra wait time after page readiness.
• block_ads: optional boolean; defaults to true.
• suppress_cookie_banners: optional boolean; defaults to true.
• format: optional png or jpeg; defaults to png.
• quality: optional JPEG quality from 1 to 100. It is accepted only when format is jpeg and defaults to 80 for JPEG.
• headers.accept, headers.accept_language, and headers.user_agent: optional outbound request headers. Credential-bearing values are rejected. Header values are never returned in public responses or operation summaries; Chab stores only accepted header names and redacted markers publicly.
• callback_url, callback_secret, callback_events, and callback_notify_on_expiration: optional one-off operation callback fields.

Async Response

{
  "operation": {
    "id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "status": "queued",
    "operation_key": "screenshots.url",
    "family": "screenshots",
    "status_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "result_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result",
    "estimated_credits": 10,
    "result_available": false,
    "warnings": []
  },
  "meta": {
    "request_id": "req_123",
    "credits": {
      "estimated": 10,
      "reserved": 10,
      "currency": "credit"
    }
  }
}

Screenshot Result

GET /v1/operations/{id}/result returns capture facts and the protected artifact reference after success:

{
  "data": {
    "result": {
      "final_url": "https://example.com/report",
      "dimensions": {
        "width": 1440,
        "height": 900
      },
      "capture_mode": "viewport",
      "viewport": {
        "width": 1440,
        "height": 900
      },
      "device_scale_factor": 1,
      "format": "png",
      "mime_type": "image/png",
      "byte_size": 98241,
      "captured_at": "2026-07-14T12:00:00+00:00",
      "elapsed_ms": 1240,
      "primary_artifact_role": "screenshot"
    },
    "artifacts": [
      {
        "id": "art_01JZ7H0A1B2C3D4E5F6G7H8J9K",
        "type": "image",
        "role": "screenshot",
        "mime_type": "image/png",
        "byte_size": 98241,
        "checksum": "sha256:abc123",
        "filename": "screenshot-op_01JZ7H0A1B2C3D4E5F6G7H8J9K.png",
        "metadata_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K",
        "download_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K/download",
        "expires_at": "2026-07-17T12:00:00+00:00"
      }
    ],
    "warnings": [],
    "result_expires_at": "2026-07-17T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

Download the image through the artifact download_url. Artifact metadata and downloads use the same protected operation-artifact routes described in Operations.

For a screenshot created through hosted MCP, call chab_operation_artifact with content: "inline" for PNG/JPEG images up to 2 MiB, or content: "link" to download larger images. See Hosted MCP for current limits.

Target URL Errors

Initial target URL safety failures return validation_failed before an operation row is created. Runtime target safety failures return target_fetch_blocked, release the hold, and do not create a screenshot artifact. See Errors, Rate Limits, and Pagination.

Capture Errors

For billing, selector_not_found, capture_timeout, and capture_failed settle the reserved screenshot estimate. artifact_creation_failed releases the hold because capture output could not be made available.