Skip to main content
POST https://api.craftkit.dev/v1/embed/catalogs
Publish a named variable catalog — the tree of namespaces, fields, and loops that powers the embed’s variable picker. Each call with the same name creates the next version and marks it current; the previous version is archived, never deleted. Sessions reference a catalog by name via catalogRef.

​
Authorization

​
Authorization
string
required
Bearer ck_live_… — a project API key for a project with embed enabled.

​
Body

​
name
string
required
Catalog name. Lowercase letters, numbers, and hyphens (^[a-z0-9][a-z0-9-]*$, ≤120 chars). Reusing an existing name publishes the next version.
​
catalog
object
required
The full catalog payload.
A CatalogField (used in namespaces[].fields and loops[].itemFields) is:
​
key
string
required
Dot-path key (customer.name). Pattern ^[a-zA-Z_][a-zA-Z0-9_.]*$, ≤160 chars.
​
label
string
required
Display name in the picker (1–160 chars).
​
dataType
string
required
One of text, longtext, number, currency, date, datetime, boolean, image, url, email.
​
required
boolean
default:"false"
Client-side hint; form-fill blocks submit if left blank. Server-side enforcement still uses the template’s variable definition.
​
format
string
Formatting hint (currency:EUR, date:DD/MM/YYYY), ≤60 chars.
​
description
string
Helper text shown under the field, ≤280 chars.
​
previewData
scalar
Dummy value for the live preview / input placeholder.

​
Response

201 when the version is published.
​
id
string
Catalog row UUID for the new version.
​
name
string
The catalog name you passed.
​
version
number
Monotonically increasing version number within this name.

​
Errors

StatuscodeMeaning
401missing_authorizationNo Authorization: Bearer header.
401invalid_credentialsKey not found, revoked, or embed not enabled.
400invalid_jsonBody is not valid JSON.
422invalid_requestname/envelope or catalog failed validation (issues included).
500internal_errorAuth check or catalog persistence threw — retry.
cURL
curl -X POST https://api.craftkit.dev/v1/embed/catalogs \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-catalog",
    "catalog": {
      "allowCustom": false,
      "namespaces": [
        {
          "key": "customer",
          "label": "Customer",
          "icon": "user",
          "fields": [
            { "key": "customer.name",  "label": "Customer name",  "dataType": "text",  "previewData": "Acme Corp" },
            { "key": "customer.email", "label": "Customer email", "dataType": "email", "previewData": "hello@acme.com" }
          ]
        }
      ],
      "loops": [
        {
          "key": "order.items",
          "label": "Order items",
          "itemFields": [
            { "key": "name",  "label": "Product",    "dataType": "text",     "previewData": "Widget A" },
            { "key": "qty",   "label": "Quantity",   "dataType": "number",   "previewData": 2 },
            { "key": "price", "label": "Unit price", "dataType": "currency", "previewData": 49.99 }
          ]
        }
      ]
    }
  }'
201
{
  "id": "0193c2c3-1a2b-7c3d-8e4f-aabbccddeeff",
  "name": "my-catalog",
  "version": 1
}
Reference the published catalog when minting a session: catalogRef: { name: "my-catalog" } resolves to the current version. Add version to pin an archived one.