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

# Make a shape

> Make a shape of a tool from words: your own form for its result, which a run returns when you pass the shape's id as shape.

> [accordion] Details
>
> * 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`](https://docs.pomerado.ai/errors#not_found), [`sign_in_required`](https://docs.pomerado.ai/errors#sign_in_required), [`shape_limit_reached`](https://docs.pomerado.ai/errors#shape_limit_reached), [`shape_create_throttled`](https://docs.pomerado.ai/errors#shape_create_throttled), and the [errors any request can get](https://docs.pomerado.ai/errors.md).


## OpenAPI

````yaml /api-reference/openapi.json post /v1/tools/{id}/shapes
openapi: 3.1.0
info:
  title: Pomerado API
  version: '1'
  description: >-
    Run and build website tools, follow their jobs, and manage logins, API keys
    and webhooks. Authenticate with a Pomerado API key (pom_…), an MCP OAuth
    token or a Dashboard session as a Bearer token.
servers:
  - url: https://api.pomerado.ai
security: []
tags:
  - name: account
    x-group: Account
  - name: api_keys
    x-group: API keys
  - name: connected_apps
    x-group: Connected apps
  - name: usage
    x-group: Usage
  - name: quota
    x-group: Quota
  - name: spend_controls
    x-group: Spend controls
  - name: usage_alerts
    x-group: Usage alerts
  - name: usage_summary
    x-group: Usage summary
  - name: billing
    x-group: Billing
  - name: integrations
    x-group: Integrations
  - name: connect
    x-group: Connect
  - name: code
    x-group: Code
  - name: logins
    x-group: Saved logins
  - name: two_factor
    x-group: 2FA
  - name: login_access
    x-group: Login access
  - name: tools
    x-group: Tools
  - name: shapes
    x-group: Shapes
  - name: webhooks
    x-group: Webhooks
  - name: payer_profiles
    x-group: Payer profiles
  - name: payer_addresses
    x-group: Payer addresses
  - name: payment_methods
    x-group: Payment methods
  - name: runs
    x-group: Runs
  - name: builds
    x-group: Builds
  - name: jobs
    x-group: Jobs
  - name: suggestions
    x-group: Suggestions
  - name: audit
    x-group: Audit
  - name: files
    x-group: Files
  - name: team
    x-group: Team
  - name: sso
    x-group: Single sign-on
  - name: issue_reports
    x-group: Problem reports
paths:
  /v1/tools/{id}/shapes:
    post:
      tags:
        - shapes
      summary: Make a shape
      description: >-
        Make a shape of a tool from words: your own form for its result, which a
        run returns when you pass the shape's id as shape.
      operationId: shapes.create
      parameters:
        - name: id
          in: path
          required: true
          description: 'a tool ID: tool_ and 32 lowercase hex digits'
          schema:
            type: string
            examples:
              - tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - request
              properties:
                request:
                  type: string
                  description: >-
                    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"
                  minLength: 1
                  maxLength: 2000
              additionalProperties: false
      responses:
        '200':
          description: The saved shape, or why none was saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeAnswer'
        '400':
          description: invalid_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: sign_in_required, unauthorized, reauthentication_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: shape_limit_reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: moved_to_team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: request_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: shape_create_throttled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: temporarily_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearer: []
components:
  schemas:
    ShapeAnswer:
      anyOf:
        - type: object
          required:
            - outcome
            - shape
            - preview
            - message
          properties:
            outcome:
              type: string
              enum:
                - saved
            shape:
              $ref: '#/components/schemas/Shape'
            preview:
              $id: /schemas/unknown
              description: The shape's result for a made-up result of the tool
            message:
              type: string
              description: What happened, in words
          additionalProperties: false
        - type: object
          required:
            - outcome
            - missing
            - message
          properties:
            outcome:
              type: string
              enum:
                - needs_tool_change
            missing:
              type: array
              items:
                type: string
              description: The data the request needs that the tool doesn't return
            message:
              type: string
              description: What happened, in words
          additionalProperties: false
        - type: object
          required:
            - outcome
            - message
          properties:
            outcome:
              type: string
              enum:
                - not_possible
            message:
              type: string
              description: What happened, in words
          additionalProperties: false
        - type: object
          required:
            - outcome
            - findings
            - message
          properties:
            outcome:
              type: string
              enum:
                - not_written
            findings:
              type: array
              items:
                type: string
              description: Why Pomerado's code didn't pass its checks
            message:
              type: string
              description: What happened, in words
          additionalProperties: false
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - retryable
            - docs_url
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            docs_url:
              type: string
            details:
              type: object
              required: []
              properties: {}
              additionalProperties:
                $id: /schemas/unknown
          additionalProperties: false
      additionalProperties: false
    Shape:
      type: object
      required:
        - id
        - tool_id
        - name
        - request
        - version
        - code
        - output_schema
        - passes_new_fields
        - new_fields
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: shp_ and 32 lowercase hex digits
        tool_id:
          type: string
        name:
          type: string
        request:
          type: string
          description: The words the current version was made from
        version:
          type: number
        code:
          type: string
          description: >-
            The function Pomerado wrote, read-only: a small JavaScript arrow
            function of the result
        output_schema:
          type: object
          required: []
          properties: {}
          additionalProperties:
            $id: /schemas/unknown
          description: The form the shape's results take, as JSON Schema
        passes_new_fields:
          type: boolean
          description: >-
            Whether fields the tool adds later come through the shape too,
            except one the shape replaces with its own field of the same name,
            which new_fields lists
        new_fields:
          type: array
          items:
            type: string
          description: Fields the tool returns now that the shape leaves out
        notice:
          type: string
          description: 'Present when new_fields isn''t empty: says so, and how to add them'
        created_at:
          type: string
        updated_at:
          type: string
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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