Ontologies

An ontology is your team's live schema — a completed template instantiated for real product data. Creating one deep-copies the template's structure (regenerating every property id) and automatically creates the root passport at the top level, so you can start adding data immediately. There's no separate "activate" step: an ontology is live the moment it's created.

Creating an ontology regenerates every property id. Always read property ids from the ontology's levels (below), never from the template you started with — they won't match.

The ontology model

Name
object
Type
string
Description
Always ontology.
Name
id
Type
string
Description
Unique identifier, e.g. ontology_00a1b2c3d4e5f607.
Name
name
Type
string
Description
Display name (3–255 characters). Nullable.
Name
description
Type
string
Description
Optional description (up to 1000 characters). Nullable.
Name
template
Type
string
Description
The id of the template this ontology was instantiated from. Nullable.
Name
levels
Type
array
Description
The schema tree — an array of level objects (see below). This is your reference for level keys and property ids.
Name
created_at
Type
string
Description
ISO 8601 timestamp of creation.
Name
updated_at
Type
string
Description
ISO 8601 timestamp of the last update.

The level object

Each entry in levels describes one level of the schema. See the Data model for how the type values behave.

Name
key
Type
string
Description
Level key — A is the root; children follow breadth-first (B, C, …). This is what you pass as level when creating passports and imports.
Name
name
Type
string
Description
Human-readable level name. Nullable.
Name
type
Type
string
Description
singular, series, many, or composite. Nullable.
Name
is_root
Type
boolean
Description
Whether this is the root level.
Name
static_lineage
Type
boolean
Description
Whether every ancestor of this level is singular (affects how paths are encoded). Nullable.
Name
parent
Type
string
Description
The parent level key, or null for the root.
Name
children
Type
array
Description
Child level keys.
Name
discoverable
Type
array
Description
The child levels traversed when rendering the public passport (series children are excluded).
Name
properties
Type
array
Description
Property definitions — each has an id, name, type, and value constraints. The id is what you use in passport values and import mappings.

GET/v1/ontologies

List ontologies

Lists your team's ontologies as a paginated list. Requires ontologies:read.

Optional attributes

Name
limit
Type
integer
Description
Page size, 1–100 (default 10).
Name
cursor
Type
string
Description
A pagination cursor from a previous response's next_cursor.

Request

GET

/v1/ontologies

curl -G https://api.synexcloud.com/v1/ontologies \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d limit=10

Response

{
  "object": "list",
  "data": [
    {
      "object": "ontology",
      "id": "ontology_00a1b2c3d4e5f607",
      "name": "EV Battery Line A",
      "description": "2026 production",
      "template": "template_00a1b2c3d4e5f607",
      "levels": [
        { "key": "A", "name": "SKU", "type": "singular", "is_root": true }
      ],
      "created_at": "2026-07-10T12:00:00Z",
      "updated_at": "2026-07-10T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/ontologies"
}

POST/v1/ontologies

Create an ontology

Instantiates a completed template — yours or a public one — into a live ontology. The root passport is created automatically and returned as root_passport; use its id as the parent for your first child passports. Draft templates are rejected with 409 template_is_draft. Requires ontologies:write. Accepts an optional Idempotency-Key header.

Required attributes

Name
template
Type
string
Description
The completed template's id.
Name
name
Type
string
Description
Display name, 3–255 characters.

Optional attributes

Name
description
Type
string
Description
Description, up to 1000 characters.

Request

POST

/v1/ontologies

curl https://api.synexcloud.com/v1/ontologies \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "template_00a1b2c3d4e5f607", "name": "EV Battery Line A", "description": "2026 production" }'

Response

{
  "object": "ontology",
  "id": "ontology_00a1b2c3d4e5f607",
  "name": "EV Battery Line A",
  "description": "2026 production",
  "template": "template_00a1b2c3d4e5f607",
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular", "is_root": true,
      "children": ["B"], "properties": [] },
    { "key": "B", "name": "Pack", "type": "series", "parent": "A",
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement" }
      ] }
  ],
  "root_passport": {
    "object": "passport",
    "id": "pass_00a1b2c3d4e5f607",
    "ontology": "ontology_00a1b2c3d4e5f607",
    "parent": null,
    "level": "A",
    "path": "A",
    "publish_status": null,
    "values": {}
  },
  "created_at": "2026-07-10T12:00:00Z",
  "updated_at": "2026-07-10T12:00:00Z"
}

GET/v1/ontologies/:id

Retrieve an ontology

Returns the ontology including its full levels — level keys, types, and property definitions. This is where you read the property ids you'll write to in passport values and reference in import mappings. Requires ontologies:read.

Request

GET

/v1/ontologies/ontology_00a1b2c3d4e5f607

curl https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

Response

{
  "object": "ontology",
  "id": "ontology_00a1b2c3d4e5f607",
  "name": "EV Battery Line A",
  "description": "2026 production",
  "template": "template_00a1b2c3d4e5f607",
  "levels": [
    {
      "key": "A", "name": "SKU", "type": "singular", "is_root": true,
      "static_lineage": true, "parent": null, "children": ["B"],
      "discoverable": ["B"], "properties": []
    },
    {
      "key": "B", "name": "Pack", "type": "series", "is_root": false,
      "static_lineage": true, "parent": "A", "children": ["C"],
      "discoverable": ["A"],
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement" }
      ]
    }
  ],
  "created_at": "2026-07-10T12:00:00Z",
  "updated_at": "2026-07-10T12:00:00Z"
}