> ## Documentation Index
> Fetch the complete documentation index at: https://swapnice.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```ts theme={null}
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",
  },
});
```

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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.