Quickstart

This walkthrough takes you from nothing to a released product passport with a QR code, entirely over the API. Along the way you'll create a key, instantiate an ontology from a template, issue a passport, fill in its values and release it, and mass-import more.

Every request authenticates with a secret API key. Create one from API Keys in the Synex application — the secret (synex_sk_...) is shown only once, and the key is pinned to the team you created it in. A new key gets four read abilities by default; for this walkthrough also grant ontologies:write, passports:write, releases:write, files:read, files:write, imports:read and imports:write. See abilities.

Set up your environment

Export your key and the API base URL so the examples below stay short. The base URL is your Synex deployment's domain with the /v1 version prefix.

export SYNEX_API_KEY="synex_sk_..."
export SYNEX_API="https://api.synexcloud.com/v1"

Check that the key works — GET /me returns the key's pinned team, abilities, and ontology scopes:

GET
/v1/me
curl -s $SYNEX_API/me -H "Authorization: Bearer $SYNEX_API_KEY"

1. Pick or build a template

Templates are reusable schema blueprints with a draft → complete lifecycle. Browse the public catalog by category, or build your own. Only a completed template can be instantiated.

GET
/v1/templates
curl -s -G $SYNEX_API/templates \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d category=battery

2. Instantiate an ontology

An ontology is your team's live schema, deep-copied from a completed template. Creating one automatically creates its root passport, so you can start adding data immediately. The response includes levels (with the property ids you'll write values to) and root_passport.id — keep both.

POST
/v1/ontologies
curl -s $SYNEX_API/ontologies \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "template_00a1b2c3d4e5f607", "name": "EV Battery Line A" }'

3. Create a passport and release it

Passports are created under a parent at a given level (a depth letter like B). Then PATCH the passport to write property values — keyed by property id — and release it by setting publish_status to released.

A release is explicit and goes top down: a passport can only be released once every ancestor is, so release the root passport first. Filling in values and releasing in the same PATCH works, because the values are written while the passport is still editable — once released, its values are locked until you set it back to draft. See passports.

POST
/v1/ontologies/:ontology/passports
# Create a passport at level B under the root
curl -s $SYNEX_API/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" }'

# Release the root, then write the pack's values and release it
curl -s -X PATCH $SYNEX_API/passports/pass_00a1b2c3d4e5f607 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "publish_status": "released" }'

curl -s -X PATCH $SYNEX_API/passports/pass_11b2c3d4e5f60718 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "property_9f2k7d": "4500" }, "publish_status": "released" }'

4. Mass-import from a spreadsheet

To create many passports at once, upload a file, preview its sheets to build a column mapping, then start an import and poll it until it finishes.

POST
/v1/imports
# Upload, then preview to read the header row
curl -s $SYNEX_API/files -H "Authorization: Bearer $SYNEX_API_KEY" -F "file=@units.xlsx"
curl -s $SYNEX_API/files/file_00a1b2c3d4e5f607/preview -H "Authorization: Bearer $SYNEX_API_KEY"

# Start the import (map spreadsheet columns → property ids), then poll it
curl -s $SYNEX_API/imports \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file": "file_00a1b2c3d4e5f607", "target": "pass_00a1b2c3d4e5f607", "rows": 120,
        "levels": [{ "level": "B", "mapping": { "0": "property_9f2k7d", "1": "friendly_id" } }] }'

curl -s $SYNEX_API/imports/import_00a1b2c3d4e5f607 -H "Authorization: Bearer $SYNEX_API_KEY"

5. Download the QR code

Every passport has a public page; its QR code is the same link the Synex app prints. Download it in png, jpg, svg, or pdf.

GET
/v1/passports/:passport/qr
curl -s -G "$SYNEX_API/passports/pass_11b2c3d4e5f60718/qr" \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d format=png -d size=1024 \
  -o passport-qr.png

What's next?

You've released a passport end to end. From here:

Was this page helpful?