Declared-contract engines

A declared-contract engine is an entity_analysis engine whose configuration declares the input fields it accepts and the output envelope it returns, and says how each output block is built. No model is called. The same input and the same enrichment lookup results give the same output, apart from request_id, which is the run ID; a lookup’s result can change between runs. Use it when a downstream system must parse every response the same way. The request and response schemas the engine publishes come straight from these declarations (see Engines overview). The example is vendor-intake, a fictional engine that Harbor Group, a fictional company, uses to record a new supplier: it takes the supplier’s details, echoes the fields its records system stores, and returns one plain next step. Prerequisites

An entity_analysis engine. The slug in this guide is vendor-intake. See Create an engine.
The organization API key in NEXIO_API_KEY. Saving configuration and publishing accept only the organization key.

How it works

Declared input. input_schema lists every accepted input field by path, with its type, whether it is required, and an optional pattern. The mode is exclusive: the declared fields are the whole input contract.
Declared output. output_contract.blocks lists every top-level output key, each with an optional JSON Schema. always_present can add response_type and request_id.
Composition. output_composition says how each block is produced: projected from the input or a source, rendered from a template, a constant, or built by a composer Nexio registers.
Validation at execution. The run is accepted with 202 and the declared input is checked when the worker starts it. A violation ends the run failed. Each composed block that declares a schema is checked against it; a mismatch also fails the run.

A declared-contract run never ends degraded. A missing upstream result is expressed inside the envelope (for example a status field), not as a run status.

The configuration

{
  "schema_version": 1,
  "pack_key": "harbor_vendor_intake",
  "pack_version": 1,
  "privacy_policy": { "mode": "default_allow" },
  "domain_key": "vendor",
  "response_type": "vendor_intake",
  "analysis_dimensions": [],
  "profile_extraction_rules": [],
  "deterministic_checks": [],
  "overlay_categories": [],
  "requirement_rules": [],
  "deterministic_gap_rules": [],
  "knowledge_overlay": [],
  "input_schema": {
    "mode": "exclusive",
    "fields": [
      { "path": "vendor", "type": "object" },
      { "path": "vendor.name", "type": "string", "required": true },
      { "path": "vendor.country", "type": "string", "required": true, "pattern": "^[A-Z]{2}$" },
      { "path": "vendor.annual_spend_usd", "type": "number" },
      { "path": "vendor.security_attestation", "type": "boolean", "required": true },
      {
        "path": "vendor.contact_email",
        "type": "string",
        "privacy": { "classification": "pii", "display": "mask", "external": "drop" }
      },
      { "path": "reference", "type": "string", "description": "Your own ID for the request." }
    ]
  },
  "output_contract": {
    "always_present": ["response_type", "request_id"],
    "blocks": [
      {
        "key": "vendor",
        "schema": {
          "type": "object",
          "required": ["name", "country", "annual_spend_usd"],
          "properties": {
            "name": { "type": "string" },
            "country": { "type": "string" },
            "annual_spend_usd": { "type": ["number", "null"] }
          }
        }
      },
      { "key": "next_step", "schema": { "type": "string" } },
      { "key": "standard", "schema": { "type": "string" } }
    ]
  },
  "output_composition": {
    "vendor": {
      "kind": "projection",
      "source": "input.vendor",
      "map": { "name": "name", "country": "country", "annual_spend_usd": "annual_spend_usd" }
    },
    "next_step": {
      "kind": "template",
      "max_length": 300,
      "cases": [
        {
          "when": { "path": "input.vendor.security_attestation", "eq": false },
          "text": "Request a current security attestation from {input.vendor.name} before onboarding."
        },
        { "else": true, "text": "{input.vendor.name} can move to contract review." }
      ]
    },
    "standard": { "kind": "constant", "value": "supplier-onboarding-2026" }
  }
}

This configuration calls no external processor, so it needs no egress_manifest_version. Enabling an enrichment source (below) makes that key required; copy its value from preset in GET /api/v1/engines/{engine_slug}/config.

Input schema rules

