# Unova node API — full reference for AI assistants

This is the complete, canonical machine-readable reference for integrating with an Unova Type-2 / Type-4 node. It is generated against the actual node server behavior. If anything here conflicts with code you generate from prior knowledge, THIS document wins.

## Recommended integration path

Prefer the official tooling over raw HTTP — it eliminates the classic integration failures (signing serialization, token semantics, address casing, query format, wrong port for trace, envelope exceptions):

- **TypeScript/JavaScript**: `npm install @unovalabs/client` → `new UnovaClient({ nodeUrl, auth: { facilityPrivateKey } })` → `assets.create()`, `events.create()`, `assets.eventsByUniqueId()`, `trace()`.
- **AI/agent tooling**: `@unovalabs/mcp` — an MCP server exposing these APIs as tools. Env: `UNOVA_NODE_URL`, `UNOVA_FACILITY_PRIVATE_KEY` (or read-only `UNOVA_API_TOKEN`).
- Raw HTTP works too — everything below documents it.

## Base URLs — one node, two services

Every builder talks to THEIR OWN node (no shared API host):

- **Hermes REST API** — `http://<node-ip>` (port 80). All endpoint groups below unless stated otherwise.
- **Atlas trace service** — `http://<node-ip>:9876`. Only the `/graphdb/*` endpoints.

Plain HTTP by default; put your own TLS proxy in front for public traffic.

## Authentication

Header: `Authorization: UNOVA_TOKEN <jwt>`

- Tokens are per-facility. Account holders generate them at https://nodes.unova.io/data/company (Facilities → API token) or by exchanging the facility's private key:

POST /auth/getApiToken           (public, no auth)
  Request:  { "privateKey": "0x..." }
  Response: { "data": { "apiToken": "UNOVA_TOKEN eyJ..." }, "meta": { "code": 200 } }

- CRITICAL: `data.apiToken` already starts with `UNOVA_TOKEN ` — use it as the entire Authorization header value. Do not prepend anything.
- Tokens are valid for ~5 days. IMPORTANT expiry semantics: **Hermes reports a missing or EXPIRED token as HTTP 403** (the Atlas trace service uses 401). Treat 403 as "refresh the token and retry once" before concluding it's a permissions problem.
- Permissions carried by the token: `create_asset`, `create_event`, `super_account` (admin). A facility token typically has the first two. 401 from Hermes usually means a create's signature didn't recover to the token's account — sign with the same facility key the token was issued for.
- Asset/event reads and bundle LISTING require a valid token. Exceptions that need no token: `GET /bundle/:bundleId` (deliberately public for bundle sheltering) and `GET /nodeinfo`.
- Events with `content.idData.accessLevel` above the caller's level are hidden from reads; `accessLevel > 0` data is encrypted for the writing organization before bundling.

## Response envelope

Most responses:

{
  "data":  ...,                 // array for lists, object for single lookups
  "meta":  { "code": 200, "count": 42, "message": "..." },   // count on lists; message only sometimes
  "pagination": { "hasNext": true, "next": "...", "hasPrevious": false, "previous": "..." }   // paged endpoints only
}

KNOWN EXCEPTIONS (memorize these — they break naive envelope parsing):
- `GET /assets/:uniqueID/events` (the primary lookup!) returns `{ "results": [...], "resultCount": n }` — no data/meta wrapper.
- `POST /asset2/v2/assetSearch` wraps a paged object INSIDE data: `{ "data": { "results": [...], "hasNext": true, "next": "..." }, "meta": ... }` — the item list is `data.results` and cursors are inside `data`, not in a top-level `pagination`.
- `GET /bundle/:bundleId` returns the raw bundle JSON with no envelope at all.
- Everything else follows the standard envelope; cursors live in `pagination` (never in `meta`).

## Queries — the clause-array format (NOT raw Mongo)

Every queryable endpoint (`/asset2/query`, `/asset2/v2/assetSearch`, `/event2/query`, `/event2/search`, `/event2/v2/count`, `/bundle/query`, `/asset2/v2/trace`, the `user/*` convenience endpoints) takes a body of the form:

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

- `query` is an ARRAY of clauses. Raw Mongo-style filter objects (e.g. `{ "content.idData.createdBy": { "$eq": ... } }`) are REJECTED ("bad operators found in query", often surfaced as HTTP 500).
- Operators: `equal`, `not-equal`, `greater-than`, `greater-than-equal`, `less-than`, `less-than-equal`, `inrange`, `startsWith`, `contains` (contains = case-insensitive regex).
- There is no `sort` key — the server ignores/rejects it.
- Addresses in values must be lowercase.

Pagination: pass `limit` (default 10, max 50) and cursor strings `next`/`previous` as URL query parameters on these POST query endpoints. AVOID the bare `GET /asset2/list`-style endpoints for pagination: they reinterpret EVERY unknown query parameter as a `content.idData.*` filter (so `?limit=20` silently becomes the filter `content.idData.limit=20` → empty results). Prefer the POST query endpoints.

