Skip to main content
POST
Make a shape
  • Say the result you want: which fields, renamed how, filtered, sorted, grouped, counted or averaged. Pomerado writes the shape’s code and checks it against every form the tool’s result can take before saving it. It answers in a few seconds and starts no job.
  • A shape only reshapes what the tool returns. A request for data the tool doesn’t return answers needs_tool_change: ask for that with POST /v1/tools/{id}/changes. One no shape can do, such as one needing the time or other pages, answers not_possible.
  • Fields the tool adds later stay out of a shape unless you asked to keep everything; the shape then lists them in new_fields.
  • Shapes are free, and only you can see and use them. You can have 50 for each tool and 500 in all.
  • Callers: an API key, an integration’s API key, an MCP OAuth token or a Dashboard session.
  • Permission: runs:create.
  • Effect: Creates or changes something.
  • Errors: not_found, sign_in_required, shape_limit_reached, shape_create_throttled, and the errors any request can get.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

a tool ID: tool_ and 32 lowercase hex digits

Example:

"tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

Body

application/json
request
string
required

The result you want, in your own words: which fields, renamed how, filtered, sorted, counted or averaged, such as "only the name and price in dollars, cheapest first"

Required string length: 1 - 2000

Response

The saved shape, or why none was saved

outcome
enum<string>
required
Available options:
saved
shape
object
required
preview
any
required

The shape's result for a made-up result of the tool

message
string
required

What happened, in words