# Developers

> Public endpoints for verifying Kizmo QR codes and checking QR link safety, plus a REST API with keys and signed alert webhooks.

Canonical page: https://kizmo.io/developers

Base URL: `https://api.kizmo.io`

## Public endpoints

### Check a link from a QR code

`POST /v1/public/check` with `{"url": "https://..."}`

Follows redirects (headers only), checks domain age via RDAP, looks for brand impersonation and risky patterns. Returns `risk` (`low`, `caution`, `high`), `findings`, `hops` and `finalUrl`. Rate limited to 30 requests per 10 minutes per client.

### Verify a Kizmo code

`GET /v1/public/codes/{code}`

Returns the public record: business name, verified domain, placement, destination host, status and when the destination last changed.

### Report a code

`POST /v1/public/reports` with `{"slug": "K7Q2MX", "reason": "sticker", "location": "..."}`

Reasons: `sticker`, `wrong_destination`, `phishing`, `broken`, `other`.

## Authenticated endpoints

The dashboard uses session cookies issued by `/api/auth/*`. On the Business plan and above you can create API keys in Settings, Developers, and call the same endpoints from your own servers:

```
curl https://api.kizmo.io/v1/codes \
  -H "Authorization: Bearer kz_live_..."
```

- `GET /v1/codes`, `POST /v1/codes`: list and create dynamic codes (`label`, `placement`, `destination`, `verifyScreen`, `monitor`)
- `GET /v1/codes/{id}`, `PATCH /v1/codes/{id}`, `DELETE /v1/codes/{id}`: read, change the destination, pause or delete
- `POST /v1/codes/bulk`: create up to 500 codes at once (Pro and above)
- `GET /v1/codes/{id}/stats?days=90`: daily scans, devices and countries, within your plan's analytics window
- `GET /v1/alerts`, `POST /v1/alerts/{id}/resolve`: tamper alerts and reports
- `GET /v1/me`: plan, limits and usage

Keys act as your account, are shown once, and stop working if the plan no longer includes API access. Limits return `402` with `code: "plan_limit"` or `"plan_required"`.

## Alert webhooks

On Pro and above, Kizmo sends a signed `POST` to your endpoint for every new alert (`alert.created`). The `Kizmo-Signature` header is `t=<unix seconds>,v1=<hex>`, where `v1` is the HMAC-SHA256 of `<t>.<raw body>` with your signing secret. Reject requests older than five minutes. Redirects are not followed and private addresses are refused.

## Health

`GET /health` returns `{"ok": true}` when the service is configured and ready.

---

Kizmo: QR codes you own. https://kizmo.io/