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.

Authentication header

Authorization: UNOVA_TOKEN <your-bearer>

Tokens are per-facility. Generate one in /data/company → Facilities → API token.

Response envelope

All responses are JSON, wrapped in this shape:

{
  "meta": {
    "code": 200,
    "message": "Success"
  },
  "data": [ /* result(s) */ ],
  "resultCount": 42
}

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 metadata listing endpoints (/bundle/list, /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.

{
  "publicKey": "0x...",
  "validUntil": 1746460800,
  "signature": "0x..."
}

{
  "data": [{
    "apiToken": "UNOVA_TOKEN eyJhbGciOi..."
  }]
}

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
const res = await fetch(`${HERMES_URL}/asset2/create/${assetId}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `UNOVA_TOKEN ${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"'"}'

# 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: UNOVA_TOKEN $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: UNOVA_TOKEN $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: UNOVA_TOKEN $BEARER"

# Forward (children + descendants):
curl -X POST "http://$NODE_IP:9876/graphdb/chain?forward=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: UNOVA_TOKEN $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": { "content.idData.createdBy": "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
  }
}

{
  "query": {
    "createdBy": "0xowner..."
  },
  "sort": { "createdAt": -1 },
  "page": 0,
  "perPage": 20
}

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)"
  },
  "groupNumbers": ["1"]                          // partner groups to share with
}

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

{
  "query": {
    "content.data.type": "unova.event.scan",
    "content.idData.assetId": "0xabc123..."
  },
  "sort": { "content.idData.timestamp": -1 },
  "perPage": 20
}

Trace endpoints

Three layers of trace, increasing in richness:

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 high-throughput ingestion (warehouse scanners, IoT batches, ERP sync) and for attaching binary files (images, PDFs, certificates) to assets/events, use the unified /api endpoint. It accepts an array of asset+event payloads in a single multipart request and ties uploaded files to the entities by index.

# multipart/form-data
requestbody: '[
  {
    "type": "asset",
    "content": {
      "idData": { "createdBy": "0x...", "timestamp": 1746460800, "sequenceNumber": 0 },
      "signature": "0x..."
    }
  },
  {
    "type": "event",
    "content": {
      "idData": {
        "assetId": "0x...",
        "createdBy": "0x...",
        "timestamp": 1746460801,
        "accessLevel": 0,
        "dataHash": "0x..."
      },
      "data": [
        { "type": "unova.event.scan", "value": "received", "fileIndex": 0 }
      ],
      "signature": "0x..."
    }
  }
]'
files[]: <binary>      # uploaded file referenced by fileIndex above

{
  "data": [
    { "assetId": "0x..." },
    { "eventId": "0x..." }
  ]
}

Max 10 files per request. The token must hold both create_asset and create_event permissions even if your batch only contains one type.

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.

{
  "permissions": ["create_asset", "create_event"],
  "accessLevel": 1,
  "organization": 1
}

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 /metric 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

All list and query endpoints accept page (0-indexed) and perPage (max 50 by default, server-configurable up to 500 via the PAGINATION_MAX env var).

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.