Model Routes

Create a model route

Creates a project-scoped model route: a named, ordered list of provider+model targets tried in array order. Every target must reference an AI provider in the same project (400 otherwise), and the total attempt budget — the sum of 1 + max_retries over all targets — may not exceed 10 (400 naming the computed total). A duplicate name in the project is rejected with 409.

post/v1/projects/{project_id}/model-routes

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/model-routes
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

namestring required

Human-readable name, unique per project

retry_onstring[]

Which failure classes are failover-eligible. A failure whose class is not listed (and every deterministic failure — 400-class, auth, content policy) fails the generation immediately instead of spending another target's budget.

failure_thresholdinteger

Consecutive retryable failures after which a target is skipped for cooldown_seconds. Breaker state is in-process per node and keyed by (provider, model), so it is shared by every route pointing at the same backend.

cooldown_secondsinteger

How long a tripped target is skipped before being probed again

Example request

{
  "name": "primary-with-fallback",
  "targets": [
    {
      "ai_provider_id": "aip_V1StGXR8Z5jdHi6B",
      "model": "gpt-4o-mini",
      "timeout_seconds": 30,
      "max_retries": 1
    }
  ],
  "failure_threshold": 3,
  "cooldown_seconds": 60
}

Response

Model route created successfully

idstring
project_idstring
namestring
retry_onstring[]
failure_thresholdinteger
cooldown_secondsinteger
created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "route_V1StGXR8Z5jdHi6B",
  "name": "primary-with-fallback",
  "targets": [
    {
      "ai_provider_id": "aip_V1StGXR8Z5jdHi6B",
      "model": "gpt-4o-mini",
      "timeout_seconds": 30,
      "max_retries": 1
    }
  ],
  "failure_threshold": 3,
  "cooldown_seconds": 60
}

Changes

No recorded changes to this operation across all 1 revision of this API.