Entries and ontologies

How partners describe products, SKUs, and collectibles so events and intents attach to a shared catalog.

An entry is an object a user can show intent toward: a product, SKU, card, event, team, creator, badge, or fandom. An ontology is the versioned field map for that kind of object.

You speak in readable field names (name, rarity, set). Swapnice validates them against the ontology and stores them uniformly. Compact internal storage keys are not part of the public API.

Why this matters for a pilot

If events say object: "Blue-Eyes" in one place and object: "sku_blue_eyes_tin" in another, intents do not roll up. Catalog entries give you a stable id that profile and intent reads can share.

Common fields (every ontology)

Field	Meaning
ontology	Which field map to use (ygo, pokemon, intent, or a partner ontology)
entry_name	Display name
owner_id	Catalog owner (your app or a user)
ingestion_origin	Source system (partner_catalog, shopify, …)
entry_id	Optional. Deterministic for source-correlated records
value	Optional list or market value
media.primary_image	Optional image
fields	Ontology-specific attributes

Suggested entry types as you extend beyond collectibles: product, sku, collectible, event, team, creator, badge, fandom, activity.

Create or upsert

await swapnice.entries.upsert({
  ontology: "ygo",
  owner_id: "partner_catalog",
  ingestion_origin: "partner_catalog",
  entry_name: "Blue-Eyes White Dragon",
  value: 12.34,
  media: { primary_image: "https://cdn.example.com/blue-eyes.webp" },
  fields: {
    name: "Blue-Eyes White Dragon",
    yugipedia_uid: "46986414",
    pcid: "2560454",
    rarity: "Ultra Rare",
    set: "Legend of Blue Eyes White Dragon",
  },
});

{
  "status": "created",
  "entry": {
    "entry_id": "46986414;2560454",
    "ontology": "ygo",
    "entry_name": "Blue-Eyes White Dragon",
    "owner_id": "partner_catalog",
    "ingestion_origin": "partner_catalog",
    "value": 12.34,
    "image_upload_status": "uploaded",
    "fields": {
      "name": "Blue-Eyes White Dragon",
      "yugipedia_uid": "46986414",
      "pcid": "2560454"
    }
  }
}

status is created, updated, or unchanged (checksum matched). Identity fields are required for that ontology — for Yu-Gi-Oh that includes the source ids that make the record correlatable. Do not send random ids for objects that already have a source key.

Unknown fields are rejected unless Swapnice agrees to evolve the ontology. Schema drift should be intentional.

Read ontologies

curl "$SWAPNICE_API_BASE_URL/v1/ontologies" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Each ontology returns readable field names, types, and which fields are required for identity. After a bulk import, Swapnice can rebuild filter metadata with POST /v1/ontologies/:id/fields/rebuild.

How events should reference entries

{
  "event_type": "purchase.completed",
  "ontology_category": "outcome",
  "object": "46986414;2560454",
  "payload": { "sku": "sku_blue_eyes_tin", "entry_id": "46986414;2560454" }
}

Use the entry id as object whenever you have one. Free-text names are a last resort.

Partner-owned catalogs

Retail, merch, and event partners often already have a product catalog (Shopify, POS, ticketing). The usual pattern:

1. Upsert the SKUs or events you will send activity for (or a subset for the pilot)
2. Map your id → Swapnice entry_id once
3. Emit events against that id
4. Read intents grouped by those objects

You do not need to import an entire collectibles archive to start. Two or three SKUs is enough to prove the join.