Rule	Detail
`mode`	`exclusive`. `additive` has no runtime yet; a configuration that declares it is refused with a validation issue whose message starts with `contract_config_not_enabled`.
`path`	Dotted lowercase snake case under `input`, for example `vendor.country`. At most 200 fields.
`type`	`string`, `integer`, `number`, `boolean`, `object` or `array`.
Closed objects	An `object` field must declare child fields, unless it sets `open: true`.
`open: true`	An opaque object passed through and stored as sent. Nothing inside it is checked, and it cannot declare children.
`required`	A required field that is missing, `null`, a blank string or an empty object fails the run. An optional field may be `null`.
`pattern`	A regular expression the whole string value must match, at most 200 bytes. String fields only.
`privacy`	Optional `{"classification": "pii", "display": "mask" or "show", "external": "drop" or "allow"}`.

Composition kinds

Kind	Fields	Produces
`projection`	`source`, `map`, optional `status_map`	An object whose fields are read from `source`, a dotted path such as `input.vendor` or `enrichment.<kind>`. A missing source field becomes an explicit `null`. With `status_map`, a `status` field is set from an enrichment source’s outcome status, and `*` is the required fallback.
`template`	`cases`, optional `max_length`	A string. Cases are tried in order; each has a `when` guard (`eq` a scalar, or `present` true or false) or is the final `else`. `{input.<path>}` and `{enrichment.<kind>.<field>}` tokens are filled in; a token with no value is left empty. `max_length` cuts the string to that many characters. With no match and no `else`, the value is `null`.
`constant`	`value`	The given JSON value.
`composer`	`name`	A whole block from a composer registered by Nexio.
`llm`, `rules`		No runtime yet for declared-contract engines. Refused with a validation issue whose message starts with `contract_config_not_enabled`.

Every declared block needs a composition entry, and no two entries may own the same part of a block. Tokens and guards must name declared input fields or enabled enrichment sources; anything else is refused when you save. A declared-contract configuration must not set model.

Enrichment sources (optional)

An enabled entry in enrichment_sources runs a lookup that Nexio registers before composition, and its result is readable at enrichment.<kind>. An input_map on the source binds the lookup’s address fields (prospect.primary_address.street, .city, .state and .zip) to declared string fields; several fields for one target are joined with single spaces. A target can be bound by only one source, and the binding feeds every enabled source.

Validate, save and publish

Save the configuration above as vendor-intake-config.json, then validate it, save it, and publish version 1.0.

BODY=$(jq -n --slurpfile c vendor-intake-config.json '{config: $c[0]}')

curl -s -X POST https://api.usenexio.com/api/v1/engines/vendor-intake/config/validate \
  -H "Authorization: Bearer $NEXIO_API_KEY" -H "Content-Type: application/json" -d "$BODY"

curl -s -X PUT https://api.usenexio.com/api/v1/engines/vendor-intake/config \
  -H "Authorization: Bearer $NEXIO_API_KEY" -H "Content-Type: application/json" -d "$BODY"

curl -s -X POST https://api.usenexio.com/api/v1/engines/vendor-intake/versions \
  -H "Authorization: Bearer $NEXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"changelog": "Vendor intake contract v1."}'

import json
import os

import requests

base = "https://api.usenexio.com/api/v1/engines/vendor-intake"
headers = {"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]}
with open("vendor-intake-config.json") as f:
    config = json.load(f)

check = requests.post(f"{base}/config/validate", headers=headers, json={"config": config}, timeout=30).json()
if not check["valid"]:
    raise SystemExit(check["errors"])

requests.put(f"{base}/config", headers=headers, json={"config": config}, timeout=30).raise_for_status()
release = requests.post(
    f"{base}/versions", headers=headers, json={"changelog": "Vendor intake contract v1."}, timeout=30
).json()
print(release["version"])

import { readFile } from "node:fs/promises";

const base = "https://api.usenexio.com/api/v1/engines/vendor-intake";
const headers = {
  Authorization: `Bearer ${process.env.NEXIO_API_KEY}`,
  "Content-Type": "application/json",
};
const config = JSON.parse(await readFile("vendor-intake-config.json", "utf8"));

const check = await (
  await fetch(`${base}/config/validate`, { method: "POST", headers, body: JSON.stringify({ config }) })
).json();
if (!check.valid) throw new Error(JSON.stringify(check.errors));

await fetch(`${base}/config`, { method: "PUT", headers, body: JSON.stringify({ config }) });
const release = await (
  await fetch(`${base}/versions`, {
    method: "POST",
    headers,
    body: JSON.stringify({ changelog: "Vendor intake contract v1." }),
  })
).json();
console.log(release.version);

The validate call returns {"valid": true, "errors": []} and the publish returns version 1.0.

Submit a supplier

curl -s -X POST https://api.usenexio.com/api/v1/engines/vendor-intake/runs \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine_version": "1.0",
    "input": {
      "vendor": {
        "name": "Example Logistics",
        "country": "US",
        "annual_spend_usd": 480000,
        "security_attestation": false,
        "contact_email": "ops@example.com"
      },
      "reference": "harbor-vendor-0107"
    }
  }'

