curl --request POST \
--url https://api.usenexio.com/api/v1/engines/{engine_slug}/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": {
"request_id": "harbor-vendor-0042",
"vendor": {
"name": "Example Logistics",
"country": "US",
"annual_spend_usd": 480000,
"certifications": [
"ISO 9001"
]
}
}
}
'import requests
url = "https://api.usenexio.com/api/v1/engines/{engine_slug}/runs"
payload = { "input": {
"request_id": "harbor-vendor-0042",
"vendor": {
"name": "Example Logistics",
"country": "US",
"annual_spend_usd": 480000,
"certifications": ["ISO 9001"]
}
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: {
request_id: 'harbor-vendor-0042',
vendor: {
name: 'Example Logistics',
country: 'US',
annual_spend_usd: 480000,
certifications: ['ISO 9001']
}
}
})
};
fetch('https://api.usenexio.com/api/v1/engines/{engine_slug}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"run_id": "bcb87157-0bfc-404d-a120-7f5c9cd01037",
"status": "queued"
}Submit run
Submit a request to an engine. Returns a run ID at once; poll the run or receive a webhook for the result.
curl --request POST \
--url https://api.usenexio.com/api/v1/engines/{engine_slug}/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": {
"request_id": "harbor-vendor-0042",
"vendor": {
"name": "Example Logistics",
"country": "US",
"annual_spend_usd": 480000,
"certifications": [
"ISO 9001"
]
}
}
}
'import requests
url = "https://api.usenexio.com/api/v1/engines/{engine_slug}/runs"
payload = { "input": {
"request_id": "harbor-vendor-0042",
"vendor": {
"name": "Example Logistics",
"country": "US",
"annual_spend_usd": 480000,
"certifications": ["ISO 9001"]
}
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: {
request_id: 'harbor-vendor-0042',
vendor: {
name: 'Example Logistics',
country: 'US',
annual_spend_usd: 480000,
certifications: ['ISO 9001']
}
}
})
};
fetch('https://api.usenexio.com/api/v1/engines/{engine_slug}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"run_id": "bcb87157-0bfc-404d-a120-7f5c9cd01037",
"status": "queued"
}Behavior
- Send
Idempotency-Key(at most 255 characters) to make retries safe. The same key and request return the original run; a changed request returns409 idempotency_key_reused. Keys have no timer and last as long as the run. See Runs. - Engines of the
matchingtype need an acting principal inX-Nexio-Acting-Principal. See Authentication and access. - The shape of
inputdepends on the engine’s type and configuration. See Engine types and the engine’s Contract page in the portal.
Authorizations
Send the key as Authorization: Bearer <key>. Two kinds of key exist.
Organization keys are issued in the portal (Settings, then API keys),
each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry
no capabilities and pass every capability check, with one exception:
routes under /records, /actions, /operations,
/api/v1/engines/{id}/opportunities, /api/v1/graph and
/api/v1/catalog/documents accept an
organization key only when its environment is live, and refuse any
other with 403 scoped_key_required. Revocation takes effect within 60
seconds.
Scoped keys are issued by Nexio on request, shaped
nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one
org, one environment, a set of engines and a set of capabilities. A
malformed, unknown or revoked nxsk_ key fails with 401 and is never
retried as an organization key. Revocation takes effect on the next
request. A scoped key without a route's capability gets 403
insufficient_capability; a scoped key not bound to the engine gets 403
engine_binding_forbidden.
Key-grantable capabilities: engines:read, runs:write, runs:read,
runs:defensibility:read, runs:test, catalog:read,
catalog:documents:read, webhooks:manage, conversations:use,
conversations:export, records:read, records:opportunities:run,
actions:write, actions:read, graph:read, records:analyze.
Routes that accept organization keys only (every scoped key gets 403
insufficient_capability): environment management, engine create,
update, configuration and publish, and conversation instance
authoring. Each operation description names the capability a scoped
key needs.
Headers
Optional retry key, at most 255 characters (400 invalid_idempotency_key otherwise). Scoped to the organization,
the key's environment, the submitter (the acting principal, or the
API key when none is sent) and the key value. The same key with the
same request returns the original run with 202 and creates
nothing. The same key with a changed request returns 409 idempotency_key_reused with the original run_id in details.
Keys have no timer; the binding lasts as long as the run.
255The person in your organization the run acts for. An engine of the
matching type refuses a submission without it
(400 run_requires_acting_principal).
A nonempty body submitted_by must equal this header after trimming,
and is refused when the header is absent
(400 acting_principal_mismatch).
The acting person's verified sign-in email, sent with X-Nexio-Acting-Principal. The seat is derived from it.
Path Parameters
Engine identifier slug (e.g. default).
Body
Engine-specific submission. The fields depend on the engine type and its configuration: see Engines overview and the engine's Contract page in the portal, which renders the typed request schema.
Alternatives to rank, for the types that take them: required in
practice by comparison engines; optional on matching engines,
which source candidates from connected data. The offering rules
below apply to these engines. An offering without id or a positive
attributes.line_premium is dropped. A comparison run reports each
drop in output.warnings; a matching run does not list drops. A
kept offering must also carry provider_id, provider_name and
category, or the submission answers 400 invalid_offerings. An
unknown key on an offering or in its constraints fails with
400 invalid_request; coverage and attributes accept extra keys.
Hide child attributes
Hide child attributes
Stable line-level identifier.
Stable provider identifier.
Provider display name.
Requirement category (domain-specific). Must match a value in input.coverage_types.
Every match category the offering belongs to, when it belongs to more than one. category stays the primary value.
Provider quality rating (e.g. A+, A, B++).
Pricing tier (premium, standard, economy).
Rate the provider pays on this offering, as a decimal (e.g. 0.14 for 14%).
Product-specific detail, pricing, and qualification data.
Hide child attributes
Hide child attributes
Quoted product name.
Optional product code for the quoted product.
Program type identifier (e.g. quoted_line for standard offerings).
Set on a single offering when the provider sells this offering as part
of a multi-line package. Identifies the partner offerings
(bundles_with) and the provider's joined annual price
(joined_premium_annual). Omit on standalone offerings.
Hide child attributes
Hide child attributes
Offering IDs (from this same offerings[] array) that this
offering is sold paired with. The bundle is recognized only when
every listed offering, plus this one, appears in the same
solution.
Total annual price for the bundled group, in dollars per year. Replaces the sum of per-offering standalone annual prices when the bundle is fully present in the solution.
x >= 0Set to true if the provider will not sell any member of the
bundle standalone. Solutions that include any bundle member
without the rest are dropped.
Eligibility constraints used by the filtering stage. Pass empty arrays []
for fields that don't apply to your domain. An unknown key fails the
submission with 400 invalid_request.
Hide child attributes
Hide child attributes
States the offering may be placed in.
States where the offering is unavailable (can be empty []).
Industry classification codes that disqualify the offering. Pass [] if not applicable.
Industry classification codes the provider prefers to avoid. Pass [] if not applicable.
Minimum employee count for eligibility. Omit if not applicable.
Maximum employee count for eligibility. Omit if not applicable.
Minimum vehicle count for eligibility.
Maximum vehicle count for eligibility.
Minimum annual cost for eligibility.
Maximum annual cost for eligibility.
Offering expiration date.
Domain-specific attributes. Structure depends on your engine's configuration. Example fields:
quote_id: line quote ID from your source systemline_premium: raw price for the term (annualized by the engine viaterm_months, which defaults to 12)package_premium_annual: annual cost for the parent provider packagepackage_id: identifier tying offerings from the same provider packageam_best: AM Best ratingbroker: originating intermediary namequote_generated_at: ISO 8601 timestamp when the offering was generatedquote_expires_at: ISO 8601 timestamp when the offering expiresterm_months: term length
Pins which released engine configuration and request/response schemas this run uses.
"1.3": exact released configuration and schemas."1.x": auto-track the latest released minor of major 1 (you ride minor releases only when the engine policy permits it)."draft": mutable unpublished config, accepted only in a sandbox environment.
Bare major ("1") and three-tier semver ("1.0.0") are rejected.
Omission resolves to the latest release on engines with the default pin
policy, and fails with 500 engine_version_none_released when the engine
has no release. exact_required engines refuse an omitted pin
(engine_version_required) and an N.x pin
(engine_version_exact_required); draft from a sandbox key is
still accepted. The resolved exact version is stable for the run and is
echoed by polling and webhooks. See Versions and releases.
^(\d+\.(\d+|x)|draft)$"1.0"
Deterministic supported-version fixture. Requires a sandbox
environment, a scoped key with runs:test, and an exact N.M
engine_version present in the published registry, which today
holds only the generic fixture engine. Fixture runs make no
provider calls and count against the monthly run cap. See
Sandbox fixtures.
completed, degraded, failed An optional restatement of the acting principal. It is not an
alternative to the X-Nexio-Acting-Principal header: a nonempty
value is accepted only when the header is also sent with the same
value (after trimming). A value without the header, or with a
different header value, fails with 400 acting_principal_mismatch.
Engines of the matching type require the header.
Response
Run accepted. A new run is queued. A retry with the same Idempotency-Key and request returns the existing run with its current status.