# ByteKit Documentation

> ByteKit is a web data API for AI agents and pipelines: scrape, screenshot, and monitor any URL.
>
> - Base URL: https://api.bytekit.com
> - Auth: `Authorization: Bearer $BYTEKIT_API_KEY` (create a key at https://app.bytekit.com)
> - Install: `npm install @hunt-labs/bytekit-sdk` (TypeScript) or `pip install bytekit-sdk` (Python, `import bytekit`)

## Getting started

- [ByteKit](https://bytekit.com/docs): The web data API for AI agents and pipelines — scrape, screenshot, and monitor any URL through one endpoint.
- [Introduction](https://bytekit.com/docs/api/md/introduction): A REST API for screenshots, scraping, and page-change monitoring — one key, one base URL, every output.
- [Quickstart](https://bytekit.com/docs/api/md/quickstart): Make your first ByteKit API call in under 5 minutes — no SDK required.

## Client Libraries

- [Client Libraries](https://bytekit.com/docs/api/md/libraries): The official TypeScript and Python clients, and how to call ByteKit from Go.
- [TypeScript SDK](https://bytekit.com/docs/api/md/libraries/typescript): Type-safe ByteKit client for Node.js and modern JavaScript runtimes.
- [Python SDK](https://bytekit.com/docs/api/md/libraries/python): Official Python client for ByteKit, with sync and async support.
- [Go](https://bytekit.com/docs/api/md/libraries/go): Call the ByteKit REST API from Go with the standard library.

## MCP Server

- [MCP Server](https://bytekit.com/docs/api/md/mcp): Call ByteKit web capture as a native tool from Claude, Cursor, and any MCP-compatible agent — hosted over HTTP or run locally over stdio.

## Guides

- [Guides](https://bytekit.com/docs/api/md/guides): Task-oriented walkthroughs of authentication, scraping, errors, limits, monitors, and webhooks.
- [Authentication](https://bytekit.com/docs/api/md/guides/authentication): How to authenticate with the ByteKit API using API keys.
- [Scraping](https://bytekit.com/docs/api/md/guides/scraping): Scrape any URL as HTML, markdown, or structured content — formats, options, latency, and async polling.
- [Errors](https://bytekit.com/docs/api/md/guides/errors): ByteKit error response shape, common error codes, and retry guidance.
- [Rate Limits](https://bytekit.com/docs/api/md/guides/rate-limits): How ByteKit enforces quotas, concurrency slots, and rate limits.
- [Monitors](https://bytekit.com/docs/api/md/guides/monitors): Detect page changes on any URL — by screenshot or scrape — and receive webhook notifications.
- [Webhooks](https://bytekit.com/docs/api/md/guides/webhooks): Verify ByteKit webhook deliveries — signature and timestamp headers, the HMAC-SHA256 scheme, and Node and Python verification code.

## Billing

- [Billing](https://bytekit.com/docs/api/md/billing): How ByteKit prices bandwidth and credits, and how balances, top-ups, and spending controls behave.
- [Balance and exhausted quota](https://bytekit.com/docs/api/md/billing/balance): What happens when a ByteKit bandwidth or credit balance reaches zero.
- [Bandwidth billing](https://bytekit.com/docs/api/md/billing/bandwidth): How ByteKit measures billed bandwidth for capture and sitemap endpoints.
- [Credit billing](https://bytekit.com/docs/api/md/billing/credits): How search and schema extraction consume credits.
- [Top-ups and rollover](https://bytekit.com/docs/api/md/billing/top-ups): How your USD balance is spent, why it never expires, and how plan allowance rolls over.
- [Spending controls](https://bytekit.com/docs/api/md/billing/spending): How spending caps and automatic top-ups behave.

## API Reference

- [API Reference](https://bytekit.com/docs/api/md/api): Every ByteKit endpoint, request, and response.
- [Health](https://bytekit.com/docs/api/md/api/health): Health API — endpoints, requests, and responses.
- [Health check](https://bytekit.com/docs/api/md/api/health/healthcheck)
- [Account](https://bytekit.com/docs/api/md/api/account): Account API — endpoints, requests, and responses.
- [Get account details](https://bytekit.com/docs/api/md/api/account/getaccount): Returns account, plan, and current API key details, including the `api_key` and `subscription` fields.
- [Screenshots](https://bytekit.com/docs/api/md/api/screenshots): Screenshots API — endpoints, requests, and responses.
- [Capture a screenshot](https://bytekit.com/docs/api/md/api/screenshots/createscreenshot): Sync by default (holds up to 28s). Pass `?async=true` to return 202 immediately. Poll via GET /v1/screenshots/{id}.
- [Get screenshot status](https://bytekit.com/docs/api/md/api/screenshots/getscreenshot)
- [Scrape](https://bytekit.com/docs/api/md/api/scrape): Scrape API — endpoints, requests, and responses.
- [Scrape a URL](https://bytekit.com/docs/api/md/api/scrape/createscrape): Fetches and processes a URL, returning content in one or more formats wrapped in a ScrapeEnvelope.
- [Get scrape result](https://bytekit.com/docs/api/md/api/scrape/getscrape): Always returns 200. Check the `status` discriminator for the scrape state.
- [Scrape Bulk](https://bytekit.com/docs/api/md/api/scrape-bulk): Scrape Bulk API — endpoints, requests, and responses.
- [Bulk scrape URLs](https://bytekit.com/docs/api/md/api/scrape-bulk/createscrapebulk): Enqueues multiple URLs for scraping. Results delivered via webhook. Completion deliveries use `X-ByteKit-Event: bulk.completed` and the `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB, followed by cursor recovery through `GET /v1/scrape/bulk/{id}` whenever `recovery_required` is true.
- [Get scrape bulk job status](https://bytekit.com/docs/api/md/api/scrape-bulk/getscrapebulk): Returns the job envelope plus its rehydrated per-URL scrape envelopes.
- [Fetch](https://bytekit.com/docs/api/md/api/fetch): Fetch API — endpoints, requests, and responses.
- [Fetch a URL (GET)](https://bytekit.com/docs/api/md/api/fetch/getfetch): Direct HTTP fetch. Successful responses return the upstream response bytes verbatim; metadata is returned in X-Fetch-* headers. Non-2xx upstream responses use the `upstream_error` JSON envelope with the upstream HTTP status.
- [Fetch a URL (POST)](https://bytekit.com/docs/api/md/api/fetch/postfetch): Same as GET /v1/fetch but with a JSON request body.
- [Fetch Bulk](https://bytekit.com/docs/api/md/api/fetch-bulk): Fetch Bulk API — endpoints, requests, and responses.
- [Bulk fetch URLs](https://bytekit.com/docs/api/md/api/fetch-bulk/createfetchbulk): Enqueues multiple URLs for HTTP fetching. Results delivered via webhook. Does not support options that require page rendering (wait_for_selector, etc.). Completion deliveries use `X-ByteKit-Event: bulk.completed` and the `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB, followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever `recovery_required` is true.
- [Get fetch bulk job status](https://bytekit.com/docs/api/md/api/fetch-bulk/getfetchbulk): Returns the job envelope plus its per-URL items.
- [Bulk](https://bytekit.com/docs/api/md/api/bulk): Bulk API — endpoints, requests, and responses.
- [List bulk jobs](https://bytekit.com/docs/api/md/api/bulk/listbulk): Returns the caller's bulk jobs, most recent first, one cursor-paginated page at a time. Optionally filter to a single status; when omitted, jobs of every status are returned. `status` narrows the set and the cursor addresses a position inside that already-ordered, already-filtered set, so the two can be combined in one request. Follow `next_cursor` while `has_more` is true.
- [Create mixed bulk job](https://bytekit.com/docs/api/md/api/bulk/createbulk): Enqueues screenshots or scrapes in a single batch. Provide `urls` (simple list) or `items` (per-item config), not both. Webhook deliveries include `X-ByteKit-Event: bulk.completed` so receivers can dispatch on the header without parsing the body shape. The body follows `BulkCompletedWebhook`: at most 500 complete items and 1 MiB, followed by cursor recovery through the existing mixed-item route whenever `recovery_required` is true.
- [Get bulk job status](https://bytekit.com/docs/api/md/api/bulk/getbulk)
- [Cancel a bulk job](https://bytekit.com/docs/api/md/api/bulk/deletebulk): Cancels an in-flight bulk job: drains its still-queued (pending) child jobs and refunds the quota held for exactly those drained children. Children already completed, failed, or in progress are untouched and keep their charge. Idempotent — cancelling an already-terminal job (completed, failed, or cancelled) is a no-op that returns 200 with the job's real, unchanged status and refunds nothing.
- [List bulk job items](https://bytekit.com/docs/api/md/api/bulk/listbulkscreenshots): Returns the bulk job's items, discriminated by `type`.
- [Monitors](https://bytekit.com/docs/api/md/api/monitors): Monitors API — endpoints, requests, and responses.
- [List monitors](https://bytekit.com/docs/api/md/api/monitors/listmonitors)
- [Create a change-detection monitor](https://bytekit.com/docs/api/md/api/monitors/createmonitor): Creates a recurring change-detection monitor for a URL, delivering results via webhook.
- [Get monitor](https://bytekit.com/docs/api/md/api/monitors/getmonitor)
- [Update monitor](https://bytekit.com/docs/api/md/api/monitors/updatemonitor)
- [Cancel monitor](https://bytekit.com/docs/api/md/api/monitors/deletemonitor)
- [List monitor captures](https://bytekit.com/docs/api/md/api/monitors/listmonitorcaptures)
- [Sitemap](https://bytekit.com/docs/api/md/api/sitemap): Sitemap API — endpoints, requests, and responses.
- [Discover URLs on a domain](https://bytekit.com/docs/api/md/api/sitemap/createsitemap): Crawls a domain to build a sitemap. Returns cached results if available within cache_ttl. Results delivered via webhook and downloadable from results_url. Webhook deliveries include `X-ByteKit-Event: sitemap.completed` or `X-ByteKit-Event: sitemap.failed` so receivers can dispatch on the header without parsing the body shape.
- [Get sitemap job status](https://bytekit.com/docs/api/md/api/sitemap/getsitemap)
- [Plans](https://bytekit.com/docs/api/md/api/plans): Plans API — endpoints, requests, and responses.
- [List public plan catalog](https://bytekit.com/docs/api/md/api/plans/listplans): Returns the catalog of public plans (`is_custom = false`) as the pricing source-of-truth for the dashboard and marketing site. Custom contract plans are excluded. Unauthenticated — this is catalog data, not per-account state (per-account plan lives on `GET /v1/account`).
- [Schema](https://bytekit.com/docs/api/md/api/schema): Schema API — endpoints, requests, and responses.
- [Schema-driven structured extraction](https://bytekit.com/docs/api/md/api/schema/createschemaextraction): Fetches `url` and extracts structured JSON conforming to the supplied JSON Schema (draft 2020-12) using an LLM. Fast-path only — slow-path rendering options (`wait_until=networkidle`, `delay_ms`, `wait_for_selector`) cause a `400 unsupported_option`.
- [Search](https://bytekit.com/docs/api/md/api/search): Search API — endpoints, requests, and responses.
- [Search the web](https://bytekit.com/docs/api/md/api/search/createsearch): Runs a web search for `query` and returns ranked organic results with contiguous `position` values from 1.
- [Usage](https://bytekit.com/docs/api/md/api/usage): Usage API — endpoints, requests, and responses.
- [Get current billing period usage](https://bytekit.com/docs/api/md/api/usage/getusage)
- [Get daily usage breakdown](https://bytekit.com/docs/api/md/api/usage/getusagedaily): Default range is last 30 days. Max range is 366 days.
- [Get per-endpoint bandwidth breakdown](https://bytekit.com/docs/api/md/api/usage/getusagebyendpoint): Returns bandwidth usage broken down by endpoint (screenshots, recordings, scrape, scrape_md, fetch, fetch_md, crawl, crawl_links, sitemap, monitors) for a date range. Each row carries raw bytes, the billing multiplier, and billable bytes. Endpoints with zero raw bytes for the range are omitted from `rows`; `totals` is always present. Default range is the last 30 days; max 366 days.
- [Webhooks](https://bytekit.com/docs/api/md/api/webhooks): Webhooks API — endpoints, requests, and responses.
- [List webhook deliveries](https://bytekit.com/docs/api/md/api/webhooks/listwebhookdeliveries)
- [Retry a webhook delivery](https://bytekit.com/docs/api/md/api/webhooks/retrywebhookdelivery): Requeues a failed or exhausted webhook delivery for another attempt.

## SDK Reference

- [SDK Reference](https://bytekit.com/docs/api/md/sdk): Per-resource reference for the ByteKit TypeScript and Python SDKs.
- [Client](https://bytekit.com/docs/api/md/sdk/typescript/client): Instantiate and configure the ByteKit TypeScript client.
- [Scrape](https://bytekit.com/docs/api/md/sdk/typescript/scrape): Fetch a URL as raw HTML, clean markdown, or structured content.
- [Screenshots](https://bytekit.com/docs/api/md/sdk/typescript/screenshots): Capture full-page or viewport screenshots.
- [Bulk](https://bytekit.com/docs/api/md/sdk/typescript/bulk): Fan out many URLs in parallel with per-item webhooks.
- [Fetch](https://bytekit.com/docs/api/md/sdk/typescript/fetch): Low-latency raw HTTP fetch with byte-for-byte upstream responses.
- [Fetch Bulk](https://bytekit.com/docs/api/md/sdk/typescript/fetch-bulk): Create and poll bulk fetch jobs.
- [Scrape Bulk](https://bytekit.com/docs/api/md/sdk/typescript/scrape-bulk): Create and poll bulk scrape jobs.
- [Monitors](https://bytekit.com/docs/api/md/sdk/typescript/monitors): Watch a URL on a schedule and webhook on change.
- [Sitemap](https://bytekit.com/docs/api/md/sdk/typescript/sitemap): Discover URLs from a domain's sitemap or by crawling.
- [Search](https://bytekit.com/docs/api/md/sdk/typescript/search): Run a web search and return ranked organic results.
- [Account](https://bytekit.com/docs/api/md/sdk/typescript/account): Account info and API key management.
- [Usage](https://bytekit.com/docs/api/md/sdk/typescript/usage): Billing-period and daily usage breakdowns.
- [Webhooks](https://bytekit.com/docs/api/md/sdk/typescript/webhooks): List and retry webhook deliveries.
- [Client](https://bytekit.com/docs/api/md/sdk/python/client): HTTP client classes for the ByteKit Python SDK.
- [Scrape](https://bytekit.com/docs/api/md/sdk/python/scrape): API functions for the Scrape resource.
- [Screenshots](https://bytekit.com/docs/api/md/sdk/python/screenshots): API functions for the Screenshots resource.
- [Bulk](https://bytekit.com/docs/api/md/sdk/python/bulk): API functions for the Bulk resource.
- [Fetch](https://bytekit.com/docs/api/md/sdk/python/fetch): API functions for the Fetch resource.
- [Fetch Bulk](https://bytekit.com/docs/api/md/sdk/python/fetch-bulk): API functions for the Fetch Bulk resource.
- [Scrape Bulk](https://bytekit.com/docs/api/md/sdk/python/scrape-bulk): API functions for the Scrape Bulk resource.
- [Monitors](https://bytekit.com/docs/api/md/sdk/python/monitors): API functions for the Monitors resource.
- [Sitemap](https://bytekit.com/docs/api/md/sdk/python/sitemap): API functions for the Sitemap resource.
- [Search](https://bytekit.com/docs/api/md/sdk/python/search): API functions for the Search resource.
- [Account](https://bytekit.com/docs/api/md/sdk/python/account): API functions for the Account resource.
- [Usage](https://bytekit.com/docs/api/md/sdk/python/usage): API functions for the Usage resource.
- [Webhooks](https://bytekit.com/docs/api/md/sdk/python/webhooks): API functions for the Webhooks resource.

## CLI

- [Install & Authenticate](https://bytekit.com/docs/api/md/cli): Install the ByteKit CLI, authenticate, and learn the global flags shared by every command.
- [Scrape](https://bytekit.com/docs/api/md/cli/scrape): Scrape URL content
- [Screenshots](https://bytekit.com/docs/api/md/cli/screenshots): Screenshot operations
- [Bulk](https://bytekit.com/docs/api/md/cli/bulk): Bulk screenshot operations
- [Fetch](https://bytekit.com/docs/api/md/cli/fetch): Fetch URL content operations
- [Monitors](https://bytekit.com/docs/api/md/cli/monitors): Page-change monitor operations
- [Sitemap](https://bytekit.com/docs/api/md/cli/sitemap): Sitemap crawl operations
- [Search](https://bytekit.com/docs/api/md/cli/search): Run a web search and return ranked results
- [Account](https://bytekit.com/docs/api/md/cli/account): Account operations
- [Usage](https://bytekit.com/docs/api/md/cli/usage): Account usage and billing-period reporting
- [Webhook-deliveries](https://bytekit.com/docs/api/md/cli/webhook-deliveries): Webhook delivery operations

## Changelog

- [Changelog](https://bytekit.com/docs/api/md/changelog): Release history for the ByteKit SDKs, CLI, and MCP server