The HTTP API
There is one API version,v1, and every public route is under /api/v1/ except the unauthenticated GET /health and GET /robots.txt. Within v1, Nexio adds new optional response fields and new routes. Build clients that ignore response fields they do not recognize.
Requests are stricter than responses: run submissions and many write routes reject unknown fields with 400 invalid_request. Send only documented fields.
The OpenAPI description of the API is published with these docs and reports info.version: 1.0.
Webhook payloads
Every webhook carries its payload version in theX-Nexio-Webhook-Version header. A run webhook also carries it as webhook_version in the JSON body; a platform event delivered by an automation has only the header. The current version is 2026-03-22. Check it before you parse the body. See Webhooks.
Engine versions
An engine’s configuration is a mutable draft until you publish it as a release numberedmajor.minor. Releases never change. A run request can pin a release:
A run records the release it used in
engine_version (draft for a draft run) and the configuration it ran in engine_config_version_hash, so a result can be traced to the configuration that produced it. The run status response omits either field when the run has none. Some engines require an exact pin. See Versions and releases for pin policies, what counts as a breaking change, and how publishing works.
Conversation instance versions
A conversation instance is also configured as a draft and released as immutable versions, and a new turn runs the latest released version. A resumed turn keeps the version it started on. Publishing passes an evaluation gate. See Versions and publish.Supported contract registry
The registry publishes exact, immutable engine contracts: for each entry, the request schema, the response schema, and a fixture set with example requests and terminal outputs. Today it holds one engine, the fixture enginegeneric_fixture_engine (engine type entity_analysis), at versions 1.0, 1.1, 1.3 and 2.0. It is what sandbox fixtures run against, and it is the reference for contract tests of your client.
The files are served from this site:
Every file is named by the SHA-256 of its own bytes, and the file that points to it records the same hash. The registry is append-only: an entry is never edited, only added.
Verify a contract
1
Download the index and pick an entry
path and a sha256.2
Download the entry and hash it
sha256 in the index and the hash in the file name, here 5513c93b72bd6d03be71f14ca5e0bb193fac8cbdcd29eec67d00a3cd6a9c0b33.3
Verify the files the entry points to
Repeat for
request_schema, response_schema and fixtures in the entry. Each file’s SHA-256 must equal the sha256 recorded beside its path.4
Match a run to the entry
A run of that release reports
engine_version equal to the entry’s version and engine_config_version_hash equal to its config_version_hash. For version 1.0 that hash is f96a86a609a2b1ea.