Introduction

Nexio is an agentic infrastructure API with two current engine families:

Placement engines: send offerings from multiple providers and get ranked solutions with multi-dimension scorecards
Entity analysis engines: send a current portfolio or entity state and get gap analysis with severity-ranked recommendations

More engine types are planned. Every run is async: submit via POST /api/v1/engines/{engine_slug}/runs, retrieve results via GET /api/v1/runs/{run_id} or webhooks.

Quickstart

You need an API key from Settings → API Keys. Keys are shown only once. nx_test_ = sandbox, nx_live_ = production.

1. Submit a run

This example uses a personal-lines insurance engine. Your engine’s input schema depends on its configuration: see the Headless Engine Setup guide.

curl -X POST https://api.usenexio.com/api/v1/engines/default/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nx_test_YOUR_KEY" \
  -d '{
    "input": {
      "address": { "state": "NY", "zip_code": "11231" },
      "coverage_types": ["home", "auto", "umbrella"],
      "appetite_bucket": "balanced",
      "vehicles": 1,
      "premium": 3557.23
    },
    "offerings": [
      {
        "id": "quote_line_carrier_a_home_001",
        "provider_id": "prov_carrier_a",
        "provider_name": "Carrier A",
        "category": "home",
        "quality_rating": "A+",
        "pricing_tier": "premium",
        "commission": 0.14,
        "constraints": { "excluded_states": [], "prohibited_naics": [], "avoided_naics": [] },
        "coverage": { "product_name": "Premier Homeowners", "program_type": "quoted_line" },
        "attributes": { "quote_id": "qt_carrier_a_home_001", "line_premium_annual": 6120, "package_premium_annual": 12840 }
      },
      {
        "id": "quote_line_carrier_a_auto_001",
        "provider_id": "prov_carrier_a",
        "provider_name": "Carrier A",
        "category": "auto",
        "quality_rating": "A+",
        "pricing_tier": "standard",
        "commission": 0.13,
        "constraints": { "excluded_states": [], "prohibited_naics": [], "avoided_naics": [] },
        "coverage": { "product_name": "Premier Auto", "program_type": "quoted_line" },
        "attributes": { "quote_id": "qt_carrier_a_auto_001", "line_premium_annual": 4980, "package_premium_annual": 12840 }
      },
      {
        "id": "quote_line_carrier_a_umbrella_001",
        "provider_id": "prov_carrier_a",
        "provider_name": "Carrier A",
        "category": "umbrella",
        "quality_rating": "A+",
        "pricing_tier": "standard",
        "commission": 0.12,
        "constraints": { "excluded_states": [], "prohibited_naics": [], "avoided_naics": [] },
        "coverage": { "product_name": "Personal Umbrella", "program_type": "quoted_line" },
        "attributes": { "quote_id": "qt_carrier_a_umb_001", "line_premium_annual": 1740, "package_premium_annual": 12840 }
      }
    ]
  }'

Returns 202 Accepted:

{ "run_id": "2aa8b3f1-9d11-4f4a-b2f2-6c2e3d96fdf0", "status": "queued" }

2. Poll for results

GET /api/v1/runs/{run_id} until status is completed or failed. Start at 2s, backoff 1.5x, cap 30s.

{
  "run_id": "2aa8b3f1-9d11-4f4a-b2f2-6c2e3d96fdf0",
  "status": "completed",
  "environment": "test",
  "output": {
    "solutions_count": 7,
    "top_label": "recommended",
    "top_score": 3.85,
    "appetite_bucket": "balanced"
  },
  "solutions": [
    {
      "rank": 1,
      "cluster_label": "recommended",
      "requirements_met": ["lob_auto", "lob_home", "lob_umbrella"],
      "provider_count": 1,
      "est_cost_low": 11985,
      "est_cost_high": 11985,
      "offerings": [
        { "id": "quote_line_carrier_c_auto_001", "provider_name": "Carrier C", "category": "auto" },
        { "id": "quote_line_carrier_c_home_001", "provider_name": "Carrier C", "category": "home" },
        { "id": "quote_line_carrier_c_umbrella_001", "provider_name": "Carrier C", "category": "umbrella" }
      ],
      "scorecard": { "overall_level": 3.85 }
    }
  ]
}

3. Read the results

solutions[0].cluster_label: solution label (recommended, best_value, etc.)
solutions[0].scorecard.overall_level: raw weighted level; use rank for ordering
solutions[0].est_cost_low / est_cost_high: annual cost range
solutions[0].offerings[*].provider_name: provider per line

See the Submit Run and Get Run Status API reference for full request/response schemas.

Next steps

Key Concepts

Runs, offerings, solutions, scorecards, engine types.

Integration Guide

Offering structure, multi-provider input, failure cases.

API Reference

Full endpoint documentation with typed schemas.

Authentication

API key types, creation, and security.

Start Here

Guides

API Reference

Introduction

Quickstart

1. Submit a run

2. Poll for results

3. Read the results

Next steps

Key Concepts

Integration Guide

API Reference

Authentication

​Quickstart

​1. Submit a run

​2. Poll for results

​3. Read the results

​Next steps

Key Concepts

Integration Guide

API Reference

Authentication

Quickstart

1. Submit a run

2. Poll for results

3. Read the results

Next steps