API Reference

Endpoints,
envelope, headers.

Every tool endpoint uses the same request and response shape. One mental model, one SDK to write, identical behaviour across the catalog.

Base URL

Production: https://api.toolsamurai.com

Local dev: http://localhost:3000/api

Endpoints

POST/v1/{domain}/{slug}Execute a tool. Main endpoint. All tools use POST.Core
GET/v1/{domain}/{slug}/schemaInputs and outputs schema for one tool.Discovery
GET/v1/toolsList all tools. Supports ?domain=, ?page=, ?limit=.Index
GET/v1/tools/{slug}Single tool's full metadata.Index
GET/v1/domainsAll domains with live + target tool counts.Index
GET/v1/meCaller info: plan, key prefix, month-to-date quota.Auth
GET/v1/healthLiveness check. No auth required.Ops

Request shape

All execute endpoints accept a JSON body keyed by each input's key. Headers are identical for every tool.

POST · request
POST /v1/pcb-design/pcb-trace-width
Content-Type: application/json
Authorization: Bearer sk_free_••••••••••••••••

{
  "current_a": 3.5,
  "temp_rise_c": 10,
  "copper_weight_oz": 1,
  "layer": "outer"
}

Success envelope

Always returned on a 2xx. The tool's actual output lives inside the result object. Outer fields are identical for every tool.

200 OK · success envelope
{
  "ok": true,
  "tool": "pcb-trace-width",
  "domain": "pcb-design",
  "version": "1.0.0",
  "result": { /* tool-specific */ },
  "meta": {
    "latency_ms": 12,
    "quota_remaining": 487,
    "request_id": "req_01HX..."
  }
}

Error envelope

Always returned on a non-2xx. The code is machine-readable; the field points at the offending input when relevant.

4xx / 5xx · error envelope
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "\"current_a\" must be >= 0.001.",
    "field": "current_a"
  },
  "meta": { "request_id": "req_01HX..." }
}

HTTP status codes

200OKTool executed. Always check "ok": true.
400Bad RequestInput validation failed. The `field` tells you which key.
401UnauthorizedMissing or invalid API key.
404Not FoundNo tool at this {domain}/{slug}.
422UnprocessableInput was valid but the tool can't compute (e.g. division by zero).
429Too Many RequestsRate limit hit. Retry-After header tells you when to try again.
500InternalServer fault. Rare. Use request_id when contacting support.

Response headers

Every response carries these headers. RFC 6585 / 7231 compliant.

X-Request-IDreq_01HX... — unique per call, log it.
X-Tool-VersionSemVer of the tool, matches result body.
X-RateLimit-LimitMax calls per minute for your plan.
X-RateLimit-RemainingCalls left in the current 60s window.
X-RateLimit-ResetUnix epoch seconds when the window resets.
Retry-AfterOn 429 only — seconds to wait.

Next