---
title: "Update a model route"
method: PUT
path: "/v1/projects/{project_id}/model-routes/{route_id}"
tags: ["Model Routes"]
---

# Update a model route

`PUT /v1/projects/{project_id}/model-routes/{route_id}`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/model-routes/{route_id}`
- 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`)

Updates a model route's name, targets, retry classes, or breaker configuration. Omitted fields are left unchanged.

## Path parameters

- `route_id` string, required

## Request body

- object
  - `name` string: New name (unique per project)
  - `targets` ModelRouteTarget[]: Replacement target list (ordered)
    - `ai_provider_id` string, required: AI provider in the route's project
    - `model` string, required: Model name to call on that provider
    - `timeout_seconds` integer: Per-attempt deadline, enforced with an AbortSignal composed with the caller's signal. A timeout classifies as `timeout`; the caller's own signal firing aborts the run without failover. Omitted means no per-target deadline.
    - `max_retries` integer: Retries on this target before falling through to the next one. The route is the only retry authority — routed calls pass `maxRetries: 0` to the AI SDK so its own retry loop cannot multiply these.
  - `retry_on` string[]
  - `failure_threshold` integer
  - `cooldown_seconds` integer

## Response `200`

Model route updated successfully

- ModelRoute
  - `id` string
  - `project_id` string
  - `name` string
  - `targets` ModelRouteTarget[]
    - `ai_provider_id` string, required: AI provider in the route's project
    - `model` string, required: Model name to call on that provider
    - `timeout_seconds` integer: Per-attempt deadline, enforced with an AbortSignal composed with the caller's signal. A timeout classifies as `timeout`; the caller's own signal firing aborts the run without failover. Omitted means no per-target deadline.
    - `max_retries` integer: Retries on this target before falling through to the next one. The route is the only retry authority — routed calls pass `maxRetries: 0` to the AI SDK so its own retry loop cannot multiply these.
  - `retry_on` string[]
  - `failure_threshold` integer
  - `cooldown_seconds` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Model route not found
- `409`: A model route with this name already exists in the project

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)