API documentation

Generate QR codes over HTTP

The API accepts bounded JSON, returns SVG or PNG output, and records content-free execution metadata for recovery and billing.

Authentication and request safety

Keep the secret on your server. Tool Swim validates the key before it reads or parses request content.

Bearer key

Send Authorization: Bearer …. Test keys work in development and preview; live keys work in production. A key needs the tools:execute scope and QR tool access.

Idempotency key

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

Bounded JSON

Use uncompressed application/json. The body limit is 16 KiB. Unsupported fields are rejected so request behavior stays predictable.

Request

Choose one type and provide only its documented data fields. Output options default to 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-order-1042" \
  --data '{
    "type": "url",
    "data": { "url": "https://example.com" },
    "options": {
      "format": "svg",
      "size": 512,
      "margin": 4,
      "errorCorrection": "M",
      "foreground": "#09090b",
      "background": "#ffffff"
    }
  }'

Supported payload types

Use url, wifi, vcard, email, sms, whatsapp, phone, location, event, or google-review. The corresponding browser-tool page explains the meaning and validation of each payload.

Review QR payload types

Response and limits

A 200 response includes the authoritative request id, replay status, requested output, and estimated and settled credits.

Read RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset on responses. A 429 may also include Retry-After.

Successful 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 QR payload.

400: Invalid JSON, fields, or idempotency key.
401: Missing, invalid, expired, or revoked API key.
403: The key environment, 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 not JSON.
429: The rate limit or available credit balance was reached.
500 / 503: Generation or the execution service did not complete.

Request data and retention

Calling the API intentionally transmits request content to Tool Swim. Execution logs retain identifiers, status, timing, byte counts, and credit metadata—not the QR payload or API secret. Retention follows your plan.

Read the privacy policy