Docs

01When to use MiniWebtool API

Use it when your product needs calculators, hashes, counters, date math, finance formulas, converters, or other repeatable utility results. You get stable JSON, a fixed credit cost per call, and no helper code to write, test, and maintain for each tool. If the utility is core IP for your business, build it yourself; if it's plumbing, call ours.

02Quickstart

Get a key from the dashboard (free tier, no card), then:

$ curl https://api.miniwebtool.com/v1/tools/percentage-calculator/run \
    -H "Authorization: Bearer $MWT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"mode":"percent_of","a":15,"b":200}'

{"request_id":"01KPW…","tool":"percentage-calculator","credits_used":1,"result":{"mode":"percent_of","a":15,"b":200,"result":30}}

Every tool lives under /v1/tools/<slug>/run. Slugs are lowercase-hyphenated and never change within a major version.

03Authentication

Pass your key as a bearer token. X-API-Key works too if your HTTP client can't set Authorization.

Authorization: Bearer mwt_live_<20-hex>_<40-hex>
# or
X-API-Key: mwt_live_...

• Keys are scoped to a Project under an Organization. Revoke from the dashboard at any time — invalidation is instant.
• We store only sha512(key) and a lookup prefix. A lost key cannot be recovered — rotate instead.
• env=test keys skip billing but still count against rate limits — use for staging.

04Errors (RFC 7807)

Every non-2xx response is application/problem+json:

{
  "type":   "https://api.miniwebtool.com/errors/insufficient_credits",
  "title":  "Insufficient credits",
  "status": 402,
  "detail": "Plan 'starter' has 0 credits remaining this period.",
  "instance":   "/v1/tools/word-counter/run",
  "request_id": "01KPW…",
  "code":   "insufficient_credits"
}

Branch on code, not title. Titles may change for copy reasons; codes are a stable contract. Known codes: invalid_request, invalid_api_key, insufficient_credits, rate_limited, tool_not_allowed, payload_too_large, internal_error.

05Rate limits & headers

Every response — 2xx, 4xx, 5xx — carries these headers:

X-RateLimit-Limit:           10        # plan per-sec cap
X-MWT-Credits-Used:          2         # cost of this call
X-MWT-Credits-Remaining:     49998     # after this call, -1 if unlimited
X-Request-Id:                01KPW…    # opaque ULID, include in support tickets
Retry-After:                 1         # only on 429
X-RateLimit-Reset:           1780…     # only on 429, unix seconds

Rate limiting is a sliding 1-second window per organization. Monthly credits reset on the 1st UTC.

06Credits

• Every tool has a fixed credit_weight. Text/hash/math tools usually cost 1 credit, simple finance costs 2, and table-heavy finance costs more.
• Weights are declared in the OpenAPI spec under x-mwt-credit-weight — your build can budget before you ever ship.
• Validation failures (4xx) and tool 5xx don't charge. Credits are reserved on entry and refunded on failure automatically.
• Free and Starter are hard-capped. Pro, Business, and Scale are hard-capped by default; optional overage is metered per 1K credits only after you enable it. No silent overage bills.

07Versioning

Every response carries tool_version. A version bump means either a bug fix (backward-compatible) or a breaking output-shape change — we never change a version in place. The /v1/ path prefix guarantees the request envelope is stable. New major versions (/v2/) ship alongside v1 for 12+ months before v1 deprecation.

08MCP / agent usage

Every tool in the registry is exposed at /v1/mcp as a Model Context Protocol server (JSON-RPC 2.0 over HTTP, spec version 2025-06-18). Claude, Cursor, and any MCP-capable agent can discover and call tools with your bearer token in one round trip — no SDK, no client codegen, no separate function definitions.

Endpoint

POST https://api.miniwebtool.com/v1/mcp
Authorization: Bearer mwt_live_...
Content-Type:  application/json

Supported methods

• initialize — public handshake; returns server info + protocol version.
• tools/list — public; returns every tool with name, title, description, and a JSON Schema inputSchema.
• tools/call — authenticated; same quota + credit billing path as REST. Response carries both content[] (for the LLM) and structuredContent (for code).
• ping, notifications/* — handled per spec.

Claude Desktop config

// ~/.config/Claude/claude_desktop_config.json  (Linux)
// %APPDATA%\Claude\claude_desktop_config.json  (Windows)
// ~/Library/Application Support/Claude/claude_desktop_config.json  (macOS)
{
  "mcpServers": {
    "miniwebtool": {
      "url": "https://api.miniwebtool.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer mwt_live_..."
      }
    }
  }
}

Try it by hand

# list tools (no key needed)
$ curl -s https://api.miniwebtool.com/v1/mcp \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | jq '.result.tools[].name'

# call one (needs key)
$ curl -s https://api.miniwebtool.com/v1/mcp \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $MWT_KEY" \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
         "params":{"name":"percentage-calculator",
                   "arguments":{"mode":"percent_of","a":15,"b":200}}}' \
  | jq .result.structuredContent

Deterministic tools are a particularly good fit for agents: let the agent plan, then call hosted tools for calculations, conversions, formatting, and hashing. Every MCP tools/call also shows up in the REST UsageEvent log — same dashboard, same billing.

09Privacy

• Pure-math tools (interest, hash, percentage) log only sha256(body), never raw input.
• PII-bearing tools (text analysis, parsing) run in no_body_logs mode — we record only the byte count.
• Request-id is always logged for debugging — include it when you file a ticket.
• Signed DPA available for Business and Scale plans. [email protected]

10Support

• Email [email protected] with the failing X-Request-Id — it links directly to our logs.
• Missing a tool you need? Request it — the catalog grows from customer asks first.