Catalog: load what you offer, recommend from it

Field types

text, keyword

A string. Use keyword for values you compare exactly (an id, a brand), text for titles and descriptions.

keywordList

A list of strings, such as categories. On a dimension, an item keeps at most 8 values.

number

A finite number.

money

An object with exactly amount (a number) and currency (three capital letters).

boolean

true or false.

time

A whole number of milliseconds since the epoch, 0 or more.

url

An http or https address.

Roles

A field takes roles that tell the platform how to use it. A field with no role is stored and shown in the console, and can be reported on.

title, url, image

The payload a pick returns. At most one field of each. title is text or keyword; url and image are url.

serve

Other fields to return with a pick. Title, url and image plus 5 more, cut to 1 KB in all.

available

A boolean. An item with false is not picked. At most one.

published, expires

time fields. An item is picked only between them; the clock decides, so no write is needed when they pass. At most one of each.

dimension

A keyword or keywordList the recommendation scores on and reports group by, such as category, brand or topic. Up to 8 per type.

filter

A field a slot filter may test, such as price or rating. Up to 8 per type.

value

A number or money field that says what a pick is worth, such as margin. At most one.

The helper defineItemType in @usercurrent/config expands three presets into this shape: product (id sku), article (id slug, with published and expires) and generic (id id). The product preset declares price as money, so items for it send {"amount": 129, "currency": "USD"}; the example below uses a plain number instead. A type for anything else, such as courses, listings or recipes, is an ordinary declaration.

{
  "type": "item_type",
  "key": "product",
  "name": "Products",
  "draft": {
    "idField": "sku",
    "fields": {
      "sku":      { "type": "keyword" },
      "title":    { "type": "text",        "roles": ["title"] },
      "url":      { "type": "url",         "roles": ["url"] },
      "image":    { "type": "url",         "roles": ["image"] },
      "price":    { "type": "number",      "roles": ["value", "filter"] },
      "category": { "type": "keywordList", "roles": ["dimension"] },
      "brand":    { "type": "keyword",     "roles": ["dimension"] },
      "inStock":  { "type": "boolean",     "roles": ["available"] }
    },
    "events": ["product_view", "add_to_cart"]
  }
}

Declare the events that mention the type

Events describe items without a lookup: an event carries the item's id and up to 8 attributes, declared once in the tracking plan as a snapshot. The type's events list names the events that mention it, and every listed event must already declare a snapshot whose item is the type's id field, or the type does not publish. The attributes and the optional numeric value must be declared fields of the type and not personal data, and an attribute's type must agree with the field: a keywordList field takes an array property, and a string where a list is declared is dropped from the observed item. Events with a value count as successes for popularity, the others as views.

For a slot to learn from browsing, the event also declares affinity: the properties that become the visitor's interests, which the slot's dims then name. The signal says how much the event counts (view, click, add_to_cart, purchase or dismiss). Without it the profile keeps no interests and the slot ranks on item value alone.

{
  "type": "tracking_plan",
  "key": "tracking_plan",
  "name": "Tracking plan",
  "draft": {
    "v": 0,
    "events": [
      {
        "name": "product_view",
        "description": "A product page was viewed.",
        "properties": {
          "sku": { "type": "string" },
          "category": { "type": "array" },
          "brand": { "type": "string" }
        },
        "affinity": { "dimensions": ["category", "brand"], "signal": "view" },
        "snapshot": { "item": "sku", "attributes": ["category", "brand"] }
      },
      {
        "name": "add_to_cart",
        "description": "A product was added to the cart.",
        "properties": {
          "sku": { "type": "string" },
          "category": { "type": "array" },
          "brand": { "type": "string" },
          "price": { "type": "number" }
        },
        "affinity": { "dimensions": ["category", "brand"], "signal": "add_to_cart" },
        "snapshot": { "item": "sku", "attributes": ["category", "brand"], "value": "price" }
      }
    ]
  }
}

