Skip to content
Documentation
GuidesAPI ReferenceIntegrations
ArenaPlatform
API Reference/Named Routers

Simulate Routing

POST/v1/routers/{id}/simulate

Overview

Requires an active workspace membership with owner, admin, developer, or viewer role.

Routing and provider details

Billing-only members and inference API keys are rejected. workspace_id is always required; a router ID from a different authorized workspace returns 404. Cookie-authenticated POST requests also require the same-origin proof described by the Routers tag.

This operation does not write a revision or call a provider. Evaluates the first matching route, then deterministically assigns an integer bucket 0–99 to its weighted variants. Assignment is scoped by workspace, router, draft generation/config hash or immutable revision, route, and assignment_key. Auto mode ranks eligible candidates by exact native token cost; ordered mode preserves candidate order.

The response includes the route trace, field-wise effective defaults, eligible/excluded models and validation issues. Empty candidate pools remain explainable. Malformed request or configuration envelopes return 400; invalid simulation facts and selection violations return issues with selection null. Metadata never grants workspace or model entitlement. inference_enabled is always false because simulation never calls a model. To see which A/B variant a caller gets in production, simulate the published revision (revision) with the caller's session_id as assignment_key; assignment is scoped to the revision, so a draft simulation can differ.

Authorization

Authorizationstring · headerRequired

Workspace session token sent as Bearer <token>. Authentication guide

Parameters

idpath · stringRequired

Router identity in the explicitly supplied workspace.

Request Body

application/json
workspace_idstringRequired
expected_generationinteger

Current generation observed by the caller. Re-read the router after a 409; do not overwrite a concurrent edit.

Minimum 1 · Maximum 2147483646

revisioninteger

Minimum 1 · Maximum 1000

configobject

Versioned declarative LLM router configuration, normalized to at most 65536 UTF-8 JSON bytes. Unknown fields and undocumented null values are rejected. Structurally valid but incomplete drafts are permitted; validation/publication enforce final-default, nonempty pools, uniqueness, exact weights and current model eligibility.

Example: {"schema_version":1,"task":"llm","protocol":"chat","requirements":[],"defaults":{},"request_overrides":[],"policy":{"max_input_tokens":128000,"max_output_tokens":8192,"deadline_ms":120000,"regions":[],"zero_retention":false},"routes":[{"id":"default","name":"Default","condition":null,"defaults":{},"variants":[{"id":"primary","name":"Primary","weight":100,"selection":{"mode":"ordered","models":[]},"defaults":{}}]}]}

Show nested fields
schema_versionintegerRequired
taskstringRequired
protocolstringRequired

Values: "chat""responses""messages"

requirementsstring[]

Default: []

Show nested fields

string

defaultsobject

Field-wise inheritance: router defaults, then route defaults, then variant defaults, then explicitly permitted request parameters. Omitted fields inherit; null does not clear a field. max_tokens defaults to policy.max_output_tokens and cannot exceed that policy. Every effective and overridable parameter must be supported by every selected model.

Show nested fields
max_tokensinteger

Minimum 1 · Maximum 1000000

temperaturenumber

Minimum 0 · Maximum 2

top_pnumber

Minimum 0 · Maximum 1

system_promptstring
request_overridesstring[]

Default: []

Show nested fields

string

policyobject

Declarative upper limits, intersected with current operator/workspace/model restrictions. A model must support the full configured input plus output context budget. Region and zero-retention requirements cannot widen workspace policy.

Show nested fields
max_input_tokensinteger

Default: 128000

Minimum 1 · Maximum 1000000

max_output_tokensinteger

Default: 8192

Minimum 1 · Maximum 1000000

deadline_msinteger

Default: 120000

Minimum 1000 · Maximum 1800000

regionsstring[]

Regions every route requires: us, eu or a documented country code, any of which an endpoint may process in. Empty or global means none. Each model must have an endpoint documented in one of them, and requests can narrow it but never widen it. A region no endpoint documents is refused with 422 on create, update and duplicate, and validate reports it as region_unavailable.

Default: []

Show nested fields

See the OpenAPI schema for this nested object.

zero_retentionboolean

Reserved. Router-level zero retention is not available, so true is refused with 422 and validate reports zero_retention_unavailable. Workspace Privacy settings, including zero data retention per provider family, still apply to every route.

Default: false

max_priceobject
Show nested fields
inputstringRequired

Exact decimal USD per native token. Strings avoid binary floating-point ambiguity. A limit of zero is allowed; approved native catalog prices must be positive.

outputstringRequired

