API reference

List your tool requests

See the tool requests you have made with these credentials and what became of each.

GET POST /api/tools/requests MCP tool tool_requests

Returns every tool request made with your client ID, newest first, with its current status and the owner's note. When a request is shipped, shipped_url points at the new tool. Requests made through the web form are not linked to a client and do not appear here.

Browser version (runs locally): Request a Tool.

Try it
Credentials
Remember these credentials

Not saved: you will paste them again next time.

No credentials yet? Get a client ID and secret. They are sent only to this site, in an Authorization: Basic header.

POST /api/tools/requests with a JSON body

Parameters

Parameter Type Default Description

Also accepted on every endpoint: format (json | text). Parameters may come from the query string, a JSON object body, an urlencoded or multipart form, or (for input) a text/plain body.

Global parameters
Parameter Type Default Description
format json | text json json returns the documented object. text returns only the primary value as text/plain (see "Text output").

Response 200 application/json

Field Type Description
requests array of object Your requests, newest first.
requests[].request_id string Identifier of the request.
requests[].title string Title as submitted.
requests[].status "received" | "planned" | "building" | "shipped" | "declined" | "duplicate" received (not reviewed yet), planned, building, shipped (see shipped_url), declined or duplicate (see status_note).
requests[].status_note string | null The owner's note, if any.
requests[].shipped_url string | null The tool, once shipped.
requests[].created_at string When it was submitted.
requests[].updated_at string When its status last changed.

Errors

Errors are JSON: {"error": "<message>", "code": "<code>", "param": "<name>"?}.

Status Code When
400 missing_parameter A required parameter is absent.
400 unknown_parameter A parameter name is not in the table above (typos are rejected, not ignored).
400 invalid_parameter A value has the wrong type, is out of range, or is not an allowed value.
413 payload_too_large The request body exceeds 1 MiB.
405 method_not_allowed A method other than GET, POST or OPTIONS.

Behaviour

  • Idempotent: the same arguments always return the same result.
  • Requires a client ID and secret (authentication). Each call is recorded as one metadata row against your client ID; inputs and outputs are never stored or logged. Responses carry cache-control: no-store.
  • CORS: any origin may call this endpoint from a browser, using your credentials.

Examples

Responses below were produced by running each request through this code at build time. Long strings are shortened.

Check your requests

curl 'https://util.caruana.me/api/tools/requests?'

Response 200

{
  "requests": [
    {
      "request_id": "tr_EXAMPLE",
      "title": "Semantic version compare",
      "status": "planned",
      "status_note": "Good fit: deterministic, and agents get it wrong. Next up.",
      "shipped_url": null,
      "created_at": "2026-10-14T09:00:00.000Z",
      "updated_at": "2026-10-15T10:30:00.000Z"
    }
  ]
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_requests",
    "arguments": {}
  }
}