---
title: "Save a static QR code from structured fields"
method: POST
path: "/v1/codes"
---

# Save a static QR code from structured fields

`POST /v1/codes`

Builds the payload server-side from `fields` and saves it as a static code: the content is encoded directly into the QR image, with no short link and no scan analytics. Static codes cannot be edited afterwards — save a new one to change the content. Field names per type: `url`: url · `text`: text · `email`: email, subject?, body? · `phone`: phone · `sms`: phone, message? · `whatsapp`: phone (country code, digits only), message? · `wifi`: ssid, password?, encryption? (WPA|WEP|nopass), hidden? · `geo`: lat, lng · `vcard`: firstName?, lastName?, phone?, email?, org?, title?, url?, address? (at least one of name/phone/email). Render the returned `payload` as an image via `/v1/qr`.

## Request body

- object
  - `type` 'url' | 'text' | 'email' | 'phone' | 'sms' | 'whatsapp' | 'wifi' | 'geo' | 'vcard', required — The payload type.
  - `fields` object, required — Field values for the type — see the per-type field list above.
  - `label` string — Optional label for your dashboard.
  - `theme` string — A saved theme id or name to style the code with.

## Response `201`

Created.

- StaticCode
  - `id` string
  - `type` string
  - `payload` string — The encoded payload string (what the QR image contains).
  - `label` string, nullable
  - `next` string — Render the payload via GET /v1/qr?data=<payload>.

## Other responses

- `400` — Invalid request — malformed JSON, a missing/invalid required field, or a disallowed dynamic-code destination (destinations must be public http(s) URLs; private/internal hosts and oqr.to self-loops are rejected).
- `401` — The `Authorization: Bearer oqr_…` header is missing or the API key is invalid or revoked.
- `429` — Dynamic-code creation rate limit hit — 20 codes per hour, per user. Bulk requests consume one unit per code and are rejected up-front (nothing created) when they exceed the remaining budget.
- `500` — An unexpected server-side error.

## Changes

- **2026-09-02** `0f28d209971b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openqr/apis/openqr-api/changes/v1/codes/post.md)

---

[API](https://skmtc.dev/openqr/apis/openqr-api.md) · [All operations](https://skmtc.dev/openqr/apis/openqr-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openqr/openqr-api/revisions/0f28d209971b/schema)