> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Engines overview > Learn what an engine and an engine type are, which types exist, and how an engine goes from configuration to runs. An engine is a configured capability you call over the API. It takes a typed input and returns a typed output as a [run](/engines/runs). 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 1. Create an engine of one [type](#engine-types). It starts with that type's default configuration and no released version. 2. Edit its draft configuration in the portal or with `PUT /api/v1/engines/{engine_slug}/config`. See [Configuration](/engines/configuration). 3. 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](/engines/versions). 4. Submit runs with `POST /api/v1/engines/{engine_slug}/runs` and read results. See [Runs](/engines/runs). 5. Record outcomes and annotations so the engine can be measured and improved. See [Outcomes and annotations](/engines/outcomes-and-annotations) and [Evaluation](/engines/evaluation). ```text theme={null} 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](/authentication). 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](/engines/guides/contract-mode). ### `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](/engines/configuration#the-contract-page). * 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](/engines/versions#version-numbers). * 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](/engines/versions)). **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](/authentication). Draft configuration, validation, request bounds and the Contract page. Submit, poll, cancel and review a run. Declare the input and output an engine accepts and returns. Publish versions and pin runs to them.