API Reference

Every Type-2 node runs the same Hermes API. The launchpad shows you the URL on the node detail page (typically http://<your-droplet-ip>). You authenticate per-facility with a bearer token, then read and write assets and events against your node — which batches them into bundles published on-chain.

Core data model

Base URL

http://<your-type-2-droplet-ip>

Find the URL on your node's detail page at /nodes/mine. SSL/custom domain support is on the roadmap; today the API is exposed on plain HTTP port 80 of the droplet.

Two services, two ports

Authentication header

Authorization: UNOVA_TOKEN <jwt>

Tokens are per-facility. Generate one in /data/company → Facilities → API token. The token you get back (from the launchpad or from /auth/getApiToken) is the entire header value — it already starts with UNOVA_TOKEN , so pass it as-is without prepending anything.

Response envelope

All responses are JSON, wrapped in this shape:

{
  "data": [ /* result(s) — an array for lists, an object for single lookups */ ],
  "meta": {
    "code": 200,
    "count": 42,              // number of items in data (list endpoints)
    "message": "..."          // only present sometimes, e.g. "No results found"
  },
  "pagination": { /* present on paged list endpoints */ }
}

On most endpoints the result count lives at meta.count and you iterate data directly. Three exceptions: GET /assets/:uniqueID/events returns {results, resultCount} without the envelope, POST /asset2/v2/assetSearch nests its paged result (items + cursors) inside data, and GET /bundle/:bundleId returns raw bundle JSON.

Read access

Privacy at the bundle level: data with accessLevel > 0is automatically encrypted with your organization's key before being bundled. Other Atlas nodes that shelter the bundle see ciphertext they can't decrypt — only your organization's accounts can read it back.

The one exception is GET /bundle/:bundleId — deliberately public so other Atlas nodes can pull bundles for sheltering and challenge resolution. Bundle listing endpoints (GET /bundle/, POST /bundle/query) require auth.

Each facility you create at /data/company gets its own auto-generated wallet (privkey encrypted at rest in the launchpad). To get an API token, you exchange that privkey at your node's /auth/getApiToken endpoint.

The launchpad does this for you — when you click API token on a facility, it loads the privkey, calls Hermes, and returns the bearer. You never need to handle the privkey manually.

{
  "privateKey": "0x..."
}

{
  "data": {
    "apiToken": "UNOVA_TOKEN eyJhbGciOi..."
  },
  "meta": { "code": 200 }
}

Token permissions

Tokens carry permissions inherited from the wallet they were issued to. Common ones:

A facility wallet typically has create_asset + create_event. The node operator wallet typically has super_account. Permissions are configured during the organization-onboarding flow on Hermes.

Every createendpoint (asset or event) requires a signed payload so the network can verify the writer's identity and detect tampering. The signing scheme is the same for both:

1. Build the payload object (the idData for assets, or idData + data for events).
2. Serialize using the deterministic format below (sorted keys, no whitespace).
3. Hash via web3.eth.accounts.hashMessage(serialized) (EIP-191 personal_sign hash).
4. Sign with the facility's private key — web3.eth.accounts.sign(serialized, privateKey) handles step 3+4 together.
5. The resulting hash also serves as the :assetId or :eventId in the URL — Hermes checks they match.

Deterministic serialization

All object keys are sorted alphabetically; arrays preserve order; strings are JSON-quoted; numbers and booleans stringify to their default form. No whitespace.

// Pseudocode for serializeForHashing
function serialize(x) {
  if (isObject(x)) {
    const keys = Object.keys(x).sort();
    return "{" + keys.map(k => `"${k}":${serialize(x[k])}`).join(",") + "}";
  }
  if (Array.isArray(x)) {
    return "[" + x.map(serialize).join(",") + "]";
  }
  if (typeof x === "string") return `"${x}"`;
  return String(x);
}

Node.js example — sign + create an asset

import Web3 from "web3";
const web3 = new Web3();

// Your facility's private key (decrypted from the launchpad's API-token modal,
// or stored in your warehouse / IoT system)
const FACILITY_PRIVKEY = "0x...";
const FACILITY_ADDRESS = "0x...";  // derived from the privkey

// 1. Build the idData
const idData = {
  createdBy: FACILITY_ADDRESS,
  timestamp: Math.floor(Date.now() / 1000),
  sequenceNumber: 0,
};

// 2-4. Serialize + sign in one call
const serialize = (x) => { /* see above */ };
const serialized = serialize(idData);
const { signature } = web3.eth.accounts.sign(serialized, FACILITY_PRIVKEY);

// 5. Compute the assetId — it's the hash of the {idData, signature} content
const content = { idData, signature };
const contentSerialized = serialize(content);
const assetId = web3.eth.accounts.hashMessage(contentSerialized);

// 6. POST to the node
// BEARER = data.apiToken from /auth/getApiToken — it already starts
// with "UNOVA_TOKEN ", so pass it as-is.
const res = await fetch(`${HERMES_URL}/asset2/create/${assetId}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": BEARER,
  },
  body: JSON.stringify({ content }),
});

For events, the content additionally includes a data array, and idData includes assetId + dataHash (the hash of the data array). See the Events section.

Five end-to-end examples covering the flows almost every integration needs. Replace placeholders (HERMES_URL, FACILITY_PRIVKEY, FACILITY_ADDRESS) with values from your facility's API token modal in /data/company.

curl -X POST "$HERMES_URL/auth/getApiToken" \
  -H "Content-Type: application/json" \
  -d '{"privateKey":"'"$FACILITY_PRIVKEY"'"}'
# → { "data": { "apiToken": "UNOVA_TOKEN eyJ..." }, "meta": { ... } }
# The token already includes the "UNOVA_TOKEN " prefix. Use it as-is:
BEARER=$(curl -s -X POST "$HERMES_URL/auth/getApiToken" \
  -H "Content-Type: application/json" \
  -d '{"privateKey":"'"$FACILITY_PRIVKEY"'"}' | jq -r '.data.apiToken')
# Later:  -H "Authorization: $BEARER"

# Use the Node.js or Python example to compute the signature + assetId,
# then POST the resulting JSON:
curl -X POST "$HERMES_URL/asset2/create/$ASSET_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: $BEARER" \
  -d '{
    "content": {
      "idData": {
        "createdBy": "0xfacility...",
        "timestamp": 1746460800,
        "sequenceNumber": 0
      },
      "signature": "0x..."
    }
  }'

# As with assets, compute eventId + signature in code, then POST:
curl -X POST "$HERMES_URL/event2/create/$EVENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: $BEARER" \
  -d '{
    "content": {
      "idData": {
        "assetId": "0xabc...",
        "uniqueID": "LOT-42",
        "createdBy": "0xfacility...",
        "timestamp": 1746460800,
        "accessLevel": 0,
        "dataHash": "0x..."
      },
      "data": [
        { "type": "unova.event.scan", "value": "delivered" }
      ],
      "signature": "0x..."
    },
    "groupNumbers": ["1"]
  }'

curl "$HERMES_URL/assets/LOT-42/events" \
  -H "Authorization: $BEARER"

# Forward (children + descendants):
curl -X POST "http://$NODE_IP:9876/graphdb/chain?forward=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: $BEARER" \
  -d '{"uniqueID":"LOT-42"}'

# Backward (parents + roots): same call with ?forward=false

An asset is any entity you want to track. It has a unique ID, an owner address, and a timeline of events. You define the schema — the API doesn't prescribe a shape for asset metadata.

{
  "content": {
    "idData": {
      "createdBy": "0xfacility-address...",
      "timestamp": 1746460800,
      "sequenceNumber": 0
    },
    "signature": "0x... (130-char hex)"
  }
}

{
  "data": {
    "assetId": "0x...",
    "createdBy": "0xfacility-address...",
    "createdAt": 1746460800,
    "content": { /* echoed */ }
  }
}

Look up an asset

Two identifiers exist: uniqueID is YOUR identifier (lot, container, SKU, animal tag — assigned by you when you create the asset), assetId is the on-chain content hash (returned by Hermes after creation, deterministic from signed content). Real integrations almost always look up by uniqueIDbecause that's what your ERP / scanners / labels use.

{
  "query": [
    { "field": "content.idData.createdBy", "operator": "equal", "value": "0xfacility..." }
  ],
  "paginationField": "content.idData.timestamp",
  "supplier": "0xsupplier...",
  "customer": "0xcustomer..."
}

{
  "list": ["0xpartnerA...", "0xpartnerB..."]   // optional: include partners' uniqueIDs too
}

Direct lookups (when you already have the assetId)

After /asset2/create returns an assetId, you can cache it and address the asset directly without a uniqueID search.

{
  "data": {
    "assetId": "0xabc123...",
    "createdBy": "0xowner...",
    "metadata": { "name": "Container LOT-42", "type": "shipment" },
    "createdAt": 1746360800
  }
}

Note: there is no /asset/:assetId/eventsroute. To get an asset's event history, use GET /assets/:uniqueID/events with your own uniqueID (above), or POST /asset2/v2/trace for a traceability score.

{
  "query": [
    { "field": "content.idData.createdBy", "operator": "equal", "value": "0xowner..." }
  ]
}

An event is a signed, timestamped record of something that happened to or with an asset. Events are the primary write — you submit them as your business logic executes (a scan, a sensor reading, a state transition).

{
  "content": {
    "idData": {
      "assetId": "0xabc123...",
      "uniqueID": "LOT-42",                     // ← required: your physical-asset link
      "timestamp": 1746360800,
      "accessLevel": 0,
      "createdBy": "0xfacility...",
      "dataHash": "0x..."                       // = calculateHash(data)
    },
    "data": [
      {
        "type": "unova.event.location",
        "geoJson": { "type": "Point", "coordinates": [4.40, 51.22] }
      },
      {
        "type": "unova.event.scan",
        "value": "delivered"
      }
    ],
    "signature": "0x... (130-char hex over serialized idData)"
  }
  // NOTE: send { "content": ... } only. Strict node schemas reject unknown
  // top-level fields (a legacy "groupNumbers" field is not read by current
  // nodes — omit it).
}

{
  "data": {
    "eventId": "0x...",
    "content": { /* echoed */ }
  }
}

{
  "query": [
    { "field": "content.data.type", "operator": "equal", "value": "unova.event.scan" },
    { "field": "content.idData.assetId", "operator": "equal", "value": "0xabc123..." }
  ]
}

Trace endpoints

For the simple "show me what happened" view, use GET /assets/:uniqueID/events (by your own uniqueID — see Assets). The endpoints below return traceability scores:

Genealogy graph (Atlas /graphdb)

For the full lineage walk — backward (inputs) + forward (outputs) + events — the Atlas worker exposes Neo4j-backed endpoints on a separate port:

{
  "uniqueID": "LOT-42"     // your physical-asset identifier
}

{
  "data": [{
    "success": true,
    "backwardReferenceAssets": [
      { "uniqueID": "LOT-37", "data": "...", "labels": ["ASSET"] }
    ],
    "forwardReferenceAssets": [
      { "uniqueID": "LOT-42-A", "data": "...", "labels": ["ASSET"] }
    ],
    "events": [
      { "uniqueID": "Event_42_scan", "data": "...", "labels": ["EVENT"] }
    ]
  }]
}

For simple ingestion from ERP / scanner / IoT systems — and for attaching binary files (images, PDFs, certificates) — use the high-level /unova/api endpoint. Unlike /asset2/create / /event2/create, it takes a flat JSON payload (no client-side hashing or signing — you pass the facility privateKey and Hermes signs server-side) in the multipart requestbody field, plus up to 10 attached files.

# multipart/form-data
requestbody: '{
  "typeOfRequest": "asset",
  "privateKey": "0xfacility-privkey...",
  "name": "Container LOT-42",
  "uniqueID": "LOT-42",
  "timestamp": "2026-07-06 12:00:00",
  "assetType": "shipment",
  "packagingID": "PKG-1",
  "eventType": "Commission"
}'
files[]: <binary>   # optional, up to 10 attachments

# For typeOfRequest "event" drop assetType/packagingID and pick an
# event-type eventType; uniqueID must reference an existing asset.
# Optional fields: companyIdentifier ("Warehouse", "Store", ...),
#   groupNumbers ("1,2" — comma string, groups 1-5),
#   assetsReferencedOrAdded ("LOT-37,LOT-38" — parent uniqueIDs),
#   expirationDate / ETA ("yyyy-mm-dd hh:mm:ss"), quantity, unitOfMeasure

{
  "status": "Success",
  "message": "Asset created successfully",
  "response": { /* created event(s) */ }
}

# Validation errors also come back with HTTP 200:
# { "status": "Failure", "message": "uniqueID should not be null or blank." }

Required for both types: typeOfRequest ("asset" | "event"), privateKey, name, eventType, uniqueID, timestamp. Assets additionally require assetType + packagingID, and a new (unused) uniqueID.

Valid eventType values — asset: Commission, Transformation, Aggregation; event: Inbound Transport, Outbound Transport, Observation, Other, Decommission, Disaggregation, Modification, Add Document.

Max 10 files per request. The token must hold both create_asset and create_event permissions regardless of type.

The easiest way to get events onto your node — no signing, no bearer tokens, no SDK. POST plain JSON to a launchpad webhook URL and we do the rest: look up the facility behind the token, sign the event with the facility key, and forward it to your Type-2 node's Hermes. Built for ERP exports, IoT gateways, and Zapier-style integrations.

Get the token in /data/company → Facilities → Webhook token (a 64-char hex string). The token in the URL is the auth gate — treat the full URL as a secret.

POST /api/webhook/<token>?assetId=0xabc...&uniqueID=LOT-42&type=delivery
Content-Type: application/json

{
  "temperature": 4.2,
  "carrier": "DHL"
}

# assetId / uniqueID / type may also be sent as body fields instead of
# query params. They're stripped from the body; the rest becomes the
# event data:  [{ "type": "delivery", "temperature": 4.2, "carrier": "DHL" }]
# An empty body is fine too — you'll get a bare event of the given type.

{
  "success": true,
  "eventId": "0x...",
  "uniqueID": "LOT-42",
  "assetId": "0xabc...",
  "type": "delivery"
}

# Errors: { "success": false, "error": "..." } with HTTP 400 (bad input),
# 401 (bad token), 502/503 (node unreachable / not deployed yet)

The event's accessLevel and default groupNumberscome from the webhook token's settings. Note this endpoint lives on the launchpad (nodes.unova.io), not on your node — it's a hosted convenience in front of /event2/create.

Bundles are the on-chain anchor for assets and events. Each bundle contains a batch of entities, signed by your node operator, and its hash is published to the chain. You typically don't fetch bundles directly — they're for proving data integrity to a third party.

Note: the v1 /bundle/:bundleIdendpoint is intentionally public — Atlas nodes pull bundles from each other without auth as part of the network's sheltering / challenge-resolution protocol. The data inside bundles can still be encrypted (see the accessLevel > 0 section in the user docs).

An organization is the top-level tenant on a Hermes node. It owns accounts, assets, events, and bundles. The launchpad creates one organization per Type-2 node automatically; you typically don't need to call these endpoints unless you're running a multi-org node or doing migrations.

Accounts are individual identities (wallets) within an organization. Each account has a public address, permissions, and metadata. The facility wallets you create in the launchpad register as accounts under your organization.

{
  "email": "ops@acme.example",
  "fullName": "Warehouse Antwerp",
  "accessLevel": 1,
  "permissions": ["create_asset", "create_event"]
}

For nodes that vet new organizations before granting write access, a request / approve / refuse flow is built in. The launchpad doesn't use this today (we manage tenancy in our DB), but it's available if you want pure on-node KYC.

{
  "address": "0x...",
  "title": "Acme Logistics BV",
  "email": "ops@acme.example"
}

Aggregate counts of assets/events by organization and time range. Useful for building dashboards on top of your node's data without paginating through every record.

Prometheus-compatible metrics for monitoring node health. The root /metrics endpoint is open for scraping; sub-paths require super_account auth.

Admin endpoints are gated by the super_account role — typically the node operator key. Used for backups and forcing immediate bundle publishing.

The Unova network ships with a small catalog of well-known data types that every node validates and that the trace UI knows how to render. You can mix these with your own custom type values — the standard ones just get richer rendering and validation.

Asset metadata items

Submitted as the data array of a regular event against an asset (right after the asset is created).

{
  "type": "unova.asset.identifiers",
  "identifiers": {
    "sku": ["WHEEL-12-BLK"],
    "gtin": ["1234567890123"],
    "internalRef": ["LOT-2024-W47-A"]
  }
}

{
  "type": "unova.asset.info",
  "name": "Container LOT-42",
  "description": "Pharmaceutical batch, cold chain",
  "images": ["https://example.com/img1.jpg"]
}

{
  "type": "unova.asset.location",
  "geoJson": { "type": "Point", "coordinates": [4.40, 51.22] },
  "name": "Warehouse Antwerp",
  "country": "BE",
  "city": "Antwerp"
}

Event data items

{
  "type": "unova.event.identifiers",
  "identifiers": {
    "scanCode": ["8412345678901"],
    "rfid": ["E20A1234..."]
  }
}

{
  "type": "unova.event.location",
  "geoJson": { "type": "Point", "coordinates": [4.40, 51.22] },
  "name": "Customs checkpoint Antwerp",
  "country": "BE",
  "city": "Antwerp"
}

Custom types: any typestring that doesn't start with unova. is passed through as-is (no validation). Use your own namespace, e.g. com.acme.shipment.scan, to avoid collision with future standard types.

Common modeling patterns for supply-chain customers — these are recipes built on the generic asset/event primitives, not separate APIs.

Tracking a shipment end-to-end

1. Create the asset once at origin: POST /asset2/create/:assetId
2. Immediately tag it with display info + identifiers via an event with unova.asset.info and unova.asset.identifiers data items
3. At each handoff (customs, warehouse, courier), submit an event with the asset's same uniqueID (your lot/container ID) and data items like unova.event.location + unova.event.scan
4. Use groupNumbers to share each event with the right partner group (e.g., group 1 = your own facilities, group 2 = customs broker, group 3 = end customer)
5. At delivery, look up POST /graphdb/chainby the shipment's uniqueID to render the full timeline with location history + every scan

Batch genealogy (TRANSFORMS_INTO)

For manufacturing or processing, where one batch becomes another:

• Create child assets with a custom data item that references parent uniqueIDs, e.g. { "type": "com.acme.transform", "fromAssets": ["LOT-37", "LOT-38"] }
• Atlas's graph migration creates TRANSFORMS_INTO edges automatically based on these references
• Trace genealogy walks both directions — backward to find inputs, forward to find downstream uses

Recall workflow

Flag a problem batch + propagate to anyone who received downstream assets:

1. Submit a recall event against the affected asset: { "type": "com.acme.recall", "reason": "...", "severity": "critical" }
2. Set groupNumbers to include EVERY partner group (recall events are typically broadcast)
3. Partners querying /graphdb/chain on any descendant asset will see the recall event in the genealogy

Privacy patterns

• Public (transparency): accessLevel: 0, groupNumbers: ["1"] (your own group). Anyone who shelters the bundle reads it in plaintext.
• Private to your org: accessLevel: > 0, groupNumbers: ["1"]. Hermes auto-encrypts with your org key; partners who pull the bundle see ciphertext.
• Shared with specific partners: accessLevel: > 0, groupNumbers: ["1", "5"]where 5 is a partner group. Only that group's nodes get bundle-routed and only their accounts decrypt.

HTTP status codes

Pagination

List and query endpoints use cursor pagination: pass limit (default 10, max 50 — raise the ceiling with the PAGINATION_MAXenv var on your node). Each response's top-level pagination object returns { hasNext, next, hasPrevious, previous } — pass the next / previous cursor strings back as request parameters to walk the result set. (Cursors are in pagination, not meta; meta only carries code/count/message.) There is no page/perPage numbering.

Rate limits

None by default — your node, your rules. Add a reverse proxy (nginx, Cloudflare) in front if you're serving public traffic.

Asset / event size limits

Hermes accepts payloads up to ~16 MB (Mongo BSON limit). Bundles are capped by chain block size — typically a few hundred entities per bundle.