> ## 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. # Submit Run > Submit a payload for asynchronous processing. Returns a run ID for polling or webhook delivery. ## OpenAPI ````yaml POST /api/v1/engines/{engine_slug}/runs openapi: 3.1.0 info: title: Nexio API version: '1.0' description: | Nexio agentic infrastructure API. Configure engines for placement, entity analysis, and other patterns. Submit runs, poll for results, or subscribe to signed webhook callbacks. contact: email: support@usenexio.com url: https://docs.usenexio.com servers: - url: https://api.usenexio.com description: Production security: - BearerAuth: [] tags: - name: EngineManagement description: Create, configure, and manage inference engines. - name: Engines description: Engine-scoped endpoints for submitting runs and retrieving results. - name: Runs description: Retrieve and reconcile submitted runs. - name: Catalog description: >- Read current carriers and products extracted for the authenticated organization. - name: Environments description: Isolated tenancy scopes under your org (one live plus non-live sandboxes). - name: Webhooks description: Manage webhook endpoints for push-based delivery of terminal run events. paths: /api/v1/engines/{engine_slug}/runs: post: tags: - Engines summary: Submit Run description: > Submit a payload for asynchronous processing via an engine-scoped endpoint. The API queues the run immediately and returns a `202 Accepted` response with a `run_id`. Scoped partner keys require `runs:write` and an explicit binding to this engine. Engines with the `exact_required` pin policy reject an omitted `engine_version` with `engine_version_required` and reject an `N.x` pin with `engine_version_exact_required`. The exact request shape depends on the engine you call: - placement engines typically send submission context in `input` plus provider offerings in top-level `offerings` - entity-analysis engines send the analysis payload in `input` See the [Integration Guide](/guides/integration) for placement payloads, the [Headless Engine Setup](/guides/headless-engine-setup) guide for a domain-specific example payload, and the per-engine Contract page on platform.usenexio.com (Copy-for-agents button) for an engine-specific typed-schema integration guide. After submission, poll `GET /api/v1/runs/{run_id}` or subscribe to [webhooks](/api-reference/webhooks/overview) for terminal-state updates. > **Note:** The example payload below uses a personal-lines insurance domain. > Your engine's input schema depends on its configuration. ### Contract assets - [Canonical request](/assets/example_input_insurance_personal_lines.json): complete request body with `input` and `offerings` - [Canonical response](/assets/example_output_insurance_personal_lines.json): complete response for a finished run operationId: submitRun parameters: - $ref: '#/components/parameters/EngineSlug' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRunRequest' example: input: address: state: NY zip_code: '11231' coverage_types: - auto appetite_bucket: balanced offerings: - id: 20260416-14.06.01.632319 provider_id: prog provider_name: Progressive category: auto attributes: line_of_business: auto quoted_vehicle_count: 1 term_months: 12 line_premium_annual: 1445 coverage: deductible_default: 500 limit_combined_single: 300000 - id: d4d5a3da-381c-40c8-b70d-39a1935af0cd provider_id: safe provider_name: Safeco category: auto attributes: line_of_business: auto quoted_vehicle_count: 1 term_months: 12 line_premium_annual: 7226 coverage: deductible_default: 500 limit_combined_single: 300000 - id: '90584063' provider_id: trvl provider_name: Travelers category: auto attributes: line_of_business: auto quoted_vehicle_count: 1 term_months: 12 line_premium_annual: 2871 coverage: deductible_default: 500 limit_combined_single: 300000 responses: '202': description: Run accepted and queued for processing. content: application/json: schema: $ref: '#/components/schemas/SubmitRunResponse' example: run_id: bcb87157-0bfc-404d-a120-7f5c9cd01037 status: queued '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: The scoped key lacks `runs:write` or `runs:test`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficientCapability: value: code: insufficient_capability message: API key does not have permission for this action testScenarioForbidden: value: code: test_scenario_forbidden message: >- The authenticated principal does not have the runs:test capability. '413': description: The HTTP envelope or canonical JSON payload exceeds its byte limit. content: application/json: schema: $ref: '#/components/schemas/RequestBoundError' '429': description: Per-minute rate limit or monthly run cap exceeded. headers: Retry-After: description: Seconds until the RPM window resets. Present for `rate_limited`. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: rateLimited: value: code: rate_limited message: Rate limit exceeded monthlyCap: value: code: run_cap_exceeded message: >- Monthly run cap reached for this organization. Contact support to raise the limit. '503': description: Temporary service unavailability. content: application/json: schema: $ref: '#/components/schemas/Error' examples: authUnavailable: summary: API key authentication temporarily unavailable value: code: auth_unavailable message: API key authentication is temporarily unavailable queueUnreachable: summary: Queue unreachable value: code: queue_unreachable message: Failed to enqueue run, queue unreachable components: parameters: EngineSlug: name: engine_slug in: path required: true description: Engine identifier slug (e.g. `default`). schema: type: string schemas: SubmitRunRequest: type: object additionalProperties: false required: - input properties: input: type: object additionalProperties: true description: | Engine-specific submission context. Common fields for current Engine-specific submission context. The exact fields depend on your engine's configuration and domain. Common fields for current insurance engines include: - placement engines: - `coverage_types`: lines to evaluate: `home`, `auto`, `umbrella` - `address.state`: two-letter state code used in quote matching - `applicant`, `drivers`, `vehicles_detail`, `residence` - `current_coverage`: incumbent policies used for context, not ranked - `insurance_history` - `appetite_bucket`: ranking strategy - entity-analysis engines: - `prospect.primary_address.state` - `current_portfolio` - any additional fields required by that engine's generated contract Open the Contract page on platform.usenexio.com for your engine to see the exact request schema; the Copy-for-agents button yields a Markdown integration guide ready to paste into agent-tooling prompts. offerings: type: array description: | Provider offerings: one entry per provider per requirement category. Required in practice for placement engines that rank quoted line items. Not typically used by entity-analysis engines. items: $ref: '#/components/schemas/Offering' engine_version: type: string pattern: ^\d+\.(\d+|x)$ description: | Pins which released engine configuration and request/response schemas this run uses. - `"1.3"`: exact released configuration and schemas. - `"1.x"`: auto-track the latest released minor of major 1 (you ride minor releases only when the engine policy permits it). - `"draft"`: mutable unpublished config, accepted only in a sandbox environment. Bare major (`"1"`) and three-tier semver (`"1.0.0"`) are rejected. Omission resolves to the latest release only for legacy-policy engines. `exact_required` engines require an explicit `N.M` and reject `N.x`. The resolved exact version is stable for the run and is echoed by polling and webhooks. example: '1.0' test_scenario: type: string enum: - completed - degraded - failed description: | Deterministic supported-version fixture. Requires a sandbox environment, a scoped key with `runs:test`, and an explicit exact `engine_version` present in the published registry. Fixture runs use zero provider egress and count against the monthly run cap. SubmitRunResponse: type: object required: - run_id - status properties: run_id: type: string format: uuid description: Unique run identifier. Use this to poll for results. status: type: string enum: - queued description: Always `queued` on successful submission. Error: type: object required: - code - message properties: code: type: string description: | Stable snake_case error identifier. Safe to match programmatically. Known codes: `invalid_request`, `invalid_input`, `unauthorized`, `auth_unavailable`, `rate_limited`, `missing_run_id`, `invalid_run_id`, `run_not_found`, `invalid_offerings`, `missing_input`, `queue_unreachable`, `engine_not_found`, `engine_slug_conflict`, `engine_archived`, `invalid_engine_type`, `validation_error`, `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`, `invalid_events`, `invalid_description`, `invalid_auth_token`, `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`, `invalid_delivery_id`, `delivery_not_found`, `delivery_not_resendable`, `insufficient_capability`, `engine_version_required`, `engine_version_exact_required`, `engine_version_not_found`, `engine_version_invalid_format`, `engine_version_draft_requires_sandbox_key`, `engine_version_none_released`, `test_scenario_sandbox_only`, `test_scenario_forbidden`, `test_scenario_exact_version_required`, `test_scenario_version_not_supported`, `invalid_test_scenario`, `request_bound_exceeded`, and `run_cap_exceeded`. message: type: string description: Human-readable error message. May change between versions. details: description: | Optional request-specific details. Request-bound failures use the `RequestBoundDetails` object. Validation failures may use an array of field issues or another documented object. RequestBoundError: type: object additionalProperties: false required: - code - message - details properties: code: type: string const: request_bound_exceeded message: type: string details: $ref: '#/components/schemas/RequestBoundDetails' Offering: type: object required: - id - provider_id - provider_name - category properties: id: type: string description: Stable line-level identifier. provider_id: type: string description: Stable provider identifier. provider_name: type: string description: Provider display name. category: type: string description: >- Requirement category (domain-specific). Must match a value in `input.coverage_types`. quality_rating: type: string description: Provider quality rating (e.g. `A+`, `A`, `B++`). pricing_tier: type: string description: Pricing tier (`premium`, `standard`, `economy`). commission: type: number description: Commission rate as decimal (e.g. `0.14` for 14%). coverage: $ref: '#/components/schemas/CoverageDetail' constraints: $ref: '#/components/schemas/FilterConstraints' attributes: type: object additionalProperties: true description: > Domain-specific attributes. Structure depends on your engine's configuration. Example fields for an insurance engine: - `quote_id`: line quote ID from your source system - `line_premium_annual`: annual cost for this line - `package_premium_annual`: annual cost for the parent provider package - `package_id`: identifier tying offerings from the same provider package - `am_best`: AM Best rating (insurance-specific) - `broker`: originating intermediary name - `quote_generated_at`: ISO 8601 timestamp when the offering was generated - `quote_expires_at`: ISO 8601 timestamp when the offering expires - `term_months`: term length RequestBoundDetails: type: object additionalProperties: false required: - bound - path - limit - actual properties: bound: type: string enum: - http_envelope_bytes - max_canonical_bytes - max_string_length - max_array_items - max_object_fields - max_object_depth path: type: string description: Deterministic JSON path to the first violation. limit: type: integer actual: type: integer CoverageDetail: type: object description: Product-specific detail, pricing, and qualification data. properties: product_name: type: string description: Quoted product name. product_code: type: string description: Optional product code for the quoted product. program_type: type: string description: | Program type identifier (e.g. `quoted_line` for standard offerings). market_type: type: string distribution: type: string appetite_strength: type: string specialty_flags: type: array items: type: string limit_per_occurrence: type: integer limit_aggregate: type: integer limit_combined_single: type: integer deductible_min: type: integer deductible_max: type: integer deductible_default: type: integer sublimits: type: object additionalProperties: type: integer endorsements_included: type: array items: type: string endorsements_available: type: array items: type: string endorsements_excluded: type: array items: type: string coverage_breadth: type: string includes_defense_costs: type: boolean tail_coverage: type: boolean bundle: $ref: '#/components/schemas/BundlePricing' rate_basis: type: string commission_renewal: type: number required_docs: type: array items: type: string loss_run_years: type: integer appetite_notes: type: string underwriting_notes: type: string FilterConstraints: type: object description: > Eligibility constraints used by the filtering stage. Pass empty arrays `[]` for fields that don't apply to your domain. properties: excluded_states: type: array items: type: string description: States where the offering is unavailable (can be empty `[]`). prohibited_naics: type: array items: type: string description: >- Industry classification codes that disqualify the offering. Pass `[]` if not applicable. avoided_naics: type: array items: type: string description: >- Industry classification codes the provider prefers to avoid. Pass `[]` if not applicable. min_employees: type: integer description: Minimum employee count for eligibility. Omit if not applicable. max_employees: type: integer description: Maximum employee count for eligibility. Omit if not applicable. min_vehicles: type: integer description: Minimum vehicle count for eligibility. max_vehicles: type: integer description: Maximum vehicle count for eligibility. min_premium: type: integer description: Minimum annual cost for eligibility. max_premium: type: integer description: Maximum annual cost for eligibility. expiration_date: type: string description: Offering expiration date. BundlePricing: type: object description: | Set on a single offering when the carrier sells this offering as part of a multi-line package. Identifies the partner offerings (`bundles_with`) and the carrier's joined annual price (`joined_premium_annual`). Omit on standalone offerings. properties: bundles_with: type: array items: type: string description: | Offering IDs (from this same `offerings[]` array) that this offering is sold paired with. The bundle is recognized only when every listed offering, plus this one, appears in the same solution. joined_premium_annual: type: integer minimum: 0 description: | Total bundled annual premium for the group, in dollars per year. Replaces the sum of per-offering standalone premiums when the bundle is fully present in the solution. required: type: boolean description: | Set to `true` if the carrier will not sell any member of the bundle standalone. Solutions that include any bundle member without the rest are dropped. responses: BadRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: summary: Malformed JSON value: code: invalid_request message: Request body is not valid JSON invalidInput: summary: Input validation failed value: code: invalid_input message: Input failed validation details: - field: input.address.state message: address.state is required for placement runs. invalidOfferings: summary: Placement run missing offerings value: code: invalid_offerings message: Inline offerings failed validation details: - field: offerings message: >- Offerings are required for placement runs. Pass provider offerings in the top-level offerings array. Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Missing or invalid API key securitySchemes: BearerAuth: type: http scheme: bearer description: | Send the credential as `Authorization: Bearer `. Scoped partner credentials use the exclusive `nxsk_v1_...` namespace. Each scoped key is bound at issuance to one organization, one canonical named environment, an explicit engine set, and a least-privilege capability set. A malformed, unknown, rotated, or revoked `nxsk_` key fails closed and is never retried as a legacy key. Capabilities used by this API are `runs:write`, `runs:read`, `engines:read`, `catalog:read`, `webhooks:manage`, `runs:defensibility:read`, `runs:test`, and `converse:use`. Operation descriptions name the required capability. Grandfathered `nx_live_...` and `nx_test_...` keys retain their existing broad access during the compatibility window. ````