API documentation

Call Tool Swim tools over HTTP

Discover the APIs available to your key, then open one family at a time for its request, response, limits, credit contract, and operation examples.

Authentication and request safety

Keep the secret on your server. Tool Swim validates the key and its per-tool permission before it reads or parses request content.

Bearer key

Send Authorization: Bearer …. Tool Swim issues live keys only. A key needs the tools:execute scope and explicit access to the requested tool.

Idempotency key

Every POST needs an Idempotency-Key containing 8–128 safe ASCII characters. Reuse it only when retrying the same logical request.

Bounded request

Use the media type and limits documented for the selected tool. Unsupported fields are rejected so execution stays predictable.

Discover tools and permissions

Call the authenticated catalog first. It returns all 187 direct browser-tool URLs with owning family, API readiness, permission, operation, credit cost, and documentation link. Family permissions cover their child routes.

List tools

curl https://www.toolswim.com/api/v1/tools \
  --header "Authorization: Bearer $TOOL_SWIM_API_KEY"

Catalog response (6 of 187 entries)

{
  "object": "list",
  "tools": [
    {
      "slug": "qr-code-generator/url",
      "familySlug": "qr-code-generator",
      "variantSlug": "url",
      "name": "URL QR Code Generator",
      "browserUrl": "/tools/qr-code-generator/url",
      "operation": "qr-code-generate",
      "api": {
        "available": true,
        "canExecute": true,
        "permission": "qr-code-generator",
        "method": "POST",
        "path": "/api/v1/tools/qr-code-generator/execute",
        "documentationPath": "/api/docs#qr-code-generator",
        "creditsPerSuccess": 1,
        "operations": [
          "qr-code-generate"
        ],
        "operation": "qr-code-generate"
      }
    },
    {
      "slug": "image-converter/svg-to-png",
      "familySlug": "image-converter",
      "variantSlug": "svg-to-png",
      "name": "SVG to PNG Converter",
      "browserUrl": "/tools/image-converter/svg-to-png",
      "operation": null,
      "api": {
        "available": false,
        "canExecute": false,
        "permission": null,
        "operation": null
      }
    },
    {
      "slug": "url-tools/parse-url",
      "familySlug": "url-tools",
      "variantSlug": "parse-url",
      "name": "URL Parser",
      "browserUrl": "/tools/url-tools/parse-url",
      "operation": "parse-url",
      "api": {
        "available": true,
        "canExecute": true,
        "permission": "url-tools",
        "method": "POST",
        "path": "/api/v1/tools/url-tools/execute",
        "documentationPath": "/api/docs#url-tools",
        "creditsPerSuccess": 1,
        "operations": [
          "parse-url",
          "build-url",
          "resolve-relative-url",
          "normalize-url",
          "compare-urls",
          "parse-query-string",
          "build-query-string",
          "encode-url-component",
          "decode-url-component",
          "convert-international-domain-name"
        ],
        "operation": "parse-url"
      }
    },
    {
      "slug": "base-encoding-tools/base64-encoder",
      "familySlug": "base-encoding-tools",
      "variantSlug": "base64-encoder",
      "name": "Base64 Encoder",
      "browserUrl": "/tools/base-encoding-tools/base64-encoder",
      "operation": "base64-encoder",
      "api": {
        "available": true,
        "canExecute": true,
        "permission": "base-encoding-tools",
        "method": "POST",
        "path": "/api/v1/tools/base-encoding-tools/execute",
        "documentationPath": "/api/docs#base-encoding-tools",
        "creditsPerSuccess": 1,
        "operations": [
          "base16-encoder",
          "base16-decoder",
          "base32-encoder",
          "base32-decoder",
          "base58-encoder",
          "base58-decoder",
          "base64-encoder",
          "base64-decoder",
          "base85-encoder",
          "base85-decoder"
        ],
        "operation": "base64-encoder"
      }
    },
    {
      "slug": "unicode-tools/count-grapheme-clusters",
      "familySlug": "unicode-tools",
      "variantSlug": "count-grapheme-clusters",
      "name": "Grapheme Cluster Counter",
      "browserUrl": "/tools/unicode-tools/count-grapheme-clusters",
      "operation": "count-grapheme-clusters",
      "api": {
        "available": true,
        "canExecute": true,
        "permission": "unicode-tools",
        "method": "POST",
        "path": "/api/v1/tools/unicode-tools/execute",
        "documentationPath": "/api/docs#unicode-tools",
        "creditsPerSuccess": 1,
        "operations": [
          "inspect-unicode-text",
          "characters-to-code-points",
          "code-points-to-characters",
          "normalize-unicode-text",
          "check-unicode-normalization",
          "escape-unicode-text",
          "unescape-unicode-text",
          "count-grapheme-clusters",
          "reveal-invisible-characters",
          "compare-unicode-confusables"
        ],
        "operation": "count-grapheme-clusters"
      }
    },
    {
      "slug": "regex-tools/regex-capture-groups",
      "familySlug": "regex-tools",
      "variantSlug": "regex-capture-groups",
      "name": "Regex Capture Groups",
      "browserUrl": "/tools/regex-tools/regex-capture-groups",
      "operation": "regex-capture-groups",
      "api": {
        "available": true,
        "canExecute": true,
        "permission": "regex-tools",
        "method": "POST",
        "path": "/api/v1/tools/regex-tools/execute",
        "documentationPath": "/api/docs#regex-tools",
        "creditsPerSuccess": 1,
        "operations": [
          "regex-tester",
          "regex-match-extractor",
          "regex-replacer",
          "regex-splitter",
          "regex-line-filter",
          "regex-capture-groups",
          "regex-validator",
          "regex-escape-literal",
          "regex-explainer",
          "regex-flags-comparison"
        ],
        "operation": "regex-capture-groups"
      }
    }
  ]
}

