Passports

A passport — a digital product passport (DPP) — is one product data record at a level of an ontology. Every passport has a globally unique id, a path within its ontology, optional property values, and a publish_status that can be set explicitly or inherited from its ancestors. Passports are addressed two ways: by their universal id, or by their path.

New to the model? Read the Data model first — it explains levels, the Singular/Series/Many types, paths (TPPMP), and how publish status is inherited. This page assumes those concepts.

The passport model

Name
object
Type
string
Description
Always passport.
Name
id
Type
string
Description
Unique, universal identifier, e.g. pass_00a1b2c3d4e5f607. Resolves any passport at any depth via GET /v1/passports/:id.
Name
ontology
Type
string
Description
The id of the ontology this passport belongs to. Nullable.
Name
parent
Type
string
Description
The parent passport's id. null for the root.
Name
level
Type
string
Description
The level key this passport sits at (e.g. A, B). Nullable.
Name
path
Type
string
Description
The passport's position within the ontology (its TPPMP — e.g. B:07c9…). Nullable.
Name
friendly_id
Type
string
Description
Optional human-readable alias, unique within the parent. Nullable.
Name
publish_status
Type
string
Description
The explicit status: published, draft, or archived. null means it inherits from the parent chain.
Name
publish_status_resolved
Type
string
Description
The effective status after inheritance (present on detail reads only).
Name
values
Type
object
Description
Property values, keyed by the ontology's 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.

Detail reads

A full detail read (GET /v1/passports/:id and the find endpoint) also includes traversal info:

Name
discoverable_levels
Type
array
Description
The child levels reachable from this passport when rendering its public page.
Name
discovery_chain
Type
array
Description
The level traversal used to assemble the full passport.

GET/v1/ontologies/:ontology/passports

List passports at a path

Lists — or searches — the passports under a path within an ontology. Paths start with the level key: B lists the series at level B; deeper paths address a specific branch. Returns a paginated list. Requires passports:read.

Required attributes

Name
path
Type
string
Description
The path to list under, e.g. B.

Optional attributes

Name
search
Type
string
Description
Free-text search within the level (up to 100 characters).
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/:ontology/passports

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

Response

