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

Validate a Router

POST/v1/routers/{id}/validate

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. Omit both revision and config to validate the saved draft. config supplies a transient document and cannot be combined with revision. expected_generation optionally rejects a stale editor.

valid describes structural/semantic document validity; publishable additionally requires active workspace entitlement and every model to satisfy current catalog, global, workspace, protocol, capability, context, native price, parameter, region, retention, deadline and fallback restrictions. Empty candidate pools produce blocking issues.

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.

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.

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.