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
An engine is a configured instance of a Nexio pattern. Each engine has an engine_type that determines its behavior:
| Engine type | What it does |
|---|
placement | Ranks offerings from multiple providers into optimal solutions |
entity_analysis | Analyzes current state against requirements, finds gaps and recommendations |
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.
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.
| Engine type | Typical payload | Typical result |
|---|
placement | input plus top-level offerings | Ranked solutions with scorecards |
entity_analysis | input only, shaped by the engine contract | Requirements, gaps, and profile summary |
Solutions (detail)
A solution is a ranked package. Each includes:
offerings — the selected items in the packageprovider_count — 1 = single provider, 2+ = mixedest_cost_low / est_cost_high — annual cost rangescorecard — multi-dimension evaluationrank 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:
appetite_bucket | Emphasis |
|---|
coverage_first | Broadest coverage, strongest offerings |
cost_sensitive | Lowest cost within quality bounds |
simplicity | Fewest providers, easiest to accept |
balanced | Even weighting across all dimensions |
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 requirementspricing_competitiveness — cost relative to alternatives and budgetprovider_quality — provider ratings and reputationplacement_likelihood — likelihood of successful acceptanceoperational_simplicity — number of providers, complexity of executionrisk_alignment — fit between provider specialties and the subject’s profile
The package score is scorecard.overall_level — a weighted average based on the ranking strategy.
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
| Stage | What happens |
|---|
| INTAKE | Parse submission, infer requirements |
| FILTER | Remove offerings that fail hard constraints (region, category, capacity) |
| MATCH | Match remaining offerings to requirements by category |
| ASSEMBLE | Build candidate solutions with bundle discounts |
| EVALUATE | Score across dimensions, rank, and label |
Entity analysis
| Step | What happens |
|---|
| Infer Requirements | Generate needs from the subject’s profile and context |
| Punch Card Check | Compare against current portfolio (MET / UNMET) |
| Deterministic Checks | Rule-based gap detection |
| LLM Adequacy | AI analysis of adequacy |
| Merge & Dedupe | Combine gaps, sort by severity (HIGH → MEDIUM → LOW) |
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.degradation_reason
Populated on degraded runs (and on placement runs that completed cleanly with
no usable output). One of:
| Value | Meaning |
|---|
no_requirements | No coverage requirements parsed from input (placement) |
no_offerings | Every offering filtered out before scoring (placement) |
no_combinations | No candidate placement combinations (placement) |
input_quality | Customer-fixable input warning (MALFORMED_FIELD, MISSING_FIELD, OUT_OF_RANGE, FIELD_CONFLICT) |
llm_degraded | LLM provider failure |
enrichment_degraded | Enrichment upstream outage |
scoring_rule_failed | Engine-side scoring rule violation |
mixed | Reserved for future use; not currently emitted |
other | Non-info diagnostic that doesn’t match a known family (catchall) |
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.
