Skip to main content
Four things carry versions: the HTTP API, webhook payloads, engines and conversation instances. A fifth, the supported contract registry, is a published record of exact engine contracts that you can verify byte for byte.

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 the X-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 numbered major.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 engine generic_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

Each entry has a path and a sha256.
2

Download the entry and hash it

The output must equal the 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.
Hash the bytes exactly as downloaded. Reformatting the JSON changes the hash.
Last modified on September 25, 2026