API reference

Overview

The /v1 API lets a workspace create, list, retarget, pause, activate and delete hosted QR codes, read each code's scan stats, get each code's QR as a styled SVG or PNG, and read its plan usage. Every code gets a public scan URL at the domain root: https://vlcard.me/<short_code>. On plans with custom links (Business and above) a code can also have a vanity slug, https://vlcard.me/<slug>, which scans the same way; the short-code URL keeps working either way. Scans get a 302 to the code's current destination, so you can change where a printed QR goes without reprinting it.

On Enterprise and the partner API plans, webhooks push code changes and scans to your own HTTPS endpoint as they happen; see Webhooks.

Call the API from your server. Browser calls from other origins are blocked by CORS, and an API key in front-end code is a leaked key.

Requests and responses are JSON (Content-Type: application/json). Timestamps are RFC 3339 in UTC. Codes created through the API always have origin set to api.

Destination rules (checked on create and update, same rules as the dashboard):

• http or https URL with a host, at most 2048 bytes after trimming surrounding whitespace.
• No spaces or control characters inside the URL, no user@ userinfo, no IP-literal hosts such as [::1], and a port of 1 to 5 digits if present.
• Percent escapes in the path and fragment must be valid and must not encode NUL, CR or LF. The query string is passed through as is.

A destination that breaks any rule is rejected with 400 invalid_destination.

Base URL: https://vlcard.me/v1

Authentication

A workspace API key, sent as X-API-Key: vlq_…. Managers of a workspace whose plan includes API access mint keys in the dashboard under API. The full key is shown once; only a hash is stored, so if you lose it, revoke it and mint a new one. A key acts on its own workspace only.

Rate limits

There are two budgets, chosen after the key is looked up.

• Valid key: limited per key to your plan's requests per minute (Business 120, Enterprise 600, Partner 300, Scale 1,200, Platform 3,000). The window is a fixed minute that starts with the first request. Over the limit you get 429 rate_limited with no rate-limit headers; wait for the minute to pass.
• Missing, unknown, revoked or no-access key: 60 requests per minute per client IP, shared by every protected /v1 route. These responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). The 61st request gets 429 rate_limited with Retry-After in seconds.

GET /v1/health is never rate limited. Scans of https://vlcard.me/<short_code> never count against these limits and are never answered with 429.

Errors

Errors are JSON with one field, error, holding a stable snake_case code: {"error": "not_found"}. Branch on the code, not on the HTTP status alone. Unmatched paths under /v1 return 404 not_found.

Webhooks

Webhooks push events to your own HTTPS endpoint as they happen, so you don't have to poll /v1. They come with Enterprise and the partner API plans (Partner, Scale, Platform).

Setting up. Workspace owners and admins add endpoints in the dashboard under Settings → Webhooks: an HTTPS URL and the events it should receive. A workspace can have up to 5 endpoints. Each endpoint gets its own signing secret (whsec_…), shown once when you add the endpoint or rotate the secret; keep it on your server like a password. Rotating replaces the secret at once, including for retries of earlier events. Send test event posts a webhook.test event to that endpoint only, once. Endpoints are managed in the dashboard only; there are no /v1 endpoints for them.

Events.

• code.created: a code was created in the dashboard, over /v1 or by our staff. A code created with a custom link arrives once, with vanity_slug already set.
• code.updated: a code's destination, name, status (paused, activated, expired) or expiry changed, or its custom link was set, changed or removed. data.changes lists what changed and data.previous holds the old values. A code becomes expired when the first scan after expires_at finds it, so that event arrives then, not at expires_at itself.
• code.deleted: a code was deleted (retired). Its short code is never reused and scans get a "no longer active" page.
• scan.created: codes were scanned. Scans are grouped: one event carries 1 to 100 scans (data.scans) of one workspace, gathered over about 2 seconds, so a busy code doesn't cause a request per scan. Each scan's code.vanity_slug is the custom link that scan came through, or null when the short-code URL was scanned.

Delivery. We POST a JSON body {id, type, created_at, workspace_id, data} with Content-Type: application/json, a few seconds after the event. Any 2xx within 10 seconds counts as delivered; redirects are not followed and count as a failure. Failures are retried with backoff (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 8 h), 10 attempts over about 24 hours, then the delivery is marked failed. An endpoint that has failed for 3 days without a single success is disabled; the dashboard shows it and you can enable it again. Every delivery from the last 30 days is listed under its endpoint with its status, response code and attempts, and can be sent again from there.

Order and duplicates. Events can arrive out of order and, rarely, more than once (delivery is at least once). Use id (evt_…) to drop duplicates, created_at or the code's updated_at to order them, and each scan's own id if you store scans. Answer quickly with a 2xx and do slow work afterwards.

Verifying. Every request carries VisionLink-Signature: t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 with your endpoint's secret (the whole whsec_… string as the key) over <t>.<raw request body>. Compute it over the raw bytes you received, before any JSON parsing, compare in constant time, and reject a t more than 5 minutes from your clock so an old request can't be replayed. There may be more than one v1= value; accept the request if any of them matches. VisionLink-Event-Id and VisionLink-Event-Type repeat the body's id and type.

Privacy. Scan events carry the time, country, device type, browser, operating system, referring site's domain, campaign (UTM) tags and whether the scan looked like a bot. Never the scanner's IP address (or its hash), user-agent text, language or visitor identifier.

