Codes / Create a code

Create a code

POST/v1/codes

Creates a code and returns it with its short link. The destination of a dynamic code can be changed later with PATCH without touching the printed code.

Body parameters

namestringrequiredInternal label for the code — never shown to a scanner.

content.typestringrequiredOne of the supported code types, e.g. url, vcard, wifi.

content.urlstringrequiredDestination for a url code. Required fields vary by type.

dynamicbooleanoptionalDefault true: a short link you can repoint. false encodes the content directly.

designobjectoptionalPattern, eye shape and colours. Defaults to the Dotwick default design.

folderIdstringoptionalFolder to file the code under. Required for keys restricted to folders.

templateIdstringoptionalA saved design template to apply instead of design.

domainIdstring | nulloptionalCustom short-link domain (coming soon: own domains are not switched on yet). Omitted = the workspace default; null = the shared domain.

slugstringoptionalA custom short-link slug instead of a generated one. Must be unique on the domain.

Example request

requestPOST /v1/codes

curl -X POST https://api.dotwick.com/v1/codes \  -H "Authorization: Bearer sk_live_…" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: van-014-2026-09-10" \  -d '{    "name": "Van fleet – unit 14",    "content": {      "type": "url",      "url": "https://example.com/fleet/van-014"    },    "design": {      "pattern": "rounded",      "eyes": {        "frame": "circle",        "ball": "circle"      },      "colors": {        "fg": "#18181B",        "bg": "#FFFFFF"      }    },    "folderId": "fld_8k2m4q7x"  }'

response201 Createdexcerpt — the full object also carries design, rules and timestamps

{  "id": "qr_8841ce2mxk",  "name": "Van fleet – unit 14",  "type": "url",  "dynamic": true,  "status": "active",  "slug": "Xq7mK2p",  "shortUrl": "https://dotwick.co/Xq7mK2p",  "content": {    "type": "url",    "url": "https://example.com/fleet/van-014"  },  "folderId": "fld_8k2m4q7x",  "createdAt": "2026-09-10T09:41:08.000Z"}

Errors

400validation_failedThe body failed schema validation — see error.details for the issues.

401unauthorizedMissing or invalid Authorization header.

403forbiddenThe key lacks codes:write, or is restricted to other folders.

403plan_limit_reachedThe plan's dynamic-code limit is reached.

409conflictThe slug is already taken on this domain.

422idempotency_conflictThe Idempotency-Key was reused with a different body.

422unsafe_destinationThe destination failed the Google Web Risk / blocklist check.

429rate_limitedOver the per-minute or burst budget — see Retry-After.