API Reference: Cost Routing Configuration

import { Aside } from ‘@astrojs/starlight/components’;

API Reference: Cost Routing Configuration

Base path: /api/v1/admin/cost-routing

Cost routing configuration controls how Arbitex selects providers and models when multiple options are available for a given request. Models are organized into named tiers (capability buckets), and requests are routed within a tier using one of six optimization strategies.

---

Tier Model

Models are assigned to named tiers (e.g., premium, standard, economy). Tier names are freeform strings — there is no predefined set. Each tier contains one or more model entries with per-model cost and weight metadata.

Tier configuration is stored as a flat key-value in system_configs under the key model_tiers.

Model Tier Entry

{
  "model_id": "claude-3-haiku-20240307",
  "provider": "anthropic",
  "tier": "standard",
  "input_cost_per_1k": 0.00025,
  "output_cost_per_1k": 0.00125,
  "weight": 1.0
}

Field	Type	Description
model_id	string	Model identifier
provider	string	Provider identifier (e.g., anthropic, openai)
tier	string	Named capability tier
input_cost_per_1k	float	Cost per 1K input tokens (USD)
output_cost_per_1k	float	Cost per 1K output tokens (USD)
weight	float	Routing weight for weighted strategy (default 1.0)

---

Optimization Strategies

Strategy	Description
cheapest_input	Select the model with the lowest input_cost_per_1k
cheapest_output	Select the model with the lowest output_cost_per_1k
cheapest_combined	Select the model with the lowest combined input + output cost (default)
weighted	Weighted random selection using the weight field
lowest_latency	Delegate to LatencyRouter.select_fastest()
balanced	Delegate to LatencyRouter.select_balanced() (cost + latency blend)

---

List Tier Assignments

GET /api/v1/admin/cost-routing/tiers
Authorization: Bearer <admin-token>

Returns the full ModelTierConfig — all models across all tiers.

Response 200 OK:

{
  "tiers": {
    "premium": [
      {
        "model_id": "claude-3-5-sonnet-20241022",
        "provider": "anthropic",
        "tier": "premium",
        "input_cost_per_1k": 0.003,
        "output_cost_per_1k": 0.015,
        "weight": 1.0
      },
      {
        "model_id": "gpt-4o",
        "provider": "openai",
        "tier": "premium",
        "input_cost_per_1k": 0.0025,
        "output_cost_per_1k": 0.01,
        "weight": 1.0
      }
    ],
    "standard": [
      {
        "model_id": "claude-3-haiku-20240307",
        "provider": "anthropic",
        "tier": "standard",
        "input_cost_per_1k": 0.00025,
        "output_cost_per_1k": 0.00125,
        "weight": 1.0
      }
    ]
  }
}

---

List Tier Names

GET /api/v1/admin/cost-routing/tiers/names
Authorization: Bearer <admin-token>

Returns all tier name strings.

Response 200 OK:

["economy", "premium", "standard"]

The response is a sorted bare array of tier name strings (not wrapped in an object).

---

Assign Model to Tier

POST /api/v1/admin/cost-routing/tiers/assign
Authorization: Bearer <admin-token>
Content-Type: application/json

Request body:

{
  "model_id": "gpt-4o-mini",
  "provider": "openai",
  "tier": "standard",
  "input_cost_per_1k": 0.00015,
  "output_cost_per_1k": 0.0006
}

The model’s weight defaults to 1.0 and can be adjusted later via the Update Tier Weights endpoint.

Response 200 OK: Updated ModelTierConfig.

---

Bulk Assign Models to Tiers

POST /api/v1/admin/cost-routing/tiers/assign/bulk
Authorization: Bearer <admin-token>
Content-Type: application/json

Request body:

{
  "assignments": [
    {
      "model_id": "gpt-4o-mini",
      "provider": "openai",
      "tier": "standard",
      "input_cost_per_1k": 0.00015,
      "output_cost_per_1k": 0.0006
    },
    {
      "model_id": "claude-3-haiku-20240307",
      "provider": "anthropic",
      "tier": "economy",
      "input_cost_per_1k": 0.00025,
      "output_cost_per_1k": 0.00125
    }
  ]
}

Response 200 OK: Updated ModelTierConfig.

---

Update Tier Weights

PUT /api/v1/admin/cost-routing/tiers/{tier}/weights
Authorization: Bearer <admin-token>
Content-Type: application/json

Path parameters: tier — tier name string

Updates the weight field for models within a tier. Used to adjust weighted routing distribution.

Request body: Array of weight update objects.

[
  { "model_id": "claude-3-haiku-20240307", "weight": 2.0 },
  { "model_id": "gpt-4o-mini", "weight": 1.0 }
]

Field	Type	Description
model_id	string	Model identifier to update
weight	float	New routing weight (>= 0.0)

Response 200 OK: Updated ModelTierConfig.

Response 404: Tier not found.

---

Remove Model from Tier

DELETE /api/v1/admin/cost-routing/tiers/assign/{model_id}
Authorization: Bearer <admin-token>

Path parameters: model_id — model identifier string

Removes a model from its current tier assignment.

Response 200 OK: Updated ModelTierConfig.

Response 404: Model not found in any tier.

---

Select Model (Test/Preview)

Test how the cost router would select a model for a given tier and strategy without sending a request:

POST /api/v1/admin/cost-routing/select
Authorization: Bearer <admin-token>
Content-Type: application/json

Request body:

{
  "tier": "standard",
  "optimize": "cheapest_combined"
}

Field	Type	Description
tier	string	Capability tier to route from
optimize	string	One of the 6 strategy strings above

Response 200 OK:

{
  "model_id": "claude-3-haiku-20240307",
  "provider": "anthropic",
  "tier": "standard",
  "input_cost_per_1k": 0.00025,
  "output_cost_per_1k": 0.00125,
  "reason": "Lowest combined cost in tier 'standard'"
}

---

Error Reference

Status	Description
400	Malformed JSON or invalid strategy
404	Tier or model not found
422	Validation error (missing required fields, invalid cost values)

---

Related

• Model Catalog API
• Budget Enforcement Guide
• Kill Switch