> ## 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.

# Marketplace

> Browse public APIs, install one as your own, call its public data endpoints, and publish or unpublish yours.

The marketplace is a catalog of public APIs that Peel users published; you can browse it without an account and install any entry as a private API you own.

## Browse and search

The browse routes need no authentication.

| Route | Query parameters | Returns |
| - | - | - |
| `GET /public/marketplace` | `q` (up to 120 characters), `cursor`, `limit` (1 to 50, default 24) | `{ items, next_cursor, search_truncated }` of summaries |
| `GET /public/marketplace/endpoints` | `q` (1 to 120 characters, required), `cursor`, `limit` (1 to 50, default 24) | `{ items, next_cursor, search_truncated }` of matching endpoint contracts |
| `GET /public/marketplace/{marketplace_id}` | none | One API with its `endpoints`: schemas and a ready request for each |

```bash theme={null}
curl "https://api.peel.sh/public/marketplace?q=docs&limit=5"
```

Peel keeps each browse answer for 15 seconds. Its `Cache-Control` is `public, max-age=N, stale-while-revalidate=60`, where `N` is 15 minus the age of Peel's copy, so through a browser or a shared cache a browse answer can be up to 75 seconds old: 15 seconds fresh, then up to 60 more while it revalidates. A `404` is not cached.

A summary has `id`, `name`, `description`, `source_host`, `source_url`, `endpoint_count`, `requires_session` and `updated_at`. Pass `next_cursor` as `cursor` for the next page. The `id` is the `marketplace_id` used below. Over MCP, use `list_marketplace_apis`, `get_marketplace_api` and `search_marketplace_endpoints`.

Each endpoint in the detail has the same fields as an endpoint of your own API: `endpoint_name`, `input_schema`, `output_schema`, `credit_cost` and `examples`. An endpoint you can call directly carries one example with the request, a `curl` line, the `peel marketplace call` command and the MCP `call_marketplace_endpoint` arguments; it runs as is, without an account. Other endpoints have empty `examples`: install the API to call them.

## Call a public endpoint directly

`POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call` runs an endpoint from the canonical marketplace version. It works only for public `data` endpoints on APIs that need no session.

```bash theme={null}
MARKETPLACE_ID=kd74n2353r515czbkq7kaet9tx8jctwy  # Hacker News
curl -X POST https://api.peel.sh/v1/marketplace/$MARKETPLACE_ID/endpoints/front_page_stories:call \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The response is the standard call envelope from [Quickstart](https://docs.peel.sh/getting-started/quickstart.md#call-an-endpoint), and the call is billed to your account. A retry with the same `Idempotency-Key` is not billed again: it replays the first response, marked `Idempotent-Replayed: true`, only when that call succeeded and its response was stored (up to 375 KB). Otherwise the retry answers `409` with the recorded outcome. Any other endpoint returns `409` with `code: "marketplace_direct_call_not_allowed"`. Install the API to use it fully.

## Call without an account

The same call works with no key at all, so you can try an API before you have an account.

```bash theme={null}
curl -X POST https://api.peel.sh/v1/marketplace/$MARKETPLACE_ID/endpoints/front_page_stories:call \
  -H "Content-Type: application/json" \
  -d '{}'
```

* Each address gets 25 calls a day, and all calls without an account share 2,000 a day. Both reset at midnight UTC. Past either one the answer is `429` with `code: "try_limit_reached"` and `Retry-After` set to the seconds until midnight UTC.
* Only public data endpoints. Anything signed in, a sign-in, or an action answers `401` with `code: "sign_in_required"`.
* `Idempotency-Key` and session headers are ignored. Nothing is stored for you: no run history and no charge, so the answer has no `credits_charged` or `credits_remaining`.
* Every call runs live against the site. Peel does not cache call answers.
* Every answer carries a `notice` saying what an account adds; on a refusal it is `details.notice`.
* An unknown endpoint answers `404` with `details.available_endpoints`.

### Files and outages

* An endpoint that saves or reads a file answers `409` with `code: "not_executable"` without an account, before it runs. A file save attempted while running fails the call with `error_code: "files_need_account"`. Install the API to use files.
* When Peel cannot check the daily limits within 250 milliseconds, the answer is `503` with `code: "temporarily_unavailable"` and `Retry-After: 30`. Calls with a key are not affected.

Agents connect to the keyless MCP server at `https://api.peel.sh/mcp/keyless`. It offers `list_marketplace_apis`, `get_marketplace_api`, `search_marketplace_endpoints` and `call_marketplace_endpoint` under the same limits; a limit comes back as a tool error with `retry_after_seconds`. It takes no key: one sent there answers `400` with `code: "keyless_url_credentials"`, and keyed clients use `https://api.peel.sh/mcp`.

```bash theme={null}
claude mcp add --transport http peel-try https://api.peel.sh/mcp/keyless
```

## Install an API

`POST /v1/marketplace/{marketplace_id}/install` copies a marketplace API into your account as a private API.