Family reference

Search the catalog, select one family, then choose one operation example. Only the active contract is rendered.

QR Code Generator API

Generate a QR code from one of the ten supported, strictly validated payload types.

POST /api/v1/tools/qr-code-generator/execute · 1 credit per success

Choose one payload type and send only its documented data fields. Output defaults are SVG, 512 pixels, margin 4, and M error correction.

URL QR request

curl https://www.toolswim.com/api/v1/tools/qr-code-generator/execute \
  --request POST \
  --header "Authorization: Bearer $TOOL_SWIM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: qr-code-generator-request-1042" \
  --data '{
  "type": "url",
  "data": {
    "url": "https://example.com"
  },
  "options": {
    "format": "svg",
    "size": 512,
    "margin": 4,
    "errorCorrection": "M",
    "foreground": "#09090b",
    "background": "#ffffff"
  }
}'

The response includes the authoritative request id, replay state, requested output, and estimated and settled credits.

Supported payloads: URL, Wi-Fi, vCard, email, SMS, WhatsApp, phone, location, event, and Google review.
The request body limit is 16 KiB and compressed bodies are rejected.

Open the browser tool

Successful QR response

{
  "requestId": "request_…",
  "replayed": false,
  "output": {
    "svg": "<svg …>…</svg>"
  },
  "credits": {
    "estimated": 1,
    "settled": 1
  }
}

Errors and recovery

Error bodies contain a stable code, a short message, and a request id. They never echo your API secret or submitted tool content.

400: Invalid JSON, fields, or idempotency key.
401: Missing, invalid, expired, or revoked API key.
403: The key scope or tool access is not allowed.
409: The idempotency key conflicts or the first request is processing.
413 / 415: The body is too large, compressed, or has the wrong media type.
429: The rate limit or available credit balance was reached.
500 / 503: The operation or execution service did not complete.

Request data and retention

Calling an API intentionally transmits request content to Tool Swim. Execution logs retain identifiers, status, timing, bounded usage facts, and credit metadata—not API secrets or submitted content. Each tool’s documentation records any stricter boundary. Retention follows your plan.

Read the privacy policy