Engines overview

An engine is a configured capability you call over the API. It takes a typed input and returns a typed output as a run. Every engine has a stable slug, an engine type, a draft configuration you edit, and released versions that live traffic runs against. An organization can run several engines, one per job to be done.

Engine types and engines

An engine type is code that Nexio ships. It defines how a run executes, how a configuration is validated, the type’s default configuration, and how the engine’s request and response schemas are derived from a configuration. The types form a registry: POST /api/v1/engines accepts any registered type and refuses anything else with 400 invalid_engine_type. An engine is configuration. Creating an engine of an existing type is a call you make, with no Nexio release: you pick the type, then edit, validate and publish the configuration. A new engine type is a code change that Nexio ships in a release.

	Engine type	Engine
What it is	Runner, validation rules, default configuration and schema derivation	A slug, a configuration of one type, and its released versions
Who adds one	Nexio, in a release	You, with `POST /api/v1/engines` or in the portal
How it changes	Only in a Nexio release	You edit the draft and publish versions. The type is fixed at creation.

How it works

Create an engine of one type. It starts with that type’s default configuration and no released version.
Edit its draft configuration in the portal or with PUT /api/v1/engines/{engine_slug}/config. See Configuration.
Publish the draft as an immutable version. Unpinned runs use the latest release, unless the engine requires an exact version pin. See Versions and releases.
Submit runs with POST /api/v1/engines/{engine_slug}/runs and read results. See Runs.
Record outcomes and annotations so the engine can be measured and improved. See Outcomes and annotations and Evaluation.

Engine (slug, type, status, group_key)
 ├── Draft configuration      edited freely; runs execute it only when a sandbox run pins "draft"
 ├── Versions 1.0, 1.1, 2.0   immutable; each points at one archived configuration
 └── Runs                      each stamped with the version and configuration hash it used

Engine identity

Field	What it is	Rules
`slug`	The name you use in every engine URL, for example `/api/v1/engines/vendor-review/runs`.	3 to 50 characters, lowercase letters, digits and hyphens, starting and ending with a letter or digit. Unique in your organization. Cannot be changed.
`id`	The engine’s UUID. Returned on every engine read.	Assigned by Nexio.
`engine_type`	One of the registered types below.	Set at creation. Cannot be changed.
`label`	Display name.	1 to 100 bytes of UTF-8 text.
`description`	Free text.	Up to 500 bytes of UTF-8 text.
`status`	`active` or `archived`. An archived engine answers `403 engine_archived` to new runs, configuration saves, publishing and version reads.	Change it with `PATCH /api/v1/engines/{engine_slug}`.
`group_key`	The key of an engine group, or empty.	Up to 100 bytes of UTF-8 text.

Engine groups

An engine group is a label your organization defines (a key, a label and a description) to organize engines and conversation instances in the portal. An engine joins a group through its group_key. Groups never change what an engine can do or who can call it. You create and edit groups in the portal; the API exposes group_key on engine reads and on PATCH /api/v1/engines/{engine_slug}.

Engine types

Six types are registered today: comparison, diligence, entity_analysis, matching, opportunity and triage. The 400 invalid_engine_type message lists the registered types.

Type	What it does	You send	Acting principal
`comparison`	Ranks alternatives you send against a list of required categories, on the scoring dimensions in its configuration.	`input` and `offerings`	Not required
`matching`	Finds, qualifies and ranks candidates for a need from your connected data.	`input` describing the need; `offerings` optional	Required
`entity_analysis`	Assesses one subject against configured requirements and reports gaps with severities and recommendations. With a declared contract, returns the envelope its configuration declares.	`input` describing the subject	Not required
`diligence`	Checks a claimed event against live web sources and returns a sourced verdict.	`input` with a location, a date and the claimed event	Not required
`triage`	Classifies and ranks a whole population in one request, with deterministic checks and no model.	`input` with every candidate	Not required
`opportunity`	Runs on a schedule over a connected system of record and records the rows it finds.	No input	Not applicable

An acting principal is the person inside your organization a request acts for, sent in the X-Nexio-Acting-Principal header. It is defined on Authentication and access. Engines Nexio publishes use these same types.

`entity_analysis`

Input validation runs first, then any enrichment sources the configuration enables, then deterministic gap checks and a model review. The output carries gaps (each with severity, category, title, description, recommendation and data_sources), summary counters and diagnostics. A configuration that declares an output_contract is a declared-contract engine: a declared input schema, a declared output envelope, no model, and never degraded. See Declared-contract engines.

`diligence`

Checks a claimed event against live web sources through the configured grounding providers. input: location, date, claimed_event, optional context and request_id. Output: verdict (confirmed, not_confirmed or needs_review), summary, evidence_chain (each item with source, url, quote, supports, provider), flagged_items (machine-readable qualifiers such as no_sources or conflicting_sources), and request_echo. The verdict is needs_review when the providers find no source, when the sources conflict, or when no retrieved source supports the proposed verdict.

Declared schemas

Each engine type derives a request schema and a response schema from an engine’s configuration. They are the typed contract of the engine:

The portal’s Contract page renders them, with example requests, for the draft configuration. See Configuration.
Publishing records them with the version. Nexio compares them with the latest release to decide whether the new version is a major or a minor. See Versions and releases.
A declared-contract engine’s schemas are exactly the fields and blocks its configuration declares.

What you configure and what you call

In the portal (platform.usenexio.com, under Engines):

Create, edit, archive and delete engines, and manage engine groups.
Edit configuration section by section, including the model an engine uses.
Read the engine’s Contract page, copy it for agents, and download its OpenAPI file.
Run the playground in a sandbox, read runs with their trace, and review quality.
Publish versions, if your portal role allows publishing. Your integration publishes through the API (see Versions and releases).

Over the API:

Task	Route	Credential
List engines	`GET /api/v1/engines`	Organization key, or scoped key with `engines:read` (lists only bound engines)
Read one engine	`GET /api/v1/engines/{engine_slug}`	Organization key, or scoped key with `engines:read` bound to the engine
Create an engine	`POST /api/v1/engines`	Organization key only
Update label, description, status, group	`PATCH /api/v1/engines/{engine_slug}`	Organization key only
Read, validate, save configuration	`GET`, `POST .../config/validate`, `PUT .../config`	Read: `engines:read`. Validate and save: organization key only
List, read, publish versions	`GET .../versions`, `GET .../versions/{version}`, `POST .../versions`	Read: `engines:read`. Publish: organization key only
Submit and read runs	`POST .../runs`, `GET /api/v1/runs/{run_id}`	`runs:write` and `runs:read`

A scoped key sent to an organization-key-only route gets 403 insufficient_capability. A scoped key not bound to the engine gets 403 engine_binding_forbidden. See Authentication and access.

Configuration

Draft configuration, validation, request bounds and the Contract page.

Runs

Submit, poll, cancel and review a run.

Declared-contract engines

Declare the input and output an engine accepts and returns.

Versions and releases

Publish versions and pin runs to them.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Engines overview

Engine types and engines

How it works

Engine identity

Engine groups

Engine types

`entity_analysis`

`diligence`

Declared schemas

What you configure and what you call

Configuration

Runs

Declared-contract engines

Versions and releases

​Engine types and engines

​How it works

​Engine identity

​Engine groups

​Engine types

​entity_analysis

​diligence

​Declared schemas

​What you configure and what you call

Configuration

Runs

Declared-contract engines

Versions and releases

Engine types and engines

How it works

Engine identity

Engine groups

Engine types

`entity_analysis`

`diligence`

Declared schemas

What you configure and what you call