---
title: "Run one tool: the body is its input (schema on GET /api/tools) plus optional budgetUsd (default 2, max 10). Answers {tool, output, media[{key, url}], chargedUsd}."
method: POST
path: "/api/tools/{name}"
---

# Run one tool: the body is its input (schema on GET /api/tools) plus optional budgetUsd (default 2, max 10). Answers {tool, output, media\[{key, url}\], chargedUsd}.

`POST /api/tools/{name}`

## Request

- Base URL: `https://shapelessai.com`
- URL: `https://shapelessai.com/api/tools/{name}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shapelessai.com/api/auth/mcp/authorize`, token URL `https://shapelessai.com/api/auth/mcp/token`, scopes: `write`)

## Path parameters

- `name` string, required

## Request body

- object: The named tool's input, as GET /api/tools declares it, plus the budget.
  - `budgetUsd` number: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

## Response `200`

OK

- ToolResult
  - `tool` string, required
  - `output` unknown, required
  - `media` object[], required: Every media key the output names, with the URL that streams it (read scope). Put a key on a post's mediaKeys.
    - `key` string
    - `url` string, uri
  - `chargedUsd` number, required

## Other responses

- `400`: The input does not match the tool's schema; the message names the field.
- `401`: No credential, or not valid.
- `402`: Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
- `403`: The key is missing the "write" scope.
- `404`: No such tool on this deployment.
- `422`: The tool refused this input; nothing was charged.
- `429`: Over the key's rate limit (600 requests an hour).
- `502`: The tool failed; nothing was charged.

---

[API](https://skmtc.dev/shapelessai/apis/shapeless-api.md) · [All operations](https://skmtc.dev/shapelessai/apis/shapeless-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shapelessai/apis/shapeless-api/revisions/fae8f701d466?raw)