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

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# SDKs

> TypeScript and Python clients generated from Peel's OpenAPI contract. They are not published to npm or PyPI yet, so install them from source.

Peel has a TypeScript SDK and a Python SDK. Both are generated from the same OpenAPI contract that the API Reference is built from, so every REST operation that takes an API key or no auth has a typed method in each, and a small hand-written layer adds the calls you use most. Neither has a runtime dependency: the TypeScript client uses `fetch` and the Python client uses the standard library.

> [!WARNING]
>
> The SDKs are not published to npm or PyPI yet, so for now installing them needs a checkout of the Peel repository. Without one, call the [REST API](https://docs.peel.sh/getting-started/quickstart.md) directly with any HTTP client. Do not install a package named `peel` from a registry; it is an unrelated project.

## Install from source

From the root of a checkout of the Peel repository:

```bash TypeScript theme={null}
bun install
bun run --cwd sdk/typescript build
cd /path/to/your/app
npm install /path/to/peel-source/sdk/typescript
```

```bash Python theme={null}
python3 -m pip install ./sdk/python
```

The TypeScript package is `@peel/sdk` and needs Node 20.3 or later, Bun or a current browser. The Python package imports as `peel` and needs Python 3.10 or later.

## Call a marketplace endpoint without a key

Marketplace endpoints answer without a key, on [Peel's trial allowance](https://docs.peel.sh/features/marketplace.md#call-without-an-account). This calls the Hacker News front page endpoint, which takes no inputs:

```ts TypeScript theme={null}
import { Peel } from "@peel/sdk";

const peel = new Peel();
const result = await peel.marketplaceCall("kd74n2353r515czbkq7kaet9tx8jctwy", "front_page_stories", {});
console.log(result.data.data);
```

```python Python theme={null}
from peel import PeelClient

peel = PeelClient()
result = peel.marketplace_call("kd74n2353r515czbkq7kaet9tx8jctwy", "front_page_stories", {})
print(result.data["data"])
```

## Call your API with a key and a shape

Pass the key from [Authentication](https://docs.peel.sh/getting-started/authentication.md). The client sends it as `X-API-Key`; pass `auth: "bearer"` (TypeScript) or `auth="bearer"` (Python) to send `Authorization: Bearer` instead. A [shape](https://docs.peel.sh/features/shapes.md) goes in the `Peel-Shape` header for you:

```ts TypeScript theme={null}
import { Peel } from "@peel/sdk";

const peel = new Peel({ apiKey: process.env.PEEL_API_KEY });
const result = await peel.call(process.env.PEEL_API_ID!, "list_books", { page: 1 }, {
  shape: { sort: [{ field: "price", order: "asc" }], limit: 5, fields: ["title", "price"] },
});
console.log(result.data.data, result.data.credits_charged);
```

```python Python theme={null}
import os

from peel import PeelClient

peel = PeelClient(os.environ["PEEL_API_KEY"])
result = peel.call(
    os.environ["PEEL_API_ID"],
    "list_books",
    {"page": 1},
    shape={"sort": [{"field": "price", "order": "asc"}], "limit": 5, "fields": ["title", "price"]},
)
print(result.data["data"], result.data["credits_charged"])
```

`call` also takes `version` to run one version of the API (sent as `Peel-Version`), `session` for endpoints that need a site login, and `idempotencyKey` (`idempotency_key` in Python).

## Build an API and wait for it

`build` starts a build and, with `wait`, follows it on the long-poll route until it completes, fails or asks a question:

```ts TypeScript theme={null}
import { Peel } from "@peel/sdk";

const peel = new Peel({ apiKey: process.env.PEEL_API_KEY });
const built = await peel.build("https://books.toscrape.com", {
  instructions: "List books with title, price and rating",
  wait: true,
});
console.log(built.data.api.status, built.data.api.endpoints.map((endpoint) => endpoint.endpoint_name));
```

```python Python theme={null}
import os

from peel import PeelClient

peel = PeelClient(os.environ["PEEL_API_KEY"])
built = peel.build(
    "https://books.toscrape.com",
    instructions="List books with title, price and rating",
    wait=True,
)
print(built.data["api"]["status"], [endpoint["endpoint_name"] for endpoint in built.data["api"]["endpoints"]])
```

## What the clients do for you

| Behaviour | Detail |
| - | - |
| Setup | The client refuses, with `PeelError` code `invalid_option` and before any request, an API key that does not start with `sk_urlapi_`, a base URL that is not `https://` (plain `http://` only for `localhost`, `127.0.0.1` and `[::1]`), a timeout that is zero, negative or not a finite number (on the client or on one call; TypeScript also caps it at 2,147,483,647 ms), and a per-call `Authorization` or `X-API-Key` header. The key is checked again whenever the auth header is built, so the client and the server agree on whether a call is keyed. The SDKs take Peel API keys only; MCP OAuth tokens are for MCP clients. |
| Errors | A failed request raises `PeelError` with `status`, `code`, `message`, `retryable`, `retry` (`same_key`, `new_key`, `fix_request` or `never`), the action outcome when known, `docs_url` (`docsUrl`), `details`, the request id from `x-request-id` and the `Retry-After` wait. Network failures, timeouts and cut-off bodies raise it with `code` `transport_error`, `timeout` or `body_read_failed`. An endpoint call (`call`, `marketplaceCall` and the generated `callApiEndpoint` and `callMarketplaceEndpoint`, or their Python names) also raises it when the call ran but its result says `status: "error"`; `batch` keeps per-item errors in its result. See [Errors](https://docs.peel.sh/reference/errors.md). |
| Timeouts | `timeoutMs` (TypeScript, rounded up to whole milliseconds) or `timeout` in seconds (Python) bounds the whole request, including a body that arrives slowly. In Python the connect and each socket read get the time left, and a timeout closes the connection. A write that timed out before its request was fully sent reports `action_outcome` `not_committed`; after that, `unknown`. Python cannot interrupt the DNS lookup, so a slow resolver can add to the time. |
| Retries | Reads (`GET`, `HEAD`) retry errors with `retryable: true`, at most twice by default, after the `Retry-After` wait. A write retries only when it sent an `Idempotency-Key` that the operation enforces (which needs an API key), with the same key, or when the error says nothing was committed. Otherwise it raises at once, and a retryable, server, network or cut-off failure reports the outcome as `unknown`. Once any attempt may have reached the server, the outcome stays `unknown`, whatever later attempts return. `retry: "new_key"` is never replayed for you. A wait over 30 seconds, such as a daily limit, raises at once. |
| Redirects | Both clients raise `invalid_path` before sending when a request path would leave the base URL's origin, such as `.other.test/resource`. Python never follows a redirect: a `3xx` raises `PeelError` with that status. TypeScript follows a read's `301`, `302`, `303`, `307` and `308` within the same origin, up to 20 hops, and raises `PeelError` `cross_origin_redirect` for one to another origin, so the key and session headers never reach it. Any other `3xx`, such as `304`, raises with its status. A write never follows a redirect: TypeScript raises `write_redirected` for a redirect or an unreadable `Location`, and the write is not sent again. |
| Idempotency | Operations that accept `Idempotency-Key` get one generated per call, and a retry reuses it. Pass your own to make a retry across processes safe. |
| Waiting | `wait`, and `build` with `wait`, keep one deadline: every request inside gets the smaller of its normal timeout and the time left, so a stalled poll times out and the next poll runs, and they never start a long poll that could outlast the deadline. Near the deadline they read the status instead and return the same shape, with `waited` and `timed_out` false. A finished build that arrives is always returned. If the deadline passes while the build is still running, they return the last answer with `timed_out` true. They raise when the server asks for a longer wait than is left. `wait` can return up to one request's network margin after the deadline. |
| Pages | `paginate` follows `next_cursor`: `peel.paginate(peel.listRuns, { query: { limit: 50 } })` in TypeScript, `peel.paginate(peel.list_runs, limit=50)` in Python. A cursor seen twice raises. |
| Batches | `batch(apiId, endpoint, inputs)` calls one endpoint for up to 100 inputs. See [Batches](https://docs.peel.sh/features/batches.md). |
| OAuth and MCP | The MCP transport and `GET /oauth/authorize` return the raw response (status, headers and body text) without raising or following redirects, because their meaning depends on the status, such as `202` for an MCP notification or the `302` from authorize. The other OAuth operations, such as the token endpoint, return parsed JSON and raise on errors. |
| Teams | An API key always acts on its own account. Operations that only accept a signed-in Peel session are not in the SDKs: team invites, joining, listing or leaving accounts, and OAuth consent approval (`POST /oauth/authorize`). |

> [!NOTE]
>
> The hosted API answers browser requests only from origins on its CORS allowlist: Peel's own public URL and the origins Peel configures. You cannot add your own origin, so a page on any other origin has to call Peel from its server. On an allowed origin, `Retry-After` and `x-request-id` are not exposed to scripts, so `retryAfterMs` and `requestId` are empty and retries fall back to a short backoff. A browser also cannot read the `Location` of a `302` (fetch returns an opaque redirect), so a redirected call raises `redirect_hidden` and the OAuth redirect endpoints belong on a server.

Every other operation is a generated method named after its `operationId`: `listApis`, `getQuota` and `createWebhook` in TypeScript, `list_apis`, `get_quota` and `create_webhook` in Python.


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