Skip to main content
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:
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, 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. 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.