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

# Shapes

> Get only the rows and fields you need from a call: filter, sort, group, count and rename, with no model and no code.

A shape reshapes a read endpoint's result for one call: keep some rows, sort them, take the first few, rename fields, or group them and count, sum or average. Peel checks the shape against the endpoint's output schema before the call runs, so a shape that names a field the endpoint never returns is refused at once and costs nothing.

Shapes are plain JSON. No model writes them and no code runs, so a shaped call is as fast as a plain one and costs the same.

## Shape a call

Send the shape as JSON in the `Peel-Shape` header. This one keeps Hacker News stories with at least 100 points, highest first, and renames `title`; it works without an account:

```bash theme={null}
curl https://api.peel.sh/v1/marketplace/kd74n2353r515czbkq7kaet9tx8jctwy/endpoints/front_page_stories:call \
  -H 'Peel-Shape: {"where":[{"field":"points","op":"gte","value":100}],"sort":[{"field":"points","order":"desc"}],"limit":3,"fields":{"headline":"title","points":"points"}}' \
  -d '{}'
```

```json theme={null}
{
  "status": "success",
  "data": {
    "stories": [
      { "headline": "Carnegie Mellon is putting computer science courses on YouTube for free", "points": 1022 },
      { "headline": "Technical issue at JPMorgan Chase triggers online banking delays for US banks", "points": 740 },
      { "headline": "BugMeNot has closed", "points": 416 }
    ]
  },
  "shape": { "status": "applied", "left_out": ["link", "author"] }
}
```

The shape changes only the list of rows. Everything beside it, such as `next_cursor`, comes back unchanged, so you page as before. On MCP, pass `shape` beside `params` on `call_endpoint` or `call_marketplace_endpoint`. In a [batch](https://docs.peel.sh/features/batches.md), put `shape` in the body and it applies to every item.

## What a shape can do

The steps run in this order. Each is optional.

| Field | What it does |
| - | - |
| `rows` | The path to the list in the result. Defaults to the endpoint's paging list, or its only list, or the result itself when the result is a list. |
| `where` | Keep rows that match every condition: `{ "field", "op", "value" }`. `op` is `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` or `exists`. |
| `group_by` | Up to five fields. Each group becomes one row with those fields and the aggregates. |
| `aggregate` | Named totals: `{ "count": { "op": "count" }, "mean": { "op": "avg", "field": "score" } }`. `op` is `count`, `sum`, `avg`, `min` or `max`. Without `group_by`, the whole list becomes one row of totals. |
| `sort` | Up to five `{ "field", "order" }` keys, `asc` by default. Rows without the field sort last. |
| `limit` | Keep the first 1 to 10,000 rows. |
| `fields` | A list of fields to keep, or a map from new names to fields. Nested fields use dots, such as `author.name`. Not combined with `group_by` or `aggregate`. |

Comparisons work on numbers and on text; dates in ISO 8601 compare correctly as text. `contains` matches text without regard to case, or an entry of a list.

## When a shape does not apply

* A shape with a mistake, such as an unknown field, `sum` on a text field, or sorting a grouped result by a field it does not have, is refused before the run with 400 `shape_invalid`. The message names the mistake and lists the fields the rows have. Nothing is charged.
* If a result has no list where the shape expects one, for example when the site answered with an error, the call returns the endpoint's own result and `shape` is `{ "status": "skipped", "reason": "…" }`. A shape never fails a call.
* `left_out` lists the row fields your `fields` leave out, so you can see what else the endpoint returns.

Shapes apply to data endpoints. A failed call is returned as the endpoint gives it.


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