Quickstart

This walkthrough takes you from nothing to a published product passport with a QR code, entirely over the API. Along the way you'll create a key, instantiate an ontology from a template, mint a passport, set and publish its values, 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.

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 publish 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 set its publish_status.

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" }'

# Write property values and publish it
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": "published" }'

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 published a passport end to end. From here:

Was this page helpful?