Engine configuration

Every engine has one draft configuration: a JSON document whose shape depends on the engine type. You edit the draft as often as you like. A run submitted through the API executes a released version, which is an immutable copy of the draft taken when you publish, unless the run pins draft from a sandbox key. This split lets you change an engine without changing what production callers get until you decide to. Three settings are the exception; see Settings read from the saved configuration. Publishing is covered on Versions and releases.

How it works

Read the draft and the type’s default with GET /api/v1/engines/{engine_slug}/config.
Check a candidate with POST /api/v1/engines/{engine_slug}/config/validate. Nothing is saved.
Save it with PUT /api/v1/engines/{engine_slug}/config. The whole draft is replaced, and the saved configuration is archived under its hash.
Publish a version when you want traffic to use it.

PUT /config ──▶ draft (hash a41c9e07d2b85f36) ──publish──▶ version 1.1 ──▶ unpinned and 1.x runs
                 └─ every saved draft archived by hash     (immutable)

Every saved configuration gets a 16-character hash. A run is stamped with the hash of the configuration it executes (engine_config_version_hash), and the worker loads that archived configuration, so a later save or publish does not change a run that already exists.

Draft and released configuration

	Draft	Released version
Changed by	`PUT /config`, the portal configuration editor, an approved improvement proposal	Never. A new publish creates a new version.
Used by	Runs that pin `engine_version: "draft"` from a sandbox key, and runs started from the portal’s Playground and Run pages (engines that require an exact version pin refuse those with `engine_version_required`)	Runs submitted through the API that do not pin `draft`
Shown on	`GET /config`, the portal Contract page	`GET /versions` (hashes and metadata)

A save does not change what an API run executes unless the run pins draft: a run that omits engine_version uses the latest released version. See Versions and releases.

Settings read from the saved configuration

Execution settings are versioned: a save changes only the draft, and a run executes the configuration of the version it resolved. Three settings are policies about what your systems receive or how fast they may call, and Nexio reads them from the engine’s current saved configuration instead of from the version:

Setting	When Nexio reads it	Effect of a save
`expose_warnings`	Each time a run is read with `GET /api/v1/runs/{run_id}`	Takes effect on the next read, for every run of the engine, including runs that finished before the save.
`notify_on_supersede`	When Nexio records a correction, in the per-run delivery setup	Governs corrections recorded after the save. In the per-correction delivery setup Nexio reads the setting from the version the run executed instead, so a save or publish changes only runs of later versions that carry it. See run.superseded.
`quotas.requests_per_minute`	On requests to the engine’s routes, cached for up to 30 seconds	Takes effect within 30 seconds of the save, without a publish.

Read the configuration

curl -s https://api.usenexio.com/api/v1/engines/vendor-review/config \
  -H "Authorization: Bearer $NEXIO_API_KEY"

import os

import requests

resp = requests.get(
    "https://api.usenexio.com/api/v1/engines/vendor-review/config",
    headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
    timeout=30,
)
body = resp.json()
print(body["engine_type"], body["config_updated_at"], sorted(body["preset"].keys()))

const resp = await fetch("https://api.usenexio.com/api/v1/engines/vendor-review/config", {
  headers: { Authorization: `Bearer ${process.env.NEXIO_API_KEY}` },
});
const body = await resp.json();
console.log(body.engine_type, body.config_updated_at, Object.keys(body.preset).sort());

Response field	Meaning
`config`	The current draft.
`config_updated_at`, `config_updated_by`	When and by whom the draft was last saved. Creating an engine sets both.
`engine_type`	The engine’s type.
`preset`	The type’s default configuration. Start from it: it carries every required key, including `egress_manifest_version` where the type needs one.
`request_schema`	The typed request contract derived from the draft, as a tree of nodes.

Validate before you save

POST /config/validate runs the same configuration checks as a save and saves nothing. A well-formed request with a config object returns 200 whether the config is valid or not; read valid. Malformed JSON, a body over 256 KiB or an absent config answers 400 invalid_request, and an unknown slug answers 404 engine_not_found. The example below is the entity_analysis preset adapted for a supplier review, with one mistake: the dimension key security appears twice.

curl -s -X POST https://api.usenexio.com/api/v1/engines/vendor-review/config/validate \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "schema_version": 1,
      "egress_manifest_version": "ee5f5d33e35b99102c9a8f9ae29ced43b3b7dfcbc59d34d8600383d267b7069f",
      "pack_key": "harbor_vendor_review",
      "pack_version": 1,
      "privacy_policy": { "mode": "default_deny" },
      "domain_key": "vendor",
      "response_type": "VENDOR_REVIEW",
      "analysis_instructions": "Review the supplier profile against each enabled dimension. Report every gap with a severity (HIGH, MEDIUM, LOW), a category, a title, a description and a recommendation.",
      "analysis_dimensions": [
        { "key": "security", "label": "Security", "enabled": true },
        { "key": "financial", "label": "Financial health", "enabled": true },
        { "key": "security", "label": "Security posture", "enabled": true }
      ],
      "profile_extraction_rules": [],
      "summary_counter_rules": [],
      "extra_result_sections": [],
      "deterministic_checks": [],
      "overlay_categories": [],
      "requirement_rules": [],
      "deterministic_gap_rules": [],
      "knowledge_overlay": []
    }
  }'

