Skip to main content

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.

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 provider offerings into optimal solutions, or entity_analysis for gap analysis and recommendations. 
curl -X POST https://api.usenexio.com/api/v1/engines \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-engine",
    "label": "Product Comparison Engine",
    "description": "Rank offerings from multiple providers.",
    "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/my-engine/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. The preset includes a pack_key that identifies the domain pack — available packs depend on your account configuration.

​
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/my-engine/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": "completeness", "label": "Completeness", "method": "deterministic", "enabled": true },
        { "key": "pricing", "label": "Pricing", "method": "deterministic", "enabled": true },
        { "key": "quality", "label": "Quality", "method": "deterministic", "enabled": true }
      ],
      "appetite_weight_profiles": [
        {
          "bucket": "balanced",
          "label": "Balanced",
          "weights": { "completeness": 0.34, "pricing": 0.33, "quality": 0.33 }
        }
      ],
      "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/my-engine/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": "completeness", "label": "Completeness", "method": "deterministic", "enabled": true },
        { "key": "pricing", "label": "Pricing", "method": "deterministic", "enabled": true },
        { "key": "quality", "label": "Quality", "method": "deterministic", "enabled": true }
      ],
      "appetite_weight_profiles": [
        {
          "bucket": "balanced",
          "label": "Balanced",
          "weights": { "completeness": 0.34, "pricing": 0.33, "quality": 0.33 }
        }
      ],
      "default_appetite_bucket": "balanced"
    }
  }'

​
Step 5: Copy the integration contract

Open your engine’s Contract page on platform.usenexio.com and click Copy for agents. You get a single Markdown document with the typed request schema, scoring dimensions, weight profiles, an example request/response payload, and polling instructions — everything a downstream consumer or AI coding agent needs to build a correct integration. Paste it into the agent’s context and let it generate the client. The Contract page is regenerated from your engine’s saved config, so the document always matches what the API expects on the next run.

​
Step 6: Submit a run

With the engine configured, submit runs using the engine slug: 
POST /api/v1/engines/my-engine/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.