> ## 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 and learn the retry and timeout defaults they share. Both call the same API.

The official SDKs wrap the Stophy API for server-side code. Each language page shows a first request and what is specific to that language. To call Stophy from a terminal, use the [CLI](https://docs.stophy.dev/install-cli.md).

| Language | Package | Install | Runs on |
| - | - | - | - |
| [TypeScript](https://docs.stophy.dev/sdks/typescript.md) | [`stophy`](https://www.npmjs.com/package/stophy) | `npm install stophy` | Node.js, Bun, Deno and the browser |
| [Python](https://docs.stophy.dev/sdks/python.md) | [`stophy`](https://pypi.org/project/stophy/) | `pip install stophy` | Python 3.9 or later |

## Set your API key

Both SDKs read `STOPHY_API_KEY` from the environment when you do not pass a key to the client. Keep it in your secret store or your project's `.env` file.

Keep the key in server-side code. Never commit it or ship it to a browser. The [Quickstart](https://docs.stophy.dev/quickstart) shows where to get one. Without an API key, `scrape`, `search`, `map` and `parse` work within the [free limits](https://docs.stophy.dev/production/rate-limits.md). `parsers`, `endpoints`, `signup` and `signup.poll` need no API key. Every other method fails with the code `apiKeyRequired`.

## Methods

Each method sends one call to the [Stophy API](https://docs.stophy.dev/api-reference/introduction.md) and returns its JSON as it is.

| 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`, `GET /v1/endpoints` |
| `crawl`, `crawl.status`, `crawl.cancel` | `/v1/crawl` and `/v1/crawl/{id}` |
| `batch.scrape`, `batch.scrape.status`, `batch.scrape.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` |

The SDKs have 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), [feedback](https://docs.stophy.dev/production/agent-feedback.md), usage history or the team calls. Call those over HTTP with the same API key.

## Timeouts and retries

* Each attempt waits up to 70 seconds. The TypeScript SDK does not retry an attempt that timed out. The Python SDK retries it like a network error.
* Both SDKs retry twice after a network error and after the statuses 429, 500, 502, 503 and 504. The wait starts at 0.5 seconds and doubles, or follows `retryAfterSeconds` when the API sends it.
* If the API asks for a wait longer than 60 seconds, the SDK stops and throws with `retryAfterSeconds` set.
* A `DELETE` call is never retried.

Set `maxRetries` to `0` to turn retries off. For a call that takes longer than 70 seconds, raise the timeout. See [Timeouts](https://docs.stophy.dev/production/timeouts.md).

## Handle errors

Both SDKs throw a `StophyError` with `code`, `retryable`, `retryAfterSeconds`, `status` and the `requestId`. The message says what went wrong and what to do next. The codes are the API's own. See [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md).

A call your balance cannot cover fails with `insufficientCredits` and status `402`, and charges nothing. The message names your balance and the most the call can cost. Add money at [stophy.dev/billing](https://stophy.dev/billing) and send the call again. See [Pricing](https://docs.stophy.dev/account/pricing.md).

`401` with `apiKeyRequired` means the call needs an API key. `401` with `unauthorized` means the key is wrong or has been revoked.


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