Let your agents make the codes.

Full API, CLI & agent reference

Everything the dashboard does, scriptable. The same quotas, safety checks and daily cap apply.

Authentication

Create a key in Settings → API keys (format hopp_live_…, shown once). Send it as a Bearer token on every request - the key carries your account, plan and quotas.

# base URL
https://hopp.qr-redirects.be

# every request
Authorization: Bearer hopp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# the CLI / MCP / skill read these env vars
export HOPP_API_KEY=hopp_live_•••
export HOPP_API=https://hopp.qr-redirects.be   # optional, defaults to prod

No key (or a bad one) returns 401 invalid_api_key. Keys never expire until you revoke them in Settings.

REST API

JSON over HTTPS. All /v1 endpoints require the Bearer key and act on your codes only.

curl -s -X POST https://hopp.qr-redirects.be/v1/codes \
  -H "Authorization: Bearer $HOPP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/launch","name":"Launch poster"}'

// 201 Created
{ "id":…, "slug":"NHDGYUJKK", "short_url":…, "destination":…, "qr_png":…, "qr_svg":… }

curl -s https://hopp.qr-redirects.be/v1/codes -H "Authorization: Bearer $HOPP_API_KEY"

// 200 OK
{ "data": [ { "slug", "title", "destination_url", "status", "webhook_url", "short_url", "created_at" } ] }

curl -s -X PATCH https://hopp.qr-redirects.be/v1/codes/NHDGYUJKK \
  -H "Authorization: Bearer $HOPP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/v2"}'

// 200 OK
{ "slug", "destination", "short_url", "webhook_url" }
// when a webhook is set, "webhook_secret" is returned ONCE - store it to verify signatures

curl -s https://hopp.qr-redirects.be/v1/codes/NHDGYUJKK/stats -H "Authorization: Bearer $HOPP_API_KEY"
// 200 OK  { "slug": "NHDGYUJKK", "scans": 1421 }

Prepaid credits & automated print orders

Top up a prepaid balance once, then place sticker print orders straight from the API - no per-order checkout. Each order is priced (≥50% markup + destination VAT), debited from credits, and sent to our print partner. Top-ups are a VAT-free advance payment; every order gets its own VAT invoice. Two order shapes: a sheet of identical codes, or a series of unique codes (the /series feature) printed across sheets.

curl -s https://hopp.qr-redirects.be/v1/credits -H "Authorization: Bearer $HOPP_API_KEY"
// 200 OK  { "balance_cents": 4250, "currency": "EUR", "recent": [ { "kind", "amount_cents", "balance_after_cents", "created_at" } ] }

curl -s -X POST https://hopp.qr-redirects.be/v1/credits/topup \
  -H "Authorization: Bearer $HOPP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"amount_cents":5000}'
// 200 OK  { "checkout_url": "https://checkout.stripe.com/…", "amount_cents": 5000 }

curl -s -X POST https://hopp.qr-redirects.be/v1/credits/autorecharge \
  -H "Authorization: Bearer $HOPP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"enabled":true,"threshold_cents":2000,"amount_cents":5000}'
// 200 OK  { "enabled": true, "threshold_cents": 2000, "amount_cents": 5000, "has_card": true }
// 400  { "error": "no_card" }   // save a card on the billing page first

curl -s https://hopp.qr-redirects.be/v1/products -H "Authorization: Bearer $HOPP_API_KEY"
// 200 OK  { "data": [ { "id", "name", "copies_per_sheet", "base_cost_cents", "currency" } ] }

curl -s -X POST https://hopp.qr-redirects.be/v1/orders/quote \
  -H "Authorization: Bearer $HOPP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"type":"sheet","content":{"kind":"url","url":"https://ex.com"},
       "design":{"primary":"#0C2F2B","shape":"square"},"size":{"width_mm":50,"height_mm":50},
       "copies":2,"recipient":{"name":"Jane","line1":"1 Main St","city":"Gent","postal":"9000","country":"BE"}}'
// 200 OK  { "total_cents", "net_cents", "vat_cents", "shipping_cents", "sheets", "per_sheet", "credit_balance_cents", "sufficient" }

curl -s -X POST https://hopp.qr-redirects.be/v1/orders \
  -H "Authorization: Bearer $HOPP_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' \
  -d '{"type":"series","items":["A-1","A-2","A-3"],"prefix":"https://ex.com/p",
       "design":{"primary":"#0C2F2B","shape":"square"},"size":{"width_mm":30,"height_mm":30},
       "recipient":{"name":"Jane","line1":"1 Main St","city":"Gent","postal":"9000","country":"BE"}}'
// 201 Created  { "order_id", "status", "charged_cents", "sheets", "credit_balance_cents", "invoice_url" }
// 402  { "error": "insufficient_credits", "balance_cents", "required_cents", "topup_url" }

curl -s https://hopp.qr-redirects.be/v1/orders/po_XXXXXXX -H "Authorization: Bearer $HOPP_API_KEY"
// 200 OK  { "order_id", "status", "type", "sheets", "charged_cents", "tracking", "invoice_url" }

// 200 OK  { "ok": true, "integrations": { "mailgun":true, "stripe":true } }

Scan webhooks PRO

Set webhook_url on a code (at create or via PATCH); Hopp POSTs a signed JSON payload to it on every scan. Use it to notify, log, or kick off automation. The signing webhook_secret is returned once when you set the URL.

# delivery from Hopp -> your endpoint
POST https://your-app.com/hooks/hopp
X-Hopp-Signature: sha256=<hex HMAC-SHA256 of the raw body>
{ "event":"scan", "slug", "destination", "scanned_at", "referrer", "user_agent" }

// verify before acting (Node)
import crypto from 'node:crypto';
const mac = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sigHeader), Buffer.from(mac))) return reject;

CLI @hopp/cli

A tiny Node wrapper over the REST API. Human output by default; add --json for machine output. Reads HOPP_API_KEY (required) and HOPP_API (optional).

# run once with npx, or install globally
npx @hopp/cli create --url https://example.com
npm i -g @hopp/cli   # then just: hopp …

MCP server

A stdio Model Context Protocol server exposing seven tools - create_code, point_code, list_codes, get_stats, get_credits, quote_order, place_order - to any MCP-capable agent. So an agent can buy credits-funded sticker prints on its own.

# run it
HOPP_API_KEY=hopp_live_••• node cli/mcp.mjs

# wire it into an agent (e.g. Claude Desktop config)
{ "mcpServers": { "hopp": {
    "command": "node", "args": ["/path/to/cli/mcp.mjs"],
    "env": { "HOPP_API_KEY": "hopp_live_•••" } } } }

Claude Code skill

Install the skill so Claude Code can make, re-point and track codes when you ask in plain language. It drives the same REST API.

mkdir -p ~/.claude/skills/hopp
curl -s https://hopp.qr-redirects.be/hopp-skill.md -o ~/.claude/skills/hopp/SKILL.md
export HOPP_API_KEY=hopp_live_•••
# then just ask: "make a QR for example.com I can re-point later"

Quotas & limits

Codes are host-scoped: a code resolves only on its own domain. Every redirect runs the same safety check as the UI.

Errors

Errors are JSON: { "error": "code", "message"?: "…" } with the matching HTTP status.