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, property values, and a publish_status that is either set explicitly or inherited from its ancestors — except released, which a passport only ever has explicitly. Passports are addressed two ways: by their universal id, or by their path.

The passport model

Values

Writes take a flat map of property id → value; reads wrap every property in an envelope:

{
  "values": {
    "property_capacity": { "value": 78.4 },
    "property_serial": { "value": "KES-EVP-24-0917", "language": "en", "is_fallback": false }
  }
}

Translatable types — short_text, long_text, tags, and file — carry language and is_fallback beside value; see Translated values. On a full read, a file or image value carries a short-lived download link inside value, next to its filename, extension, and size; list rows and the PATCH response return the stored file reference without a link.

There is no chart property type: charts are a section of the ontology's composition that plots ordinary numeric values.

Full reads

GET /v1/passports/:id and the find endpoint return the full shape, which adds:

List rows, and the response to a PATCH that changed something, omit these three fields.

Reported granularity

Levels declare their granularity and is_core on the ontology. If the EV Battery Pack ontology reported its product line as model, its packs as batch, and its cells as item, each level its tier's core, a cell would read:

{
  "granularity": {
    "tier": "item",
    "model": "pass_5f0c8b3a6d1e4072",
    "batch": "pass_3e9a1c5b7d2f4083",
    "item": "pass_9c4e7a1d5b3f2064"
  }
}

The block resolves against the ontology version the passport is pinned to. Resolving it costs one read per level, which is why list rows don't carry it.

List passports at a path

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

{
  "object": "list",
  "data": [
    {
      "object": "passport",
      "id": "pass_3e9a1c5b7d2f4083",
      "ontology": "ontology_7d1f4a2b9c3e5081",
      "parent": "pass_5f0c8b3a6d1e4072",
      "level": "B",
      "path": "B:3e9a1c5b7d2f4083",
      "friendly_id": "PACK-24-0917",
      "ontology_version": 2,
      "publish_status": "released",
      "publish_status_resolved": "released",
      "release_number": 1,
      "values": {
        "property_capacity": { "value": 78.4 },
        "property_serial": { "value": "KES-EVP-24-0917", "language": "en", "is_fallback": false }
      },
      "metadata": { "batch_ref": "BATCH-2026-07" },
      "created_at": "2026-07-22T14:10:43Z",
      "updated_at": "2026-07-22T14:18:02Z"
    },
    {
      "object": "passport",
      "id": "pass_6b2d4f8a0c1e7359",
      "ontology": "ontology_7d1f4a2b9c3e5081",
      "parent": "pass_5f0c8b3a6d1e4072",
      "level": "B",
      "path": "B:6b2d4f8a0c1e7359",
      "friendly_id": "PACK-24-0918",
      "ontology_version": 2,
      "publish_status": null,
      "publish_status_resolved": "draft",
      "release_number": 0,
      "values": {
        "property_capacity": { "value": 77.9 },
        "property_serial": { "value": "KES-EVP-24-0918", "language": "en", "is_fallback": false }
      },
      "metadata": {},
      "created_at": "2026-07-22T14:11:09Z",
      "updated_at": "2026-07-22T14:11:09Z"
    }
  ],
  "has_more": true,
  "next_cursor": "WyJvbnRvbG9neV83ZDFmNGEyYjljM2U1MDgxIl0",
  "url": "/v1/ontologies/ontology_7d1f4a2b9c3e5081/passports"
}

Create a passport

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

{
  "object": "passport",
  "id": "pass_3e9a1c5b7d2f4083",
  "ontology": "ontology_7d1f4a2b9c3e5081",
  "parent": "pass_5f0c8b3a6d1e4072",
  "level": "B",
  "path": "B:3e9a1c5b7d2f4083",
  "friendly_id": "PACK-24-0917",
  "ontology_version": 2,
  "publish_status": null,
  "publish_status_resolved": "draft",
  "release_number": 0,
  "values": {},
  "metadata": {},
  "created_at": "2026-07-22T14:10:43Z",
  "updated_at": "2026-07-22T14:10:43Z"
}

Find a passport by path

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

{
  "object": "passport",
  "id": "pass_5f0c8b3a6d1e4072",
  "ontology": "ontology_7d1f4a2b9c3e5081",
  "parent": null,
  "level": "A",
  "path": "A",
  "friendly_id": null,
  "ontology_version": 1,
  "publish_status": "released",
  "publish_status_resolved": "released",
  "release_number": 1,
  "values": {
    "property_line_code": { "value": "KES-EVP-LINE-01", "language": "en", "is_fallback": false }
  },
  "metadata": {},
  "created_at": "2026-07-21T11:04:29Z",
  "updated_at": "2026-07-21T11:09:52Z",
  "discoverable_levels": ["B"],
  "discovery_chain": ["B", "C"],
  "granularity": { "tier": null, "model": null, "batch": null, "item": null }
}