Exact decimal USD per native token. Strings avoid binary floating-point ambiguity. A limit of zero is allowed; approved native catalog prices must be positive.

routesobject[]Required
Show nested fields
idstringRequired
namestringRequired
conditionobject | object | object | object | object | object | object | nullRequired
Show nested fields

See the OpenAPI schema for this nested object.

defaultsobject

Field-wise inheritance: router defaults, then route defaults, then variant defaults, then explicitly permitted request parameters. Omitted fields inherit; null does not clear a field. max_tokens defaults to policy.max_output_tokens and cannot exceed that policy. Every effective and overridable parameter must be supported by every selected model.

Show nested fields

See the OpenAPI schema for this nested object.

variantsobject[]Required
Show nested fields

See the OpenAPI schema for this nested object.

inputobject

Synthetic simulation facts, never authorization claims. Unspecified protocol uses the router protocol. Input/output counts cannot exceed router policy. Parameters must be explicitly allowed by request_overrides and cannot widen policy. No prompt or paid inference is needed.

Show nested fields
assignment_keystring

Default: "preview"

metadataobject

Default: {}

input_tokensinteger

Default: 0

Minimum 0 · Maximum 1000000

output_tokensinteger

Default: 0

Minimum 0 · Maximum 1000000

protocolstring

Values: "chat""responses""messages"

parametersobject

Field-wise inheritance: router defaults, then route defaults, then variant defaults, then explicitly permitted request parameters. Omitted fields inherit; null does not clear a field. max_tokens defaults to policy.max_output_tokens and cannot exceed that policy. Every effective and overridable parameter must be supported by every selected model.

Show nested fields
max_tokensinteger

Minimum 1 · Maximum 1000000

temperaturenumber

Minimum 0 · Maximum 2

top_pnumber

Minimum 0 · Maximum 1

system_promptstring

Responses

200Operation completed.
application/json
generationintegerRequired

Optimistic version of the router record. Every successful mutation increments it. Send the observed value as expected_generation; stale values return 409.

Minimum 1 · Maximum 2147483647

validbooleanRequired
publishablebooleanRequired
catalog_revisionstring | nullRequired
Show nested fields
Option 1: string

string

Option 2: null

null

issuesobject[]Required
Show nested fields
codestringRequired
pathstringRequired
messagestringRequired
modelsobject[]Required
Show nested fields
modelstringRequired

A catalog model ID: a model several hosts serve (its hosts are ranked as for a request), a host's own ID, either with :nitro, :floor, :exacto, :free or :thinking, or a ~author/family-latest alias. An entry is eligible when one endpoint it can route to is. Recursive router aliases are forbidden.

eligiblebooleanRequired
reasonsstring[]Required
Show nested fields

See the OpenAPI schema for this nested object.

selectionobject | nullRequired
Show nested fields
Option 1: object
route_idstringRequired
variant_idstringRequired
bucketintegerRequired

Minimum 0 · Maximum 99

traceobject[]Required
Show nested fields

See the OpenAPI schema for this nested object.

modelsstring[]Required
Show nested fields

See the OpenAPI schema for this nested object.

modestringRequired

Values: "ordered""auto"

effective_defaultsobjectRequired

Field-wise inheritance: router defaults, then route defaults, then variant defaults, then explicitly permitted request parameters. Omitted fields inherit; null does not clear a field. max_tokens defaults to policy.max_output_tokens and cannot exceed that policy. Every effective and overridable parameter must be supported by every selected model.

Show nested fields
max_tokensinteger

Minimum 1 · Maximum 1000000

temperaturenumber

Minimum 0 · Maximum 2

top_pnumber

Minimum 0 · Maximum 1

system_promptstring
eligible_modelsstring[]Required
Show nested fields

See the OpenAPI schema for this nested object.

excluded_modelsobject[]Required
Show nested fields

See the OpenAPI schema for this nested object.

Option 2: null

null

inference_enabledbooleanRequired

Always false: simulation never calls a model. Published routers run through Chat Completions, Responses and Messages.

400Request validation failed.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

401Authentication is missing or invalid.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

403Authenticated principal lacks permission.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

404Resource was not found.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

409Stale expected_generation, archived state, reserved slug, or an Idempotency-Key reused with different command content. Re-read current state before editing; do not blindly retry with a new generation.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

413JSON body exceeds 131072 bytes.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

422Draft cannot publish or the requested restore is no longer eligible under current policy/catalog. Also used for workspace router or revision limits. Use validate for structured blocking issues. No revision, active-pointer change or idempotency claim is committed on failure.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

429Rate limit exceeded.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

500Internal server error.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.