## Signing scheme (writes)

Every create (asset or event) is a signed payload. Use the SDK if at all possible; the raw scheme:

1. Build `idData` (assets) or `idData` + `data` (events).
2. Serialize deterministically: object keys sorted alphabetically, arrays keep order, strings wrapped in double quotes (NO escaping is applied — avoid embedded quotes in values), numbers/booleans via String(), NO whitespace.

   serialize(x):
     object → "{" + sortedKeys.map(k => '"'+k+'":' + serialize(x[k])).join(",") + "}"
     array  → "[" + x.map(serialize).join(",") + "]"
     string → '"' + x + '"'
     other  → String(x)

3. Sign the serialized string with the facility private key, EIP-191 personal_sign style (`web3.eth.accounts.sign` / viem `account.signMessage`). 65-byte hex signature.
4. The content hash = EIP-191 hash (`hashMessage`) of the serialized CONTENT object — `{idData, signature}` for assets, `{idData, data, signature}` for events. This hash IS the `:assetId` / `:eventId` in the URL. Hermes recomputes it and rejects mismatches.

Pitfalls that break hand-rolled signing:
- NEVER put `null` anywhere in a signed payload — the server's serializer crashes on null (it treats null as an object), so a signed null can never verify. Omit the field instead.
- Strip `undefined` values BEFORE hashing — JSON drops them in transit, so hashing them locally produces a hash the server can never reproduce.
- Use a library for the EIP-191 hash (`hashMessage`) — never hand-assemble the `"\x19Ethereum Signed Message:\n" + byteLength` prefix.
- `createdBy` must be the LOWERCASED address.
- `dataHash` in an event's idData = hash of the `data` array alone.
- No whitespace anywhere in the serialization; keys sorted at EVERY nesting level.

## Assets

An asset is any trackable entity (container, device, parcel, certificate, VIN...). You define the metadata schema.

POST /asset2/create/:assetId          (auth: create_asset)
  Body: { "content": { "idData": { "createdBy": "0x...", "timestamp": 1746460800, "sequenceNumber": 0 }, "signature": "0x..." } }
  :assetId = content hash (see Signing). Response echoes the stored asset.

GET  /assets/:uniqueID/events         (auth) — PRIMARY LOOKUP: all events for YOUR identifier (lot, container, SKU). RESPONSE IS `{results, resultCount}` (no envelope — see Response envelope exceptions). The uniqueID is yours, assigned on events; assetId is the on-chain hash.
GET  /asset2/info/:assetId            (auth) — one asset by on-chain hash
GET  /asset2/exists/:assetId          (auth) — NOTE: on current builds a missing asset surfaces as HTTP 500, not 404 — treat both as "does not exist"
POST /asset2/v2/assetSearch           (auth) — clause-array query + cursor pagination (cursors INSIDE data — see envelope exceptions)
  Body: { "query": [ { "field": "content.idData.createdBy", "operator": "equal", "value": "0x..." } ], "paginationField": "content.idData.timestamp", "supplier": "0x...", "customer": "0x..." }
  (paginationField / supplier / customer optional)
POST /asset2/query                    (auth) — generic clause-array query, standard envelope
GET  /asset2/v2/list/:publicKey       (auth) — assets created by a wallet (address lowercase)
POST /asset2/v2/list/all/:publicKey   (auth) — same, including sub-accounts
POST /asset2/v2/user/uniqueIds        (auth) — uniqueIDs the queried account created. Body MUST include a clause-array query naming the account: { "query": [ { "field": "events.content.idData.createdBy", "operator": "equal", "value": "0x..." } ], "list": ["0xpartner..."] } (list optional, includes partners)
POST /asset2/v2/user/assetTypes       (auth) — distinct asset types; same required query pattern with field "content.idData.createdBy"
POST /asset2/v2/user/eventTypes       (auth) — distinct event types; same required query pattern with field "events.content.idData.createdBy"
DELETE /asset2/v2/remove/:uniqueId    (auth)
POST /asset2/v2/trace                 (auth) — traceability score for an ACCOUNT. Body: { "query": [ { "field": "content.idData.createdBy", "operator": "equal", "value": "0x..." } ] }; query params ?inbound=true / ?outbound=true select direction. Response data: { "inboundTrace": n, "outboundTrace": n, "totalTrace": n }

## Events

An event is anything that happened to an asset — signed and timestamped.

POST /event2/create/:eventId          (auth: create_event)
  Body:
  {
    "content": {
      "idData": {
        "assetId": "0x...",              // the asset's on-chain hash
        "uniqueID": "LOT-42",            // YOUR physical identifier — drives the trace graph
        "timestamp": 1746460800,
        "accessLevel": 0,                // 0 plaintext; >0 encrypted for your org
        "createdBy": "0x...",            // lowercased facility address
        "dataHash": "0x..."              // = hash(data array)
      },
      "data": [
        { "type": "unova.event.location", "geoJson": { "type": "Point", "coordinates": [4.40, 51.22] } },
        { "type": "unova.event.scan", "value": "delivered" }
      ],
      "signature": "0x..."
    }
  }
  :eventId = content hash. `data` items each need at least a `type`.
  IMPORTANT: send `{ "content": ... }` ONLY — strict node schemas reject unknown top-level fields (`additionalProperties: false`). A `groupNumbers` top-level field exists in some older examples; current controllers do not read it — do not send it unless you know your node accepts it.