```bash theme={null}
curl -X POST https://api.peel.sh/v1/marketplace/$MARKETPLACE_ID/install \
  -H "X-API-Key: $PEEL_API_KEY"
```

Expected response:

```json theme={null}
{
  "installed": true,
  "marketplace_id": "...",
  "api_id": "...",
  "build_id": "...",
  "version_id": "..."
}
```

Use the returned `api_id` with every route in the [API Reference](https://docs.peel.sh/api-reference/apis/create-an-api.md). An unknown `marketplace_id` returns `404`.

## Publish your API

`POST /v1/apis/{api_id}/marketplace/publish` publishes the current version of an API you own, or contributes it back to an existing canonical API.

```bash theme={null}
curl -X POST https://api.peel.sh/v1/apis/$API_ID/marketplace/publish \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

To contribute to an API that already exists in the marketplace, send `expected_marketplace_version_id` with the canonical version you based your work on. It is a compare-and-swap value: the contribution fails if the canonical version has moved. The response includes `published`, `already_published`, `publication_kind` (`first_publish` or `contribution`), `marketplace_id`, `api_id`, `version_id`, `source_version_id` and `visibility` (`global`). A first publish returns `201` and a repeat returns `200`. Other users cannot see your APIs unless you publish one.

## Unpublish your API

`POST /v1/apis/{api_id}/marketplace/unpublish` takes your API's listing off the marketplace. The CLI command is `peel marketplace unpublish <api-id>` and the MCP tool is `unpublish_api_from_marketplace`.

```bash theme={null}
curl -X POST https://api.peel.sh/v1/apis/$API_ID/marketplace/unpublish \
  -H "X-API-Key: $PEEL_API_KEY"
```

The answer is `200` with `unpublished`, `already_unpublished`, `marketplace_id`, `api_id` and `version_id`. Repeating the call, or calling it for an API you never published, answers `200` with `already_unpublished: true`.

After you unpublish:

* The listing leaves marketplace list, search and detail. Those reads are cached for up to 15 seconds, and a cache in front of Peel may serve the old answer for 60 seconds more while it refreshes.
* Calls to the `marketplace_id`, with or without a key, answer `404` `marketplace_api_removed` and charge nothing. This includes saved MCP setups and scripts that call it.
* A call that was already running when you unpublished may still finish and be charged; nothing new starts.
* Your API and its own routes keep working. Private copies other users installed keep working too, because each is the installer's own API.
* The listing page and the sitemap on peel.sh are built when the website is deployed, so the page stays in the static files until the next deploy. A visitor's browser loads the listing again when the page opens and shows "not found".

Run publish again to list the API under the same `marketplace_id`. After a rebuild you do not need `expected_marketplace_version_id` for this; sending the listing's current version works too. Only the API that unpublished the listing can list it again. A listing Peel removed, for example after a site owner's request, cannot be published again and answers `409` `marketplace_listing_removed`. When a publisher deletes its API, its listing goes off the marketplace until another contributor publishes a newer version to it.

Only the API that last published the listing can unpublish it. An installed copy, or an API whose contribution someone else replaced, gets `409` `marketplace_not_publisher`. On a team, anyone whose role can publish (admin or member) can also unpublish.

## Installed copies

An installed API is your own copy of the marketplace version at the time you installed it. It does not change when the marketplace version changes, and installing again returns the same copy. Revise, rebuild, repair and roll it back like any API you built; see [API updates](https://docs.peel.sh/features/api-updates.md).

Calls through `POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call` always use the current marketplace version.

## Errors and what to do

| Response | Cause | Do this |
| - | - | - |
| `404` `Marketplace API not found` | Unknown `marketplace_id`. | Search again. |
| `404` `marketplace_api_removed` | The listing was taken off the marketplace, by its publisher or by Peel. | Search for another listing, or use a copy you installed. |
| `409` `marketplace_direct_call_not_allowed` | The endpoint is not a public data endpoint. | Install the API first. |
| `401` `sign_in_required` | A call without an account to an endpoint that needs one. | Get an account and install the API. |
| `429` `try_limit_reached` | Calls without an account are used up for this address, or for everyone, until midnight UTC. | Wait for `Retry-After`, or use a key. |
| `409` `not_executable` | A call without an account to an endpoint that uses files. | Get an account and install the API. |
| `503` `temporarily_unavailable` | Peel could not check the limits for calls without an account. | Wait for `Retry-After`, or use a key. |
| `400` `keyless_url_credentials` | A key was sent to `/mcp/keyless`. | Connect to `/mcp` with the key. |
| `409` on publish | The version cannot be published, or the canonical version moved. | Read `code` and `error` in the body. For a moved canonical version, retry with the new `expected_marketplace_version_id`. |
| `400` | Invalid query, path or body. | Fix the request using the tables above. |

## Related pages

* [API updates](https://docs.peel.sh/features/api-updates.md)
* [MCP server](https://docs.peel.sh/features/mcp-server.md)
* [Errors](https://docs.peel.sh/reference/errors.md)


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