{
  "object": "list",
  "data": [
    {
      "object": "passport",
      "id": "pass_11b2c3d4e5f60718",
      "ontology": "ontology_00a1b2c3d4e5f607",
      "parent": "pass_00a1b2c3d4e5f607",
      "level": "B",
      "path": "B:07c9f2a1b3d4e5f6",
      "friendly_id": "PACK-001",
      "publish_status": "published",
      "values": { "property_9f2k7d": "4500" },
      "created_at": "2026-07-12T09:35:00Z",
      "updated_at": "2026-07-12T09:40:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/ontologies/ontology_00a1b2c3d4e5f607/passports"
}

POST/v1/ontologies/:ontology/passports

Create a passport

Creates a passport at a level of the ontology, under a parent passport — start from the ontology's root_passport. singular levels allow one passport per parent (a second fails with 409 passport_exists_at_level); series and many levels allow any number. You never create level A — the root passport is created with the ontology. Requires passports:write. Accepts an optional Idempotency-Key header.

Required attributes

Name
parent
Type
string
Description
The parent passport's id.
Name
level
Type
string
Description
The level key to create at (e.g. B).

Optional attributes

Name
friendly_id
Type
string
Description
Human-readable alias, unique within the parent (409 friendly_id_taken otherwise).

Request

POST

/v1/ontologies/:ontology/passports

curl https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/passports \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parent": "pass_00a1b2c3d4e5f607", "level": "B", "friendly_id": "PACK-001" }'

Response

{
  "object": "passport",
  "id": "pass_11b2c3d4e5f60718",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "parent": "pass_00a1b2c3d4e5f607",
  "level": "B",
  "path": "B:07c9f2a1b3d4e5f6",
  "friendly_id": "PACK-001",
  "publish_status": null,
  "values": {},
  "created_at": "2026-07-12T09:35:00Z",
  "updated_at": "2026-07-12T09:35:00Z"
}

GET/v1/ontologies/:ontology/passports/find

Find a passport by path

Returns the single passport at an exact path, with full traversal detail. Use this when you know a passport's position (e.g. the root at path A) rather than its id. Requires passports:read.

Required attributes

Name
path
Type
string
Description
The exact path, e.g. A for the root.

Request

GET

/v1/ontologies/:ontology/passports/find

curl -G https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/passports/find \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d path=A

Response

{
  "object": "passport",
  "id": "pass_00a1b2c3d4e5f607",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "parent": null,
  "level": "A",
  "path": "A",
  "friendly_id": null,
  "publish_status": "published",
  "publish_status_resolved": "published",
  "values": { "property_11a0f3": "EV-PACK-48V" },
  "discoverable_levels": ["B"],
  "discovery_chain": [{ "level": "A", "type": "singular" }],
  "created_at": "2026-07-10T12:00:00Z",
  "updated_at": "2026-07-12T09:40:00Z"
}

GET/v1/passports/:id

Retrieve a passport

Retrieves a passport by its universal id — this works for any passport at any depth, without knowing its ontology or path. It's a full detail read: values (file and image values carry short-lived download links), the resolved publish status, and traversal info. Requires passports:read.

A retrieve records a read audit event — every read of a passport is logged, whether from the app or the API.

Request

GET

/v1/passports/pass_11b2c3d4e5f60718

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

Response

{
  "object": "passport",
  "id": "pass_11b2c3d4e5f60718",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "parent": "pass_00a1b2c3d4e5f607",
  "level": "B",
  "path": "B:07c9f2a1b3d4e5f6",
  "friendly_id": "PACK-001",
  "publish_status": "published",
  "publish_status_resolved": "published",
  "values": {
    "property_9f2k7d": "4500",
    "property_datasheet": { "url": "https://files.synexcloud.com/...", "expires_at": "2026-07-12T10:10:00Z" }
  },
  "discoverable_levels": ["C"],
  "discovery_chain": [
    { "level": "B", "type": "series" },
    { "level": "C", "type": "many" }
  ],
  "created_at": "2026-07-12T09:35:00Z",
  "updated_at": "2026-07-12T09:40:00Z"
}

PATCH/v1/passports/:id

Update a passport

Updates any combination of property values, friendly_id, and publish_status in one call. All values are validated against the ontology's property definitions before anything is written — a single bad value fails the whole values group with 400 value_invalid and per-property errors; valid values are then applied. Every change writes an audit event. Requires passports:write.

Optional attributes

Name
values
Type
object
Description
A map of property id → new raw value.
Name
friendly_id
Type
string
Description
A new human-readable alias, unique within the parent.
Name
publish_status
Type
string
Description
published, draft, archived, or automatic. Setting automatic clears the explicit status so the passport inherits again.

series levels with fully static ancestry never inherit published — publishing each instance is an explicit decision. See the series release gate.

Request

PATCH

/v1/passports/pass_11b2c3d4e5f60718

curl -X PATCH https://api.synexcloud.com/v1/passports/pass_11b2c3d4e5f60718 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "property_9f2k7d": 4500, "property_material": "Graphite" },
    "friendly_id": "PACK-001-R2",
    "publish_status": "published"
  }'

Response

{
  "object": "passport",
  "id": "pass_11b2c3d4e5f60718",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "level": "B",
  "path": "B:07c9f2a1b3d4e5f6",
  "friendly_id": "PACK-001-R2",
  "publish_status": "published",
  "values": { "property_9f2k7d": 4500, "property_material": "Graphite" },
  "updated_at": "2026-07-12T09:45:00Z"
}

DELETE/v1/passports/:id

Delete a passport

Deletes the passport and releases its friendly_id for reuse within the parent. Requires passports:write.

Request

DELETE

/v1/passports/pass_11b2c3d4e5f60718

curl -X DELETE https://api.synexcloud.com/v1/passports/pass_11b2c3d4e5f60718 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

Response

{
  "object": "passport",
  "id": "pass_11b2c3d4e5f60718",
  "deleted": true
}

GET/v1/passports/:id/qr

Download a passport's QR code

Renders the QR code linking to the passport's public page — the same link the Synex app prints. Returns binary image data, so write it straight to a file. Requires passports:read.

Optional attributes

Name
format
Type
string
Description
png (default), jpg, svg, or pdf.
Name
size
Type
integer
Description
Pixel size, 64–2048 (default 512).

Request

GET

/v1/passports/:id/qr

curl -G https://api.synexcloud.com/v1/passports/pass_11b2c3d4e5f60718/qr \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d format=png \
  -d size=1024 \
  -o passport-qr.png

Response

HTTP/1.1 200 OK
Content-Type: image/png

(binary QR image — PNG, JPG, SVG, or PDF per the `format` parameter)