> ## 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.

# Introduction

> Agentic infrastructure for placement, entity analysis, and beyond.

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](/api-reference/webhooks/overview).

## Quickstart

You need an API key from [Settings → API Keys](https://platform.usenexio.com/settings/api-keys?create=1\&environment=test). Keys are shown only once. `nx_test_` = sandbox, `nx_live_` = production.

### 1. Submit a run

<Note>
  This example uses a personal-lines insurance engine. Your engine's input schema depends on its configuration: see the [Headless Engine Setup](/guides/headless-engine-setup) guide.
</Note>

```bash theme={null}
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`:

```json theme={null}
{ "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.

```json theme={null}
{
  "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](/api-reference/engines/submit-run) and [Get Run Status](/api-reference/engines/get-run-status) API reference for full request/response schemas.

## Next steps

<CardGroup cols={2}>
  <Card title="Key Concepts" icon="book" href="/concepts">
    Runs, offerings, solutions, scorecards, engine types.
  </Card>

  <Card title="Integration Guide" icon="list-tree" href="/guides/integration">
    Offering structure, multi-provider input, failure cases.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full endpoint documentation with typed schemas.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key types, creation, and security.
  </Card>
</CardGroup>