usercurrent.config.ts can declare a snapshot for scalar properties, but its event format has no array properties and no affinity, so declare catalog events in the tracking plan object as above.

Publish the plan and the type together

# 1. Save the two objects as drafts (the MCP tools create_draft and update_draft do the same).
#    A project has one tracking plan: if it already has one, read it with get_object and add these events to it.
curl -X POST "$CONTROL/api/v1/projects/$PROJECT/objects" \
  -H "Authorization: Bearer $USERCURRENT_TOKEN" -H "Content-Type: application/json" -d @tracking-plan.json
curl -X POST "$CONTROL/api/v1/projects/$PROJECT/objects" \
  -H "Authorization: Bearer $USERCURRENT_TOKEN" -H "Content-Type: application/json" -d @product.item-type.json

# 2. Publish them together. Publishing the item type alone fails: its events need their snapshots in the same version.
curl -X POST "$CONTROL/api/v1/projects/$PROJECT/environments/dev/publish" \
  -H "Authorization: Bearer $USERCURRENT_TOKEN" -H "Content-Type: application/json" -d '{ "message": "Product catalog" }'

Item types and the tracking plan are created and published through the control API or the MCP server (create_draft or update_draft, then publish). Item types are not keys of usercurrent.config.ts yet, so uc publish does not carry them. Publishing to Production from an agent key waits for a person.

File formats

NDJSON: one JSON object per line, in the same shape as an upsert item. CSV: a header row, then one item per row. The header must hold the id field, may not repeat a column, and may name only declared fields. Text, keyword and url columns are read as written; number, boolean, time, keywordList and money columns are read as JSON, so a list is ["a","b"] and money is {"amount":10,"currency":"USD"}, quoted as CSV needs. An empty cell means the field is not given. The JSON value null in a number, boolean, time, keywordList or money cell removes that field, as null does in an upsert; text, keyword and url cells cannot be removed from a CSV. A UTF-8 byte order mark is accepted. A file whose bytes are not valid UTF-8 fails.

{"sku":"trail-100","title":"Trail 100 pack","url":"https://shop.example.com/p/trail-100","price":129,"category":["packs"],"brand":"Alder","inStock":true}
{"sku":"trail-200","title":"Trail 200 pack","url":"https://shop.example.com/p/trail-200","price":179,"category":["packs","hiking"],"brand":"Alder","inStock":false}

sku,title,url,price,category,brand,inStock
trail-100,Trail 100 pack,https://shop.example.com/p/trail-100,129,"[""packs""]",Alder,true
trail-200,Trail 200 pack,https://shop.example.com/p/trail-200,179,"[""packs"",""hiking""]",Alder,false

Full and incremental

Every import names a feed (letters, digits, underscores and hyphens, up to 128) and a mode. An incremental import only upserts the rows it holds. A full import also retires the items its feed supplied before and its file does not hold. It only retires items that this feed last certified, so items from the API, a different feed or a connector are never touched, and an item written after the sync started is kept. Use full only with a file that is the whole feed.

The retire guard

A full sync that would retire more than 10% of the feed's items and more than 100 items stops before retiring anything and waits in awaiting_confirmation. A truncated export therefore retires nothing. A person looks at the counts (missing of feedItems) in the console or the status and either confirms, which retires them, or discards, which retires nothing. Updates the import already applied stay in both cases. Below the guard a full sync retires its missing items without asking.

From the CLI

export USERCURRENT_URL=https://console.example.com
export USERCURRENT_PROJECT=prj_...
export USERCURRENT_TOKEN=...            # a personal or agent key, never an argument

uc catalog import --environment dev --type product --file products.ndjson --feed shop-feed --mode full
uc catalog import-status --environment dev --type product --id <import id>
uc catalog confirm       --environment dev --type product --id <import id>   # only when the status says awaiting_confirmation
uc catalog discard       --environment dev --type product --id <import id>

From any HTTP client