Retrieve a passport

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

{
  "object": "passport",
  "id": "pass_9c4e7a1d5b3f2064",
  "ontology": "ontology_7d1f4a2b9c3e5081",
  "parent": "pass_3e9a1c5b7d2f4083",
  "level": "C",
  "path": "C:3e9a1c5b7d2f4083/9c4e7a1d5b3f2064",
  "friendly_id": "CELL-24-0917-014",
  "ontology_version": 2,
  "publish_status": "released",
  "publish_status_resolved": "released",
  "release_number": 1,
  "values": {
    "property_cell_voltage": { "value": 3.671 }
  },
  "metadata": {},
  "created_at": "2026-07-22T14:14:30Z",
  "updated_at": "2026-07-22T14:16:11Z",
  "discoverable_levels": ["B"],
  "discovery_chain": ["A", "B"],
  "granularity": { "tier": null, "model": null, "batch": null, "item": null }
}

Update a passport

curl -X PATCH https://api.synexcloud.com/v1/passports/pass_3e9a1c5b7d2f4083 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "property_capacity": 78.4, "property_serial": "KES-EVP-24-0917" },
    "friendly_id": "PACK-24-0917",
    "publish_status": "released",
    "include_descendants": true,
    "metadata": { "batch_ref": "BATCH-2026-07" }
  }'

{
  "object": "passport",
  "id": "pass_3e9a1c5b7d2f4083",
  "ontology": "ontology_7d1f4a2b9c3e5081",
  "parent": "pass_5f0c8b3a6d1e4072",
  "level": "B",
  "path": "B:3e9a1c5b7d2f4083",
  "friendly_id": "PACK-24-0917",
  "ontology_version": 2,
  "publish_status": "released",
  "publish_status_resolved": "released",
  "release_number": 1,
  "values": {
    "property_capacity": { "value": 78.4 },
    "property_serial": { "value": "KES-EVP-24-0917", "language": "en", "is_fallback": false }
  },
  "metadata": { "batch_ref": "BATCH-2026-07" },
  "created_at": "2026-07-22T14:10:43Z",
  "updated_at": "2026-07-22T14:18:02Z",
  "release_run": {
    "object": "release_run",
    "id": 4822,
    "status": "pending",
    "mode": "release",
    "root": "pass_3e9a1c5b7d2f4083",
    "total_count": 0,
    "processed_count": 0,
    "skipped_count": 0,
    "failed_count": 0,
    "created_at": "2026-07-22T14:18:02Z",
    "updated_at": "2026-07-22T14:18:02Z"
  }
}

Translated values

short_text, long_text, tags, and file properties hold one value per language, in any of the 24 official EU languages: bg cs da de el en es et fi fr ga hr hu it lt lv mt nl pl pt ro sk sl sv. Every other type holds a single value. Each ontology has a default language — the one its values are authored in.

Reading a language

The endpoints that return passport values — list, find, retrieve, and update — take ?lang=<code>. Each translatable value then reads in that language, with two fields beside value:

Without ?lang, values read in the ontology's default language. When the requested language is missing, the value falls back to the default language, then to the first translation present in the code order above — and says so with is_fallback, so a missing Bulgarian text is never passed off as Bulgarian. Codes are case-insensitive and region subtags are dropped (DE and de-AT read as de); a code outside the 24 is ignored, and values read in the default language.

?lang=all reads value in the default language and adds translations: every language the property holds, keyed by code. On a full read, each translation of a file carries its own download link.

{
  "values": {
    "property_chemistry": {
      "value": "NMC-811 lithium-ion",
      "language": "en",
      "is_fallback": false,
      "translations": {
        "de": "NMC-811-Lithium-Ionen",
        "en": "NMC-811 lithium-ion"
      }
    }
  }
}

A value stored without any language — written before its property held translations — reads as a plain value, without language or is_fallback, and counts as the default language. The next write to it stores it per language.

Writing a language

• A bare value writes the default language: "property_chemistry": "NMC-811 lithium-ion".
• A map of language codes writes those languages: "property_chemistry": { "de": "NMC-811-Lithium-Ionen", "fr": "Lithium-ion NMC-811" }. Keys must be lowercase codes from the list — any other key (ru, DE, de-AT) fails with unsupported_language.
• Writes merge: the languages you name are replaced, and the ones you leave out are kept.
• An explicit null (or "", or []) for a language deletes that translation: { "fr": null }.