GET  /event2/info/:eventId            (auth)
POST /event2/query                    (auth) — clause-array query, standard envelope + cursors
GET  /event2/list                     (auth) — avoid for pagination (see Queries section warning)
GET  /event2/lookup/types             (auth)
POST /event2/search                   (auth) — clause-array query
POST /event2/v2/count                 (auth) — count matching events (clause-array query)
GET  /event2/v2/list/:publicKey       (auth)
POST /event2/v2/list/all/:publicKey   (auth)

## Trace (Atlas service, port 9876)

POST http://<node-ip>:9876/graphdb/chain?forward=true    (auth)
  Body: { "uniqueID": "LOT-42" }
  forward=true  → children/descendants (where did it go)
  forward=false → parents/origins (where did it come from)
  Response data[0]: the chain node with `events`, `forwardReferenceAssets`, and linked assets.

Notes:
- This is the ATLAS port (9876), not Hermes (80). 404s here usually mean you called the wrong port.
- Atlas reports an expired token as 401 (unlike Hermes's 403).
- Newly created events appear in trace results after the next graph-sync cycle — an empty result immediately after a write is normal; retry after a minute.
- POST /graphdb/routes (auth) returns the traversal routes for a uniqueID.

## Bundles

Bundles are the on-chain proof batches your node publishes (cadence set by bundle settings: interval + minimum items).

GET  /bundle/:bundleId                (PUBLIC — raw bundle JSON, no envelope; other nodes pull bundles for sheltering/challenges)
GET  /bundle/                         (auth) — list, paginated
POST /bundle/query                    (auth) — clause-array query
GET  /bundle2/info/:bundleId          (auth)
GET  /bundle2/list                    (auth)
POST /bundle2/query                   (auth)

## Accounts & organizations (multi-tenant)

POST /account2/create/:address        (auth)
GET  /account2/info/:publicKey        (auth)
GET  /account2/list                   (auth)
POST /account2/modify/:address        (auth)
GET  /account/:address/trace          (auth)
Organization onboarding/KYC flows are driven from the launchpad UI; see /api-docs "Organizations" for request shapes.

## Operations

GET  /nodeinfo                        (public, no token) — node version, network, organization
GET  /metrics                         (public) — Prometheus-style basics
GET  /metrics/balance, /metrics/bundle, /metrics/uon   (super_account token required)
GET  /analytics/:collection/count     (auth) — plus per-organization and time-window aggregate variants
Admin (super_account token only):
GET  /admin/pushbundle                — force an immediate bundle push
GET  /admin/getconfig                 — org/account backup
POST /admin/restoreconfig             — restore backup

## Webhook ingestion (no-code)

POST plain JSON to a launchpad-issued webhook URL (created per facility in the launchpad UI) and the platform signs + writes the asset/event for you — no signing code needed. Configure at https://nodes.unova.io.

## Errors & limits

- 200 success · 400 validation, including malformed create bodies and schema rejections (read `meta.message`) · **401 = signature/authentication problem** (a create signed with a different key than the token's account; on Atlas: expired token) · **403 = missing or EXPIRED token, or missing permission** — refresh the token and retry once before assuming permissions · 404 not found · 500 server-side error — NOTE the server wraps many request errors (including malformed clause queries and the exists-check miss) as 500, so read the message before blaming the node.
- Rate limits: none by default (your node). Payloads up to ~16 MB; bundles hold a few hundred entities.

## Known pitfalls (checklist for generated code)

1. Authorization value is the token VERBATIM — it already starts with `UNOVA_TOKEN `.
2. Tokens last ~5 days; expiry arrives as **403 on Hermes** (401 on Atlas) — refresh and retry once on 403.
3. Queries are ARRAYS of `{field, operator, value}` clauses — never raw Mongo objects, never `sort`.
4. Addresses lowercase, everywhere (createdBy, list/:publicKey, query values).
5. `uniqueID` (yours, human-assigned) vs `assetId`/`eventId` (content hashes). Trace and ERP lookups use uniqueID.
6. Trace = port 9876; everything else = port 80.
7. Envelope exceptions: `/assets/:uniqueID/events` → `{results, resultCount}`; `assetSearch` cursors inside `data`; `bundle/:bundleId` raw.
8. The URL id on creates MUST equal the content hash — never invent it.
9. Serialization: sorted keys, no whitespace, at every nesting level; NEVER null; strip undefined before hashing.
10. Event create body is `{ "content": ... }` only — no extra top-level fields.

## Access

Working credentials require an Unova account + a running node: https://nodes.unova.io. Questions / undocumented endpoints: tech@unova.io