> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Install the Stophy TypeScript or Python SDK, set your API key, call each endpoint and handle errors and retries. Both call the same API.

Each SDK method sends one call to the [API](https://docs.stophy.dev/api-reference/introduction.md) and returns its JSON. For terminal commands, use the [CLI](https://docs.stophy.dev/install-cli.md).

| Language | Install | Runs on |
| - | - | - |
| TypeScript | `npm install stophy` | Node.js, Bun, Deno and the browser |
| Python | `pip install stophy` | Python 3.9 or later |

## Set your API key

Set `STOPHY_API_KEY`, or pass the key to the client: `new Stophy(key)` or `new Stophy({ apiKey })` in TypeScript, `Stophy(api_key=...)` in Python. Keep it in server code. Get one in the [Quickstart](https://docs.stophy.dev/quickstart.md).

Without a key, `scrape`, `search`, `map` and `parse` work within the [free limits](https://docs.stophy.dev/production/rate-limits.md), and so do `parsers`, `endpoints`, `signup` and `signup.poll`. Any other method fails with `apiKeyRequired`. See [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Make a request

> [tab] TypeScript
>
> ```ts theme={null}
> import { Stophy } from "stophy";
>
> const stophy = new Stophy();
> const page = await stophy.scrape({ url: "https://example.com", formats: ["markdown"] });
> console.log(page.data.metadata.title, page.data.markdown);
> ```
>
> Pass the parser name and URL to `stophy.parsed()` to read a site's data at `data.json`. Parser options are the third argument, for example `{ page: 2 }`.

> [tab] Python
>
> ```python theme={null}
> from stophy import Stophy
>
> stophy = Stophy()
> page = stophy.scrape(url="https://example.com", formats=["markdown"])
> print(page["data"]["metadata"]["title"], page["data"]["markdown"])
> ```
>
> Arguments are keyword-only and snake\_case. Pass the parser name and URL to `stophy.parsed()` to read a site's data at `data["json"]`. Parser options are extra keywords, for example `page=2`. `AsyncStophy` has the same methods, and you `await` each call.

`parsed` calls `scrape` with `{ type: "json", parser }`, and `parsers()` lists every parser. See [Pre-built parsers](https://docs.stophy.dev/scrape/prebuilt-parsers).

## Methods

| Method | Endpoint |
| - | - |
| `scrape`, `search`, `map`, `parse` | `POST /v1/scrape`, `/v1/search`, `/v1/map`, `/v1/parse` |
| `parsed` | Scrape with a [parser](https://docs.stophy.dev/scrape/prebuilt-parsers) |
| `parsers`, `endpoints` | `GET /v1/parsers`, `/v1/endpoints` |
| `crawl`, `crawl.status`, `crawl.cancel` | `/v1/crawl` and `/v1/crawl/{id}` |
| `batch.scrape`, `.status`, `.cancel` | `/v1/batch/scrape` and `/v1/batch/scrape/{id}` |
| `extract`, `extract.result` | `POST /v1/extract`, `GET /v1/extract/{id}` |
| `browser.task`, `browser.task.status` | `/v1/browser/task` and `/v1/browser/task/status` |
| `signup`, `signup.poll`, `key.revoke` | `/v1/signup`, `/v1/signup/poll`, `DELETE /v1/key` |
| `limits`, `usage`, `logs` | `GET /v1/limits`, `/v1/usage`, `/v1/logs` |

There are no methods for [agent](https://docs.stophy.dev/agent/overview), [browser sessions](https://docs.stophy.dev/browser/overview), [monitors](https://docs.stophy.dev/monitors/overview), [webhooks](https://docs.stophy.dev/webhooks.md) or [feedback](https://docs.stophy.dev/production/agent-feedback.md). Call those over HTTP with the same key.

`crawl`, `batch.scrape` and `extract` answer with an `id`. Pass it to `.status` or `.result`. See [Read a crawl](https://docs.stophy.dev/crawl/async.md).

## Errors and retries

Catch `StophyError`. It has `code`, `message`, `retryable`, `status`, `details`, plus `retryAfterSeconds` and `requestId` in TypeScript or `retry_after_seconds` and `request_id` in Python. The message says what to do. The codes are the API's own. See [Errors](https://docs.stophy.dev/api-reference/errors.md).

Each attempt waits up to 70 seconds, and eligible calls retry twice with a backoff or the delay the API returns. The SDK throws instead of waiting more than 60 seconds. A `DELETE` is not retried.

If a write may have run and cannot be replayed safely, the error carries `outcomeUnknown` (`outcome_unknown` in Python). Check whether the work finished before you send it again. To recover a replayable write, reuse its idempotency key and the same body. Pass your own as `idempotencyKey` (`idempotency_key` in Python) and read it back from `error.details.idempotencyKey`. See [Timeouts](https://docs.stophy.dev/production/timeouts.md).

## Client options

> [tab] TypeScript
>
> | Option | Default | What it does |
> | - | - | - |
> | `apiKey` | `STOPHY_API_KEY` | Your API key |
> | `baseUrl` | `STOPHY_BASE_URL` | The server to call |
> | `maxRetries` | `2` | Retries per request. `0` turns them off. |
> | `retryInitialDelayMs` | `500` | First retry wait. It doubles each time. |
> | `timeoutMs` | `70000` | Limit for each attempt |
> | `headers` | none | Extra headers on every call |
> | `fetch` | global `fetch` | A replacement `fetch` |
>
> Pass `signal` as a method's second argument to cancel the request.

> [tab] Python
>
> | Option | Default | What it does |
> | - | - | - |
> | `api_key` | `STOPHY_API_KEY` | Your API key |
> | `base_url` | `STOPHY_BASE_URL` | The server to call |
> | `max_retries` | `2` | Retries per request. `0` turns them off. |
> | `retry_initial_delay` | `0.5` | First retry wait in seconds. It doubles each time. |
> | `timeout` | `70.0` | Limit in seconds for each attempt |
> | `headers` | none | Extra headers on every call |
>
> Use `with Stophy() as stophy:` or `async with AsyncStophy() as client:` to close the client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.