import os

import requests

config = {
    "schema_version": 1,
    "egress_manifest_version": "ee5f5d33e35b99102c9a8f9ae29ced43b3b7dfcbc59d34d8600383d267b7069f",
    "pack_key": "harbor_vendor_review",
    "pack_version": 1,
    "privacy_policy": {"mode": "default_deny"},
    "domain_key": "vendor",
    "response_type": "VENDOR_REVIEW",
    "analysis_instructions": (
        "Review the supplier profile against each enabled dimension. Report every gap with a severity "
        "(HIGH, MEDIUM, LOW), a category, a title, a description and a recommendation."
    ),
    "analysis_dimensions": [
        {"key": "security", "label": "Security", "enabled": True},
        {"key": "financial", "label": "Financial health", "enabled": True},
        {"key": "security", "label": "Security posture", "enabled": True},
    ],
    "profile_extraction_rules": [],
    "summary_counter_rules": [],
    "extra_result_sections": [],
    "deterministic_checks": [],
    "overlay_categories": [],
    "requirement_rules": [],
    "deterministic_gap_rules": [],
    "knowledge_overlay": [],
}

resp = requests.post(
    "https://api.usenexio.com/api/v1/engines/vendor-review/config/validate",
    headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
    json={"config": config},
    timeout=30,
)
result = resp.json()
for issue in result["errors"]:
    print(issue["path"], issue["message"])

const config = {
  schema_version: 1,
  egress_manifest_version: "ee5f5d33e35b99102c9a8f9ae29ced43b3b7dfcbc59d34d8600383d267b7069f",
  pack_key: "harbor_vendor_review",
  pack_version: 1,
  privacy_policy: { mode: "default_deny" },
  domain_key: "vendor",
  response_type: "VENDOR_REVIEW",
  analysis_instructions:
    "Review the supplier profile against each enabled dimension. Report every gap with a severity (HIGH, MEDIUM, LOW), a category, a title, a description and a recommendation.",
  analysis_dimensions: [
    { key: "security", label: "Security", enabled: true },
    { key: "financial", label: "Financial health", enabled: true },
    { key: "security", label: "Security posture", enabled: true },
  ],
  profile_extraction_rules: [],
  summary_counter_rules: [],
  extra_result_sections: [],
  deterministic_checks: [],
  overlay_categories: [],
  requirement_rules: [],
  deterministic_gap_rules: [],
  knowledge_overlay: [],
};

const resp = await fetch(
  "https://api.usenexio.com/api/v1/engines/vendor-review/config/validate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEXIO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ config }),
  },
);
const result = await resp.json();
for (const issue of result.errors) console.log(issue.path, issue.message);

The response names the repeated key:

{
  "valid": false,
  "errors": [
    {
      "path": "analysis_dimensions.2.key",
      "message": "Duplicate analysis dimension key \"security\""
    }
  ]
}

Each issue has a path, a message, and, for policy issues, a code (for example provider_not_approved, egress_manifest_version_required, egress_manifest_version_mismatch). Fix the value at path and validate again. A valid configuration returns {"valid": true, "errors": []}.

Save the draft

PUT /api/v1/engines/{engine_slug}/config with {"config": {...}} replaces the draft. The body must be the complete configuration; there is no partial update. A full example is in Declared-contract engines.

Status	Code	Meaning
200		Saved. The body has the same shape as `GET /config`.
400	`invalid_request`	`config` is missing, the body is not JSON, or the body is over 256 KiB.
400	`validation_error`	The configuration failed validation. `details` is the list of issues.
403	`engine_archived`	Archived engines cannot be edited. Reactivate first.
403	`insufficient_capability`	A scoped key was used. Saves need the organization key.
404	`engine_not_found`	No engine with that slug.

Keys shared across types

These keys appear on more than one engine type. The Types column lists where each is accepted; a type that does not list a key refuses it when you save. Each type adds its own keys; the preset shows them.