{
  "id": "evt_3b9f0c6ad2e94a7f8e51c2d4b6a8f0e1",
  "type": "code.created",
  "created_at": "2026-09-23T08:00:01.250Z",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "code": {
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "org_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "short_code": "aB3xY9",
      "name": "Spring menu",
      "destination": "https://example.com/menu",
      "status": "active",
      "origin": "api",
      "expires_at": null,
      "has_ad": false,
      "created_at": "2026-09-23T08:00:01.201Z",
      "updated_at": "2026-09-23T08:00:01.201Z",
      "deleted_at": null,
      "vanity_slug": "spring-menu",
      "vanity_url": "https://vlcard.me/spring-menu"
    }
  }
}

{
  "id": "evt_9d2c41e07ab5463c8f1e2a3b4c5d6e7f",
  "type": "code.updated",
  "created_at": "2026-09-24T12:30:00.004Z",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "code": {
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "org_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "short_code": "aB3xY9",
      "name": "Spring menu",
      "destination": "https://example.com/menu-v2",
      "status": "active",
      "origin": "api",
      "expires_at": null,
      "has_ad": false,
      "created_at": "2026-09-23T08:00:01.201Z",
      "updated_at": "2026-09-24T12:30:00.001Z",
      "deleted_at": null,
      "vanity_slug": "spring-menu",
      "vanity_url": "https://vlcard.me/spring-menu"
    },
    "changes": [
      "destination"
    ],
    "previous": {
      "destination": "https://example.com/menu"
    }
  }
}

{
  "id": "evt_1a2b3c4d5e6f47809a1b2c3d4e5f6a7b",
  "type": "code.deleted",
  "created_at": "2026-10-01T09:15:42.870Z",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "code": {
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "org_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "short_code": "aB3xY9",
      "name": "Spring menu",
      "destination": "https://example.com/menu-v2",
      "status": "deleted",
      "origin": "api",
      "expires_at": null,
      "has_ad": false,
      "created_at": "2026-09-23T08:00:01.201Z",
      "updated_at": "2026-10-01T09:15:42.866Z",
      "deleted_at": "2026-10-01T09:15:42.866Z",
      "vanity_slug": null,
      "vanity_url": null
    }
  }
}

{
  "id": "evt_5f0e1d2c3b4a49588776655443322110",
  "type": "scan.created",
  "created_at": "2026-09-24T07:45:12.502Z",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "scans": [
      {
        "id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
        "scanned_at": "2026-09-24T07:45:10.917Z",
        "code": {
          "short_code": "aB3xY9",
          "vanity_slug": "spring-menu"
        },
        "country": "ZA",
        "device": "mobile",
        "browser": "Chrome",
        "os": "Android",
        "referrer_host": null,
        "utm_source": "poster",
        "utm_medium": "print",
        "utm_campaign": "spring",
        "is_bot": false
      }
    ]
  }
}

{
  "id": "evt_c0ffee00c0ffee00c0ffee00c0ffee00",
  "type": "webhook.test",
  "created_at": "2026-09-23T08:05:00.000Z",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "message": "Test event from VisionLink QR. Your endpoint received and can verify it.",
    "endpoint_id": "9b2e7c1a-4d3f-4a6b-8c9d-0e1f2a3b4c5d"
  }
}

// Node 18+. Keep the raw body: with Express, use express.raw({ type: "application/json" }).
import crypto from "node:crypto";

export function verifyVisionLinkSignature(rawBody, header, secret, toleranceSeconds = 300) {
  let timestamp = NaN;
  const signatures = [];
  for (const piece of String(header ?? "").split(",")) {
    const [key, value] = piece.trim().split("=");
    if (key === "t") timestamp = Number(value);
    if (key === "v1" && value) signatures.push(value);
  }
  if (!Number.isInteger(timestamp) || signatures.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  return signatures.some((sig) => {
    const given = Buffer.from(sig, "hex");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

// app.post("/visionlink/webhooks", express.raw({ type: "application/json" }), (req, res) => {
//   const ok = verifyVisionLinkSignature(req.body, req.get("VisionLink-Signature"), process.env.VISIONLINK_WEBHOOK_SECRET);
//   if (!ok) return res.sendStatus(400);
//   const event = JSON.parse(req.body);
//   // Drop duplicates by event.id, then handle event.type.
//   res.sendStatus(204);
// });

package webhook

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "errors"
    "strconv"
    "strings"
    "time"
)

// VerifySignature checks a VisionLink-Signature header against the raw request body.
func VerifySignature(body []byte, header, secret string, tolerance time.Duration) error {
    timestamp := int64(-1)
    var signatures []string
    for _, part := range strings.Split(header, ",") {
        key, value, _ := strings.Cut(strings.TrimSpace(part), "=")
        switch key {
        case "t":
            n, err := strconv.ParseInt(value, 10, 64)
            if err != nil {
                return errors.New("bad timestamp")
            }
            timestamp = n
        case "v1":
            signatures = append(signatures, value)
        }
    }
    if timestamp < 0 || len(signatures) == 0 {
        return errors.New("no signature")
    }
    if age := time.Since(time.Unix(timestamp, 0)); age > tolerance || age < -tolerance {
        return errors.New("timestamp outside the tolerance")
    }
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(strconv.FormatInt(timestamp, 10) + "."))
    mac.Write(body)
    expected := mac.Sum(nil)
    for _, s := range signatures {
        if given, err := hex.DecodeString(s); err == nil && hmac.Equal(given, expected) {
            return nil
        }
    }
    return errors.New("signature mismatch")
}

// In your handler: read the raw body, then
//   err := VerifySignature(body, r.Header.Get("VisionLink-Signature"), secret, 5*time.Minute)
// Answer 400 on an error; otherwise drop duplicates by the event id, handle it and answer 204.

Objects