Skip to main content
This guide walks through the full engine lifecycle using only the API — no dashboard required. For request/response schemas, see the Engine Management API reference.

​
Flow

​
Step 1: Create an engine

Choose an engine_type based on your use case: placement for ranking carrier quote packages, or entity_analysis for coverage gap analysis. 
curl -X POST https://api.usenexio.com/api/v1/engines \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "auto-home-pl",
    "label": "Personal Lines Auto + Home",
    "description": "Quote matching for bundled home and auto policies.",
    "engine_type": "placement"
  }'
The engine is created with a default configuration and active status. The slug is used in all subsequent endpoint URLs.

​
Step 2: Build your config

The config structure depends on engine_type. Retrieve the current config to use the preset template as a starting point: 
# Get the current config (includes preset template)
curl https://api.usenexio.com/api/v1/engines/auto-home-pl/config \
  -H "Authorization: Bearer $NEXIO_API_KEY"
The preset field in the config response provides the default template for your engine type. Use it as a starting point and modify the fields you need.

​
Step 3: Validate the configuration

Before saving, dry-run your config through validation. The validate endpoint always returns 200 OK — check the valid field: 
curl -X POST https://api.usenexio.com/api/v1/engines/auto-home-pl/config/validate \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"schema_version": 1, "pack_key": "insurance-personal-lines", "pack_version": 1, "scoring_dimensions": [{"key": "coverage_completeness", "label": "Coverage Completeness", "method": "deterministic", "enabled": true}, {"key": "pricing_competitiveness", "label": "Pricing Competitiveness", "method": "deterministic", "enabled": true}], "appetite_weight_profiles": [{"bucket": "balanced", "label": "Balanced", "weights": {"coverage_completeness": 0.5, "pricing_competitiveness": 0.5}}], "default_appetite_bucket": "balanced"}}'
A valid response: 
{ "valid": true, "errors": [] }
An invalid response: 
{
  "valid": false,
  "errors": [
    { "path": "scoring_dimensions", "message": "at least one scoring dimension is required" }
  ]
}

​
Step 4: Save the configuration

Once validation passes, save the config with a full replacement PUT: 
curl -X PUT https://api.usenexio.com/api/v1/engines/auto-home-pl/config \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "schema_version": 1,
      "pack_key": "insurance-personal-lines",
      "pack_version": 1,
      "scoring_dimensions": [
        { "key": "coverage_completeness", "label": "Coverage Completeness", "method": "deterministic", "enabled": true },
        { "key": "pricing_competitiveness", "label": "Pricing Competitiveness", "method": "deterministic", "enabled": true }
      ],
      "appetite_weight_profiles": [
        {
          "bucket": "balanced",
          "label": "Balanced",
          "weights": { "coverage_completeness": 0.5, "pricing_competitiveness": 0.5 }
        }
      ],
      "default_appetite_bucket": "balanced"
    }
  }'

​
Step 5: Get the integration contract

The contract endpoint generates a Markdown document describing the exact request format your engine expects, based on its current config: 
curl https://api.usenexio.com/api/v1/engines/auto-home-pl/contract \
  -H "Authorization: Bearer $NEXIO_API_KEY"
The markdown field contains scoring dimensions, weight profiles, viability rules, example request/response payloads, and polling instructions — everything a downstream consumer or AI agent needs to build a correct submission.

​
Step 6: Submit a run

With the engine configured, submit runs using the engine slug: 
POST /api/v1/engines/auto-home-pl/runs
See the Integration Guide for the full submission flow, including how to structure offerings, poll for results, and handle failures.

​
Managing engines

After initial setup, use these endpoints to manage your engines:
TaskEndpoint
List all enginesGET /api/v1/engines
View engine detailsGET /api/v1/engines/
Rename or update descriptionPATCH /api/v1/engines/
Archive an enginePATCH /api/v1/engines/ with {"status": "archived"}
Reactivate an archived enginePATCH /api/v1/engines/ with {"status": "active"}
Archiving an engine prevents config updates but does not affect in-flight runs or the ability to submit new runs. Reactivate the engine to resume config changes.