# AUTO-GENERATED tier-A mirror spec — do not edit. # Source: openapi/runtime/model-routes.yaml (runtime 0.71.2) # + policy: openapi/mirror-policies/model-routes.json # Regenerate: node scripts/generate-mirror-specs.mjs openapi: 3.0.3 info: title: naturali.ai — Model Routes API version: 1.0.0 description: >- Model routes: named, ordered provider+model failover lists an agent can generate through. A fully runtime-backed module — this spec is generated verbatim from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the path is authorized by naturali and enforced upstream by the project's scoped credential. This module mirrors the upstream runtime verbatim (tier A, #304): paths are the runtime's own re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by naturali itself (authentication, project resolution, an unreachable runtime) use naturali's. contact: name: naturali.ai url: https://naturali.ai servers: - url: "{baseUrl}" description: Host of your naturali.ai deployment; every path carries the /v1 prefix. variables: baseUrl: description: Base host URL. default: https://api.naturali.ai tags: - name: Model Routes description: Manage ordered provider+model failover routes security: - bearerAuth: [] - oauth2: - mcp:access paths: /v1/projects/{project_id}/model-routes: get: tags: - Model Routes summary: List model routes description: Returns the model routes defined in a project operationId: listModelRoutes parameters: - name: limit in: query required: false description: Maximum number of results to return schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query required: false description: Number of results to skip schema: type: integer default: 0 responses: "200": description: List of model routes content: application/json: schema: type: object required: - data - total - limit - offset properties: data: type: array items: $ref: "#/components/schemas/ModelRoute" total: type: integer limit: type: integer offset: type: integer "401": description: Unauthorized "403": description: Forbidden "500": description: Internal server error post: tags: - Model Routes summary: Create a model route description: "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." operationId: createModelRoute requestBody: required: true content: application/json: schema: type: object required: - name - targets additionalProperties: false properties: name: type: string description: Human-readable name, unique per project example: primary-with-fallback targets: type: array minItems: 1 description: "Ordered failover targets. Position is priority: target 0 is tried first, and a retryable failure falls through to the next target." items: $ref: "#/components/schemas/ModelRouteTarget" retry_on: type: array description: 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. items: type: string enum: - provider_error - timeout - rate_limited default: - provider_error - timeout - rate_limited failure_threshold: type: integer default: 3 description: 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. example: 3 cooldown_seconds: type: integer default: 60 description: How long a tripped target is skipped before being probed again example: 60 responses: "201": description: Model route created successfully content: application/json: schema: $ref: "#/components/schemas/ModelRoute" "400": description: Bad request (invalid targets, attempt cap exceeded, unknown provider) "401": description: Unauthorized "403": description: Forbidden "409": description: A model route with this name already exists in the project "500": description: Internal server error parameters: - $ref: "#/components/parameters/ProjectId" /v1/projects/{project_id}/model-routes/{route_id}: get: tags: - Model Routes summary: Get a model route description: Returns a specific model route operationId: getModelRoute x-naturali-resource: kind: model_route from: route_id parameters: - name: route_id in: path required: true description: Model route ID schema: type: string example: route_V1StGXR8Z5jdHi6B responses: "200": description: Model route details content: application/json: schema: $ref: "#/components/schemas/ModelRoute" "401": description: Unauthorized "403": description: Forbidden "404": description: Model route not found put: tags: - Model Routes summary: Update a model route description: Updates a model route's name, targets, retry classes, or breaker configuration. Omitted fields are left unchanged. operationId: updateModelRoute x-naturali-resource: kind: model_route from: route_id parameters: - name: route_id in: path required: true description: Model route ID schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: New name (unique per project) targets: type: array minItems: 1 description: Replacement target list (ordered) items: $ref: "#/components/schemas/ModelRouteTarget" retry_on: type: array items: type: string enum: - provider_error - timeout - rate_limited failure_threshold: type: integer cooldown_seconds: type: integer responses: "200": description: Model route updated successfully content: application/json: schema: $ref: "#/components/schemas/ModelRoute" "400": description: Bad request "401": description: Unauthorized "403": description: Forbidden "404": description: Model route not found "409": description: A model route with this name already exists in the project delete: tags: - Model Routes summary: Delete a model route description: Deletes a model route. Returns 409 when an agent still references it — a routed agent has no pinned provider to fall back on, so the reference must be repointed or the agent deleted first. operationId: deleteModelRoute x-naturali-resource: kind: model_route from: route_id parameters: - name: route_id in: path required: true description: Model route ID schema: type: string responses: "204": description: Model route deleted successfully "401": description: Unauthorized "403": description: Forbidden "404": description: Model route not found "409": description: The model route is still referenced by one or more agents parameters: - $ref: "#/components/parameters/ProjectId" components: schemas: ModelRouteTarget: type: object required: - ai_provider_id - model properties: ai_provider_id: x-naturali-ref: ai-providers type: string description: AI provider in the route's project example: aip_V1StGXR8Z5jdHi6B model: type: string description: Model name to call on that provider example: gpt-4o-mini timeout_seconds: type: integer description: 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. example: 30 max_retries: type: integer default: 0 description: "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." example: 1 ModelRoute: type: object properties: id: type: string example: route_V1StGXR8Z5jdHi6B project_id: x-naturali-ref: projects type: string name: type: string example: primary-with-fallback targets: type: array items: $ref: "#/components/schemas/ModelRouteTarget" retry_on: type: array items: type: string enum: - provider_error - timeout - rate_limited failure_threshold: type: integer example: 3 cooldown_seconds: type: integer example: 60 created_at: type: string format: date-time updated_at: type: string format: date-time parameters: ProjectId: name: project_id in: path required: true description: Project public ID (proj_ prefix). schema: type: string example: proj_V1StGXR8Z5jdHi6B securitySchemes: bearerAuth: type: http scheme: bearer description: A naturali API key (nat_sk_…) or a session JWT. oauth2: type: oauth2 description: "A connected app's OAuth access token, issued by this API's authorization server (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation, confined to the projects the user chose when approving the app." flows: authorizationCode: authorizationUrl: https://api.naturali.ai/authorize tokenUrl: https://api.naturali.ai/token refreshUrl: https://api.naturali.ai/token scopes: mcp:access: Every operation this API serves, on the projects the grant covers.