# 1. Declare the file. bytes is its exact length.
curl -X POST "https://events.example.com/v1/catalog/product/imports" \
  -H "x-usercurrent-key: $UC_PUBLIC_KEY" -H "Authorization: Bearer $UC_SECRET_KEY" \
  -d '{ "feed": "shop-feed", "format": "ndjson", "mode": "full", "bytes": 48213 }'
# { "id": "...", "phase": "uploading", "upload": { "url": "...", "headers": { ... }, "expiresIn": 3600 } }

# 2. PUT the file once, within the hour, with exactly the headers given. The object is create-only.
curl -X PUT "<upload.url>" -H "content-length: 48213" -H "content-type: application/x-ndjson" -H "if-none-match: *" --data-binary @products.ndjson

# 3. Queue it, then read its status until phase is completed, awaiting_confirmation or failed.
curl -X POST "https://events.example.com/v1/catalog/product/imports/$ID/start"   -H "x-usercurrent-key: ..." -H "Authorization: Bearer ..."
curl         "https://events.example.com/v1/catalog/product/imports/$ID"         -H "x-usercurrent-key: ..." -H "Authorization: Bearer ..."
# /confirm and /discard are POSTs on the same path.

The control API has the same imports under /api/v1/projects/{projectId}/environments/{environment}/catalog/{type}/imports, which is what the CLI, the MCP tools and the console call.

Phases

uploading

Created; the file has not been started.

queued

Started and waiting for the imports before it.

validating

Every row is checked before any is applied. A bad row fails the import with nothing applied.

applying

Rows are upserted in steps of up to 5,000. A failure partway leaves the earlier steps applied.

checking

A full sync counts the feed items the file did not hold.

awaiting_confirmation

The retire guard stopped the sync. Nothing is retired until a person confirms or discards.

retiring

Retiring the missing items.

completed, discarded, failed

Done. failed carries an error code; discarded retired nothing.

Rows that appear twice in one file count as duplicates in the status, and the last one wins. A rejected step retries; if it keeps failing the import fails with its error. If the lake is unavailable an import keeps applying until the history backlog fills.

Events that declare a snapshot are grouped by item. A key becomes an observed item once at least 5 distinct visitors have touched it within 7 days; visitors classed as crawlers or agents never count, and a visitor with no classification does. A one-off id, a mistyped key or personal data typed into an item key therefore stays out. A new observed item shows in the console within the Lake flush interval, and a changed attribute on a known item is rewritten at most once a day. Each type keeps up to 8 observed attributes, the ones the snapshot declares.

Drift marks a certified item whose observed value for a field is unlike the certified one, or that has observed fields your feed lacks. It is how a stale feed or broken page tagging shows up: a price that events carry and your feed does not match, a category the feed never had. The console lists the drifting fields on the item.

Observed items are never returned by a slot. Whether a pick may name an item that exists only as observed is an open question.

Item reports are queries of kind items (run with run_query, saved as insights, or placed on dashboards as tables). They cover top items, engagement, funnel (the same person on the same item), click_through (per picked item, matching clicks to exposures by person, item and decision id) and versions (one item's history, newest 50 first). Group by any field with field: a field named in the event's snapshot is read from the event, and any other field is joined from the item's history as it was when the event happened. The query carries the item type and snapshot declarations, which must match what is published.

{
  "v": "analytics.1",
  "kind": "items",
  "report": "top",
  "event": { "event": "product_view" },
  "field": "brand",
  "catalog": { ...the published item type, with its id... },
  "snapshots": { ...the snapshot declarations of the events used... }
}

Item-field segments add an item and property to an event condition. Validation names an unknown type or field and refuses a field the event's snapshot does not declare.

{
  "type": "segment",
  "key": "alder_browsers",
  "name": "Looked at Alder products",
  "draft": {
    "v": 0,
    "condition": {
      "kind": "event",
      "event": "product_view",
      "window": { "value": 30, "unit": "days" },
      "count": { "op": "gte", "value": 3 },
      "where": [{ "item": "product", "property": "brand", "op": "eq", "value": "Alder" }]
    }
  }
}