Text limits

Each translation is checked on its own: a short_text is at most 255 characters, a long_text 7,000, and a tags value at most 50 tags of up to 64 characters each. A translation is also capped at 14,000 bytes, which binds before the character limit only for a long_text in a script heavier than two bytes per character, such as CJK or emoji. A value over a limit fails the values group with 400 value_invalid, whose errors detail carries code value_too_long and the offending language. A value too large to store at all is 413 passport_too_large.

Dates

A date value is stored as the calendar day it names, always normalized to YYYY-MM-DD. The response echoes back that canonical form — a different string than you sent whenever you write another spelling — which is what keeps dates sortable and comparable with PassQL >, <, and between.

Accepted on write: 2026-07-22, 2026/07/22, 22 Jul 2026, July 22, 2026, 20260722, and ISO 8601 datetimes such as 2026-07-22T10:30:00Z (truncated to the day they name, with no timezone shift).

Rejected with 400 value_invalid / invalid_date: days that don't exist (2026-02-30, 2026-02-29), years outside four digits (99999-01-01), and relative expressions (next tuesday, tomorrow, +1 day) — a value whose meaning changes every time it's read is not a date.

Numeric dates are never guessed at

Whether 03/04/2026 means 3 April or 4 March is a fact about the writer's locale, not about the string, so the API refuses to pick one. A separator-delimited numeric date is rejected with 400 ambiguous_date whenever both readings are real days:

The same applies to - and . separators. Send YYYY-MM-DD and none of this applies to you.

Releases

released is the one publish status with rules of its own. draft and archived are labels; a release is a commitment — it is what the passport's public page serves, what a regulator may read, and — at the item tier's core level — what the team is billed for.

• Explicit, never inherited. A passport is released only when its own publish_status says so. draft and archived still cascade down the chain; a passport with no explicit status under a released ancestor resolves to draft.
• Its own ability. publish_status: "released", and any move away from released, needs releases:write on top of passports:write — 403 insufficient_permissions without it. Every other write needs passports:write alone. See Abilities.
• Top-down. Every ancestor must be released first; otherwise the release is refused with 409 ancestor_not_released, and the message names the nearest one that isn't. An archived passport may be released directly.
• Locked while released. A values or friendly_id write, a move to archived, and DELETE are all refused with 409 passport_released; metadata stays writable. Set it to draft (or automatic) to edit, then release again — that re-release is release_number 2.
• Taken back bottom-up. Un-releasing a passport is refused with 409 descendants_released while anything beneath it is still released. The exception is a passport at the level that carries the ontology's item tier as its core: taking its release back cancels the billed release, drafts the passport, and drafts its released descendants in a draft-mode release run, returned as release_run like a cascade. A release already reported for billing can't be cancelled — 409 release_reported.
• Checked first. A transition the rules refuse is checked before the values and friendly_id groups of the same request are written, so a refused release leaves the values untouched. Filling a passport in and releasing it in one call works, because the values land while it is still editable. A release that moved between the check and the write — cancelled, or released again — is 409 release_conflict; re-read and decide again.

Releasing a subtree

Send include_descendants: true with publish_status: "released" to take the passport's existing subtree with it. The passport itself is released by the time the response is written; its descendants are released by a background run, returned as release_run on the response — poll it with Retrieve a release run. On a passport that is already released, the request starts the run without re-releasing the root.

• The cutoff. The run covers the passports that existed when the release was taken. Anything created afterwards is a new passport, released on its own terms.
• No re-releases. A descendant that is already released, or was released once and then taken back, keeps its own release number and is counted as skipped.
• The chain freezes. Until the run closes, releasing or un-releasing anything on its chain — the root, an ancestor, or a descendant — is refused with 409 release_in_progress.

A single release or un-release emits passport.updated. A run emits only run-level events — release_run.started, then release_run.completed or release_run.failed — never one per descendant.

Delete a passport

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

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

Download a passport's QR code

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

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

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

The release run model

A release run is one release cascade: "release this passport and everything under it", or the same in reverse. It is opened by include_descendants on a release, or by taking back the release of an item-tier core passport — never by a request of its own. A run is bookkeeping, not a passport: it says how much of the subtree has been stamped, not what any of it now says.

Retrieve a release run

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

{
  "object": "release_run",
  "id": 4822,
  "status": "running",
  "mode": "release",
  "root": "pass_3e9a1c5b7d2f4083",
  "total_count": 1240,
  "processed_count": 875,
  "skipped_count": 12,
  "failed_count": 0,
  "created_at": "2026-07-22T14:18:02Z",
  "updated_at": "2026-07-22T14:18:44Z"
}