The OpenAPI document defines the engine’s /v1 API: every route, with its fields, roles and refusals. Generate a client from it in your own stack, for a core system, a connector or a back office, and have the client follow the rules below.

​
The OpenAPI document

Every deployment serves it at GET /v1/openapi.json, with no sign-in, and each release ships it as nodeasset-v1-<version>.yaml (Downloads). Take it from the release your deployment runs, so the client matches the API it calls.

​
Generate a client

Each route’s page in the API reference shows the call in curl, then through a client that OpenAPI Generator 7.25.0 makes from the document: TypeScript, Python, and Java on the JDK’s own HTTP client. Make the same client, and the samples run as they are:
The TypeScript client is a folder of sources to import, the Python client a package, and the Java client a project for Maven or Gradle. The generator runs on Java 11 or later, and the Java samples need Java 17 or later. Each release ships the document rather than a client library, so make your client from the document of the release your deployment runs. Any generator for OpenAPI 3.0 makes a client in another language the same way, and so does an AI assistant given the document.

​
What a client must handle

  • Decimals are plain JSON numbers with every digit. Have the generated code read number fields as an exact decimal type, never a float, or send and read them as strings.
  • Every write has one answer, WriteAnswer, a single type with a state: branch on awaiting, and otherwise follow the operation by its operationId.
  • A refusal’s body is application/problem+json: branch on the slug that ends its type and on its check, and show its detail and recovery.
  • Each operation’s roles (x-roles), its four-eyes rule (x-four-eyes) and the webhook bodies (x-webhooks) are vendor extensions most generators skip; read them from the document.
  • Send an Idempotency-Key with every write, built from your own id for the action, so a retry after a timeout or a lost answer is the same request (idempotency and retries).
  • Follow each operation to its end: read GET /v1/operations/{operationId} until its state is succeeded or failed. A failed one carries its problem.
  • Page a list by sending each page’s next back as after, until next is null; the event feed’s and the audit log’s next is never null, so poll them with the last one (pagination).
  • A service client signs each request with the HMAC key the engine holds for it, beside its bearer (request signing).
  • Verify each webhook delivery’s signature and timestamp before you act on it, and drop one you have already handled (verify a delivery).

​
With an AI assistant

Give the assistant the OpenAPI document and the rules on this page. Then have it test its request signing against the example in How the API works, and its webhook check against the one in Events and webhooks, before the client calls your deployment. Related: How the API works · Events and webhooks · Downloads