Key	Types	Meaning
`egress_manifest_version`	`comparison`, `entity_analysis`, `diligence`	Pins the list of approved external processors and the fields sent to them. Required when the configuration calls an external processor (a `model`, an enabled enrichment source on `entity_analysis`, an enabled grounding provider on `diligence`). When present it must equal the platform’s current value. Copy it from `preset`.
`model`	`comparison`, `entity_analysis`, `diligence`	The model the engine calls, by the ID of an entry in the platform model list. Nexio maintains the list. For `comparison` and `entity_analysis` you choose from it in the portal on the engine’s General configuration page. A declared-contract `entity_analysis` configuration (one that declares `output_contract`) takes no model. Publishing checks the chosen model’s provider against the platform’s processor list. `matching` names its models under `models` instead, with the default `platform-default`.
`request_bounds`	`comparison`, `entity_analysis`, `diligence`	Replaces the type’s request bounds field by field, up to the platform ceiling. It can raise a bound as well as lower it. See Request bounds.
`resource_limits`	`comparison`, `entity_analysis`, `diligence`	`max_provider_calls` (0, or 1 to 100) and `max_output_tokens` (0, or 1 to 1,000,000). Validated when you save. Not enforced when a run executes, whatever the value.
`expose_warnings`	every type except `matching`	When `true`, runs expose recorded warnings as `warnings` on `GET /api/v1/runs/{run_id}`. Read from the saved configuration on each read; see Settings read from the saved configuration.
`notify_on_supersede`	every type except `matching`	When `true`, the engine’s runs send `run.superseded` if a corrected result is attached. Read when the correction is recorded in the per-run delivery setup, and from the version the run executed in the per-correction setup; see Settings read from the saved configuration and Defensibility.
`quotas.requests_per_minute`	every type except `matching`	A per-engine request rate limit that replaces the organization default for routes on this engine. Read from the saved configuration; see Settings read from the saved configuration.
`privacy_policy`	every type except `diligence`	How fields with no privacy classification are treated before external calls: `default_allow` treats them as public, `default_deny` as sensitive. Fields with their own classification follow it.
`enrichment_sources`	`entity_analysis`	External lookups, registered by Nexio, that the engine calls before analysis. Unknown and duplicate kinds are refused when you save. The registered kinds are a fixed set.

Request bounds

Every run submission is measured against request bounds before a run is created. The measurement covers the submission serialized as {"input": ..., "offerings": ...} with object keys sorted. A configuration can set request_bounds on comparison, entity_analysis and diligence engines.

Bound	Default	`triage`	Highest value a configuration can set
`max_string_length` (characters in one string)	16,384	16,384	65,536
`max_array_items`	100	10,000	1,000
`max_object_fields`	100	100	1,000
`max_object_depth`	12	12	32
`max_canonical_bytes` (whole submission)	256 KiB	16 MiB	1 MiB
HTTP body	1 MiB	16 MiB	not configurable

Two engines Nexio operates have larger bounds of their own. A configuration’s request_bounds replaces the type’s profile field by field, up to the ceiling. 0 keeps the profile value. The bounds that apply are the ones in the configuration of the version the run resolves to. details.path locates the value, starting at $ for the whole submission. A violation returns request_bound_exceeded with status 413 for max_canonical_bytes and the HTTP body, and 400 for the other bounds. No run is created.

{
  "code": "request_bound_exceeded",
  "message": "The submission exceeds max_array_items: measured 140, limit 100. No run was submitted; reduce the submission or ask an operator to review this bound.",
  "details": {
    "bound": "max_array_items",
    "measured": 140,
    "actual": 140,
    "limit": 100,
    "path": "$.offerings"
  }
}

The contract page

Each comparison, entity_analysis, matching and triage engine has a Contract page in the portal (Engines, then your engine, then Contract). It renders the request and response contract for the draft configuration, with three example requests (minimal, realistic and full). Two actions build integrations from it:

Copy for agents copies integration instructions as one Markdown document, ready to paste into a coding agent’s context.
OpenAPI, then Download openapi.json, saves <slug>-openapi.json, an OpenAPI 3.1 file for this engine’s POST /api/v1/engines/{engine_slug}/runs and GET /api/v1/runs/{run_id}.

The Contract page shows the draft. Unpinned runs execute the latest released version. If you have saved changes you have not published, the page describes the next version, not the one serving traffic.

Credentials

Reading configuration accepts the organization key or a scoped key with engines:read bound to the engine. Validate and save accept only the organization key; a scoped key gets 403 insufficient_capability. See Authentication and access.

Versions and releases

Publish the draft and pin versions.

Declared-contract engines

Declare an engine’s input fields and output envelope.

Update engine config

Endpoint reference.

Validate engine config

Endpoint reference.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Engine configuration

How it works

Draft and released configuration

Settings read from the saved configuration

Read the configuration

Validate before you save

Save the draft

Keys shared across types

Request bounds

The contract page

Credentials

Versions and releases

Declared-contract engines

Update engine config

Validate engine config

​How it works

​Draft and released configuration

​Settings read from the saved configuration

​Read the configuration

​Validate before you save

​Save the draft

​Keys shared across types

​Request bounds

​The contract page

​Credentials

Versions and releases

Declared-contract engines

Update engine config

Validate engine config

How it works

Draft and released configuration

Settings read from the saved configuration

Read the configuration

Validate before you save

Save the draft

Keys shared across types

Request bounds

The contract page

Credentials