Sandbox fixtures

A sandbox fixture makes a run finish in a state you choose: completed, degraded or failed. The run goes through normal admission, polling and webhooks, but its output comes from a published fixture file and no model or enrichment provider is called. Use it to test that your client handles every terminal state.

Fixtures work only for the fixture engine, generic_fixture_engine, at the exact versions in the supported contract registry: 1.0, 1.1, 1.3 and 2.0. Your own engines cannot run fixtures. A request against any other engine or version gets 400 test_scenario_version_not_supported.

Requirements

Requirement	Why
A scoped key that holds `runs:write` and `runs:test`	`runs:test` is issued by Nexio. Organization keys cannot run fixtures
The key’s environment is a sandbox	Live requests are refused
The key is bound to the fixture engine	Like any engine route
An exact `engine_version` pin, such as `"1.0"`	The pin selects the registry entry

Ask Nexio for a fixture testing key if you need one.

Request

Add test_scenario at the top level of a run request, next to input:

curl -X POST https://api.usenexio.com/api/v1/engines/generic-fixture-engine/runs \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contract-check-degraded-001" \
  -d '{
    "engine_version": "1.0",
    "test_scenario": "degraded",
    "input": { "request_id": "contract-check-degraded" }
  }'

import os
import requests

resp = requests.post(
    "https://api.usenexio.com/api/v1/engines/generic-fixture-engine/runs",
    headers={
        "Authorization": "Bearer " + os.environ["NEXIO_API_KEY"],
        "Idempotency-Key": "contract-check-degraded-001",
    },
    json={
        "engine_version": "1.0",
        "test_scenario": "degraded",
        "input": {"request_id": "contract-check-degraded"},
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(
  "https://api.usenexio.com/api/v1/engines/generic-fixture-engine/runs",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEXIO_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "contract-check-degraded-001",
    },
    body: JSON.stringify({
      engine_version: "1.0",
      test_scenario: "degraded",
      input: { request_id: "contract-check-degraded" },
    }),
  },
);
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
console.log(await resp.json());

The engine slug in your org is set when Nexio creates the fixture engine for you; generic-fixture-engine above is an example. Response 202:

{
  "run_id": "c41d7e20-5a8b-4f93-b6e2-09d1f3a7c5b8",
  "status": "queued"
}

Outcomes

`test_scenario`	Terminal run status	Webhook event
`completed`	`completed`	`run.completed`
`degraded`	`degraded`	`run.completed`, with `data.run.status` equal to `degraded`
`failed`	`failed`	`run.failed`

The run’s output, warning_details, error and error_details are the values in the entry’s fixture file under terminal.completed, terminal.degraded or terminal.failed. For version 1.0, a failed fixture run reports:

{
  "error": "fixture provider failed",
  "error_details": { "code": "FIXTURE_PROVIDER_FAILURE" }
}

test_scenario is never inferred from input, and it does not appear in poll or webhook responses.

What still applies

Each fixture run is a real run: it counts against the monthly run cap and the rate limits.
Idempotency-Key works as for any run, and test_scenario is part of the request it compares.
Webhook secret rotation in a sandbox keeps the previous secret valid for 5 minutes.

Errors

Checks run in this order, and a refused request creates no run, uses no cap and queues nothing.

HTTP	Code	Cause	Fix
400	`test_scenario_sandbox_only`	The key’s environment is `live`	Use a sandbox key
403	`test_scenario_forbidden`	The key does not hold `runs:test`	Use a scoped key with `runs:test`
400	`test_scenario_exact_version_required`	`engine_version` is missing or is not an exact `major.minor`	Pin an exact version such as `"1.0"`
400	`test_scenario_version_not_supported`	The engine and version are not a registry entry	Use the fixture engine at 1.0, 1.1, 1.3 or 2.0
400	`invalid_test_scenario`	The value is not `completed`, `degraded` or `failed`	Use one of the three values

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Sandbox fixtures

Requirements

Request

Outcomes

What still applies

Errors

​Requirements

​Request

​Outcomes

​What still applies

​Errors

Requirements

Request

Outcomes

What still applies

Errors