Make one metered putty call on an agent's behalf
Runs one MCP tool on behalf of a registered agent, and charges the caller for it. This is the route the agent harness on a user's host calls. **The charge comes first.** Credits are taken before the tool runs, and a caller whose balance is short gets the 402 with nothing metered and no tool run. There is no state in which the work happened and the money did not. **`requestId` is the idempotency key, and it is the caller's job to make it stable.** A network retry of the same work must carry the same id. The first call with an id is charged; a replay of that id returns the same charge and takes no new credits, and says so with `replayed: true`. Two calls that are genuinely different work must carry different ids — reusing one id for different work is how a caller would avoid paying for it, and the server cannot tell the two apart by design. A call refused for want of credits is NOT remembered, so retrying that same id after topping up charges it then. A `402` is a statement about a balance, and a balance changes. `status` is `completed` when the tool ran, and `tool_error` when it ran and refused its own input — a tool that rejects a malformed palette is still work the caller asked for and is still billed. The caller learns the price of every tool from `GET /agents/pricing` before it calls.
Runs one MCP tool on behalf of a registered agent, and charges the caller for it. This is the route the agent harness on a user's host calls.
The charge comes first. Credits are taken before the tool runs, and a caller whose balance is short gets the 402 with nothing metered and no tool run. There is no state in which the work happened and the money did not.
requestId is the idempotency key, and it is the caller's job to make it stable. A network retry of the same work must carry the same id. The first call with an id is charged; a replay of that id returns the same charge and takes no new credits, and says so with replayed: true. Two calls that are genuinely different work must carry different ids — reusing one id for different work is how a caller would avoid paying for it, and the server cannot tell the two apart by design.
A call refused for want of credits is NOT remembered, so retrying that same id after topping up charges it then. A 402 is a statement about a balance, and a balance changes.
status is completed when the tool ran, and tool_error when it ran and refused its own input — a tool that rejects a malformed palette is still work the caller asked for and is still billed. The caller learns the price of every tool from GET /agents/pricing before it calls.
Path Parameters
The agent's id, as returned by POST /agents.
Request Body
application/json
The tool to run, its arguments, and the idempotency key to meter it under.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/agents/string/calls" \ -H "Content-Type: application/json" \ -d '{ "requestId": "stringst", "toolName": "string" }'{ "call": { "agentId": "string", "requestId": "string", "toolName": "string", "status": "completed" }, "credits": { "charged": 0, "action": "agent_call", "balance": { "allowance": 0, "purchased": 0, "total": 0 } }, "replayed": true, "result": { "isError": true, "text": "string", "structuredContent": null }}Deregister an agent DELETE
Deregisters an agent. The row stays: the usage reports still attribute the agent's past spend to its name, and a deregistered agent can never make another metered call. The delete is scoped by owner in the store query, so a foreign agent answers the same 404 as a missing one. Deleting twice answers 404 as well — the agent is already gone from every read, and a fresh timestamp would make a dead agent look recently used.
What one agent spent GET
The credits one agent spent over a window, summed from the credit ledger rows this agent caused. The sum is read from the ledger rather than from the metering journal, because the ledger is the money and the journal is only a replay cache. An agent with no spend in the window answers zeroes rather than 404, so a dashboard renders a zero row instead of an error.