Skip to main content

​
Engines

An engine is a configured instance of a Nexio pattern. Each engine has an engine_type that determines its behavior: More engine types are planned. See the Headless Engine Setup guide for creating and configuring engines via API.

​
Runs

A run is an async job submitted to POST /api/v1/engines/{engine_slug}/runs. Each run gets a run_id and is processed through the engine’s pipeline. Poll GET /api/v1/runs/{run_id} for results. Statuses are queued, processing, completed, degraded, failed, and cancelled. The last four are terminal: poll until one of them, then stop.

​
Output phase

A response that carries output or solutions also carries output_phase, which states which answer they are. It is a first-class field so that no consumer has to infer the distinction from a status and timestamp combination. A placement run finishes all of its deterministic scoring before it calls the model, and it persists that answer at the boundary. The run stamps completed_deterministic_at at that moment and serves a draft from then on, while status is still processing. A caller that wants a result sooner than the model leg allows can render the draft. A draft is a real answer over part of the decision, not a preview. Its ranks, cluster labels, and overall_level values are real, but they are computed over the deterministic scoring dimensions only, with the weights renormalized over them. The model-scored dimensions are absent from a draft scorecard rather than empty. They carry real weight, so the final answer can reorder the shortlist.
Never treat a draft as the final answer, and never stop polling on one. Keep polling until status is completed, degraded, failed, or cancelled; label anything rendered from a draft as provisional, and replace it when the final response arrives.
A failed or cancelled run carries no output, no solutions, and no output_phase, even when it reached the boundary before it failed. Only the placement engine has a deterministic boundary today; runs on engines that have none omit both fields until they reach a terminal status. Webhook payloads never carry either field, because every webhook event type is terminal. Full field semantics live on the Get Run Status page.

​
Input

input is the subject’s profile and run context. What goes in input depends on your engine’s configuration and domain.
Field names like coverage_types and premium reflect the current API contract. Your engine’s configuration determines which input fields are relevant. Open the per-engine Contract page on platform.usenexio.com (Copy-for-agents button) to see the exact typed request schema for your engine.

​
Offerings

offerings is the array of provider offerings Nexio evaluates in a placement engine. Each offering represents one provider’s entry for one requirement category. If you have 3 providers each offering 3 categories, that’s 9 offerings.

​
Solutions

Nexio assembles offerings into ranked solutions: complete packages that satisfy the stated requirements. Solutions may combine offerings from a single provider or mix providers, whichever combinations score best. Each solution has a rank (1 = best) and a cluster_label that categorizes it: recommended, best_value, best_coverage, or simplest.

​
Engine Types

The engine you call determines the contract and the pipeline that runs. Open the per-engine Contract page on platform.usenexio.com (Copy-for-agents button) when you need the exact field-level typed schema for a specific engine.

​
Solutions (detail)

A solution is a ranked package. Each includes:
  • offerings: the selected items in the package
  • provider_count: 1 = single provider, 2+ = mixed
  • est_cost_low / est_cost_high: annual cost range
  • scorecard: multi-dimension evaluation
  • rank and cluster_label
Provider identity is on solutions[*].offerings[*].provider_name, not on the solution root.

​
Ranking strategy

appetite_bucket controls how Nexio weights the scorecard dimensions when ranking solutions. Set it in input to express the priority: When omitted, Nexio infers it from submission signals. The top-ranked solution’s label is returned in output.top_label and on each solution as cluster_label. Labels like recommended, best_value, best_coverage, and simplest reflect where each solution excels: they’re the output side of the ranking strategy.

​
Scorecards

Six dimensions, each rated L1–L4 (lower is better):
  • coverage_completeness: how completely the solution addresses requirements
  • pricing_competitiveness: cost relative to alternatives and budget
  • provider_quality: provider ratings and reputation
  • placement_likelihood: likelihood of successful acceptance
  • operational_simplicity: number of providers, complexity of execution
  • risk_alignment: fit between provider specialties and the subject’s profile
The package score is scorecard.overall_level, a raw weighted level based on the ranking strategy. Use the emitted solution rank, not the raw weighted level, as the ordering contract. A dimension the run could not score is absent from the scorecard, not present with an empty value, and overall_level is the weighted level over the dimensions that are present. On a deterministic_draft scorecard every model-scored dimension is absent for that reason. Which dimensions are model-scored is set per engine by scoring_dimensions[*].method in the released engine configuration. Where the configuration also declares an assessed-weight floor, each scorecard carries assessed_weight_fraction: the share of the decision weight that scorecard covers.
Dimension names like coverage_completeness reflect the default engine configuration. Custom engines can define their own scoring dimensions via the Update Config endpoint.

​
The pipeline

​
Placement

​
Entity analysis

Returns gaps with severity, recommendations, profile summary, and flags. See the Get Run Status response schema for full field details.

​
Output fields you may see

These fields appear on output and on individual gap entries depending on engine configuration. Integrators should treat them as additive: absent on engines that don’t enable them, present when the engine does.

​
output.output_phase

The stored output block’s own copy of the top-level output_phase, carrying the same two values. It is there so a consumer that reads the run’s output object on its own, rather than the whole response, can still tell a draft from a final answer. Written on placement-engine output blocks.

​
output.degradation_reason

Populated on degraded runs (and on placement runs that completed cleanly with no usable output). One of: Omitted on healthy completions. Route on this field instead of parsing free-text from output.diagnostic or walking warning_details[]. When multiple non-info diagnostics are present, strict precedence picks the most actionable single reason: scoring_rule_failed > input_quality > llm_degraded > enrichment_degraded > other.

​
data_source_labels (entity analysis)

Per-gap sibling to data_sources[]. Index-aligned broker-readable labels for each entry in data_sources. data_sources keeps its audit-trail role (raw input paths); data_source_labels adds a display string per path so broker UIs can render evidence captions without maintaining their own mapping. Unmatched paths emit empty strings at the corresponding index: fall back to the raw path. Omitted when the engine has no data_source_labels map configured.

​
Rate limits

Rate limits are enforced on the public API. 429 Too Many Requests includes a Retry-After header. Contact support@usenexio.com for higher limits. Run submission supports an optional Idempotency-Key. Retrying the same submission attaches to the existing run, while reusing the key for changed execution input returns 409 idempotency_key_reused. Keys are actor- and environment-scoped and live with the run row.