Docs

When to use MiniWebtool API

Use MiniWebtool API when your product needs calculators, hashes, counters, date math, finance formulas, converters, or repeatable utility results. You get stable JSON, fixed credit cost, lower latency, and no custom helper code to maintain for each tool.

Quickstart

Get a key from the dashboard, 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.

Authentication

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.

Errors (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.

Rate 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.

Credits

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.
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 the customer enables it.

Versioning

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.

MCP / 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.

Privacy

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]

Support

Email [email protected] with the failing X-Request-Id.
Feature requests: [email protected]

How the API works

Every endpoint, searchable