QR Hero Developer Docs

Get started

Quickstart

This guide walks through authentication, your first REST call, and an equivalent MCP tool invocation. Replace https://api.qrhero.com with your app host (production: https://app.qrhero.com).

1. Create an API token

Sign in to the QR Hero dashboard. Your organization must be on a plan that includes API access. Open /settings/api-tokens to create a personal access token.

  1. Choose a descriptive token name (for example Local dev or CI automation).
  2. Select abilities your integration needs — start with codes.view plus codes.create for basic automation, and add mcp.access if you will call MCP tools.
  3. Copy the plain-text secret immediately — it is shown only once.

See the full token abilities reference for what each ability grants. Owners can also mint tokens programmatically once an initial token with api.tokens.manage exists: 

curl -sS -X POST "https://api.qrhero.com/v1/tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI automation","abilities":["codes.view","codes.create","mcp.access"]}'

The plain-text secret is returned once in the token field — store it securely.

2. REST: verify connectivity

Paste your token into the command below and confirm you receive HTTP 200: 

curl -sS "https://api.qrhero.com/v1/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example response:

{
  "status": "ok",
  "version": "v1",
  "organization": { "ulid": "...", "name": "...", "slug": "..." },
  "plan": { "code": "PROFESSIONAL_ANNUAL", "name": "Professional" },
  "api": {
    "rate_limit_per_min": 120,
    "calls_included_month": 5000,
    "calls_used_month": 42
  },
  "token": { "name": "CI automation", "abilities": ["codes.view", "codes.create"] }
}

If you receive HTTP 403 with API access is not included in your plan, upgrade to a plan with the api_access feature. If you receive HTTP 401, check the Bearer token value.

3. REST: create a dynamic QR code

First, list domains to find a domain_ulid: 

curl -sS "https://api.qrhero.com/v1/domains" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Then create a code:

curl -sS -X POST "https://api.qrhero.com/v1/qr-codes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "launch-2026",
    "destination": "https://example.com/launch",
    "domain_ulid": "YOUR_DOMAIN_ULID"
  }'

The stored slug is <org-slug>/launch-2026. A successful response includes data.public_url for the short link.

4. REST: bulk import (confirm-then-execute)

# Stage rows — review preview before committing
curl -sS -X POST "https://api.qrhero.com/v1/qr-codes/bulk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": { "domain_ulid": "YOUR_DOMAIN_ULID" },
    "rows": [
      { "slug": "row-1", "destination": "https://example.com/1" },
      { "slug": "row-2", "destination": "https://example.com/2" }
    ]
  }'

# Confirm with the confirm_token from the staging response
curl -sS -X POST "https://api.qrhero.com/v1/qr-codes/bulk/IMPORT_ULID/confirm" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm_token":"TOKEN_FROM_STAGE_RESPONSE"}'

5. MCP: connect an AI agent

The MCP server exposes the same operations as REST tools. Your token must include the mcp.access ability (in addition to any tool-specific abilities such as codes.create).

MCP endpoint: https://mcp.qrhero.com/mcp

Transport: HTTP with Bearer token authentication (same Sanctum token as REST).

Example tool call — status_read

Equivalent to GET /v1/status. JSON-RPC 2.0 over MCP: 

curl -sS -X POST "https://mcp.qrhero.com/mcp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "status_read",
      "arguments": {}
    }
  }'

A successful response includes a result object with the same payload shape as the REST endpoint.

Example tool call — codes_create

Equivalent to POST /v1/qr-codes: 

curl -sS -X POST "https://mcp.qrhero.com/mcp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "codes_create",
      "arguments": {
        "slug": "agent-created",
        "destination": "https://example.com/from-agent",
        "domain_ulid": "YOUR_DOMAIN_ULID"
      }
    }
  }'

See the full MCP tool catalog for all 25 tools, input fields, client setup, and confirm-then-execute flow.

6. Handle rate limits

When you exceed your per-minute limit, the API returns HTTP 429 with a Retry-After header (seconds) and a documentation URL. See Rate limits for platform defaults, per-plan ceilings, and metering.