import os

import requests

resp = requests.post(
    "https://api.usenexio.com/api/v1/engines/vendor-intake/runs",
    headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
    json={
        "engine_version": "1.0",
        "input": {
            "vendor": {
                "name": "Example Logistics",
                "country": "US",
                "annual_spend_usd": 480000,
                "security_attestation": False,
                "contact_email": "ops@example.com",
            },
            "reference": "harbor-vendor-0107",
        },
    },
    timeout=30,
)
print(resp.status_code, resp.json())

const resp = await fetch("https://api.usenexio.com/api/v1/engines/vendor-intake/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEXIO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    engine_version: "1.0",
    input: {
      vendor: {
        name: "Example Logistics",
        country: "US",
        annual_spend_usd: 480000,
        security_attestation: false,
        contact_email: "ops@example.com",
      },
      reference: "harbor-vendor-0107",
    },
  }),
});
console.log(resp.status, await resp.json());

Response 202:

{
  "run_id": "8e4b2c7a-1f5d-4a3e-9c6b-0d2f8a7e5b14",
  "status": "queued"
}

Read the envelope

Poll GET /api/v1/runs/8e4b2c7a-1f5d-4a3e-9c6b-0d2f8a7e5b14 as on Runs. The output of the completed run:

{
  "response_type": "vendor_intake",
  "request_id": "8e4b2c7a-1f5d-4a3e-9c6b-0d2f8a7e5b14",
  "vendor": {
    "annual_spend_usd": 480000,
    "country": "US",
    "name": "Example Logistics"
  },
  "next_step": "Request a current security attestation from Example Logistics before onboarding.",
  "standard": "supplier-onboarding-2026"
}

request_id is the run ID. The envelope has exactly the declared keys, every time. A supplier sent without annual_spend_usd gets "annual_spend_usd": null, because a projection writes an explicit null for a missing source field, and the block schema allows it. A supplier with "security_attestation": true gets the else case: "Example Logistics can move to contract review."

Input failures

A request that clears submission but breaks the declared input becomes a failed run. error names the first violation found:

Condition	`error`
Required field missing, `null`, blank or empty	`required input vendor.name is missing or empty`
Wrong type	`input vendor.security_attestation must be a boolean`
An undeclared parent of declared fields is not an object	`input <path> must be an object`
Pattern mismatch	`input vendor.country does not match the required format`
Undeclared field	`input vendor.tax_id is not part of this engine's request contract`

An error that names an input path is a request defect: resubmitting the same input fails the same way. For any other error on a declared-contract run, see error_details.retryable on Runs.

What to build next

Next step	Page
Receive envelopes by webhook	Webhooks
Pin and upgrade the contract	Versions and releases
Understand run statuses	Runs

Common errors

Error	Cause	Fix
Validation issue starting `contract_config_not_enabled`	`additive` mode, or an `llm` or `rules` composition.	Use `exclusive` and the four enabled kinds.
Validation issue at `model`	Declared-contract configurations take no model.	Remove `model`.
Validation issue at `egress_manifest_version` (code `egress_manifest_version_required` or `egress_manifest_version_mismatch`)	Missing or stale value with an enabled enrichment source.	Copy the value from `preset`.
Validation issue at `output_composition[...].cases[...].text`	The token names an undeclared field or a disabled source.	Declare the field, or enable the source.
Run `failed`: `composed output violates the declared contract for block ...`	A block does not match its schema.	Fix the block schema or its composition, then publish.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Declared-contract engines

How it works

The configuration

Input schema rules

Composition kinds

Enrichment sources (optional)

Input failures

What to build next

Common errors

​How it works

​The configuration

​Input schema rules

​Composition kinds

​Enrichment sources (optional)

​Input failures

​What to build next

​Common errors

How it works

The configuration

Input schema rules

Composition kinds

Enrichment sources (optional)

Input failures

What to build next

Common errors