Virtual Models

Create Virtual Model

post

Creates a virtual model — a named list of [provider, model, weight] entries plus a routing strategy — and returns its model_list_id, which updateVirtualModel and deleteVirtualModel need.

Access: createVirtualModel with project_id — org owner or project admin. createVirtualModel without project_id (org-level) — org owner only.

Rules: the key must be valid and belong to org_id; a key works only on its own project's virtual models; the key's creator must still be a member of the org and project.

Known issue: a project member's key calling create is rejected with 500 An internal error occurred instead of a 403.

Authorizations

AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Body

org_idstringRequired

Must match the key's org.

project_idstringOptional

Must be the key's project. Leave out to create an org-level model (org owner key only).

model_list_namestringRequired

Unique within the project.

default_strategy_namestring · enumRequired

Hyphen forms (e.g. lowest-price) are accepted and stored with underscores.

Example: random_shufflePossible values:

model_list_idstringOptional

Must not be sent on create; returns 400.

Responses

200

Virtual model created.

application/json

model_list_idstringOptionalExample: b7248b2e-bb43-11f1-9932-de4251ea43fc

model_list_namestringOptional

project_idstring · nullableOptional

400

Bad Request. Includes: unknown strategy (default_strategy_name must be one of: ...), missing model_list_id on update/delete (model_list_id is required), wrong model_list_id (Virtual model not found for model_list_id: ...), unknown project_id (Project not found for org_id=..., project_id=...), model_list_id sent on create (model_list_id not allowed), unknown model (Invalid model 'x': model not found), or provider not serving the model (Invalid provider 'x' for model 'y').

application/json

401

Missing or invalid API key.

application/json

403

Forbidden. Includes: key from another org (API key does not belong to this organization), another project's model or project_id (API key does not belong to this project), or an org-level action without an org owner's key (API key must belong to an organization owner to perform this operation).

application/json

post/prod/createVirtualModel

POST /prod/createVirtualModel HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 218

{
  "org_id": "<ORG_ID>",
  "project_id": "<PROJECT_ID>",
  "model_list_name": "frontier-router",
  "default_strategy_name": "random_shuffle",
  "model_provider_list": [
    [
      "openai",
      "openai/gpt-5.1",
      0.7
    ],
    [
      "openai",
      "openai/gpt-5.5-pro",
      0.3
    ]
  ]
}

{
  "model_list_id": "b7248b2e-bb43-11f1-9932-de4251ea43fc",
  "model_list_name": "frontier-router",
  "project_id": "<PROJECT_ID>"
}

Show Virtual Models

post

Returns the virtual models of the key's project plus org-level ones, newest first. Any role (org owner, project admin, project member) can call it.

Authorizations

AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Body

org_idstringRequired

Must match the key's org.

project_idstringOptional

Optional. If sent, must exist (else 400 Project not found) and be the key's project (else 403). If omitted, returns the key's project's models plus org-level ones.

Responses

200

List of virtual models.

application/json

org_idstringOptional

project_idstringOptional

"NULL" for org-level models.

model_list_idstringOptional

model_list_namestringOptional

default_strategy_namestringOptional

model_provider_list_jsonbobject · nullableOptional

created_bystringOptional

created_onstring · date-timeOptional

updated_bystringOptional

updated_onstring · date-timeOptional

400

Bad Request. Includes: unknown strategy (default_strategy_name must be one of: ...), missing model_list_id on update/delete (model_list_id is required), wrong model_list_id (Virtual model not found for model_list_id: ...), unknown project_id (Project not found for org_id=..., project_id=...), model_list_id sent on create (model_list_id not allowed), unknown model (Invalid model 'x': model not found), or provider not serving the model (Invalid provider 'x' for model 'y').

application/json

401

Missing or invalid API key.

application/json

403

Forbidden. Includes: key from another org (API key does not belong to this organization), another project's model or project_id (API key does not belong to this project), or an org-level action without an org owner's key (API key must belong to an organization owner to perform this operation).

application/json

post/prod/showVirtualModels

POST /prod/showVirtualModels HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "org_id": "<ORG_ID>"
}

[
  {
    "org_id": "<ORG_ID>",
    "project_id": "<PROJECT_ID>",
    "model_list_id": "<MODEL_LIST_ID>",
    "model_list_name": "frontier-router-v2",
    "default_strategy_name": "priority_routing",
    "model_provider_list": [
      [
        "openai",
        "openai/gpt-5.1",
        "1"
      ],
      [
        "ALL",
        "anthropic/claude-4.5-sonnet",
        "2"
      ]
    ],
    "model_provider_list_jsonb": null,
    "created_by": "[e-mail]",
    "created_on": "2026-09-28T10:15:02.123456",
    "updated_by": "[e-mail]",
    "updated_on": "2026-09-28T10:20:41.654321"
  }
]

Update Virtual Model

post

Replaces a virtual model's name, strategy and entries. The full model_provider_list is sent each time; it is not merged with the old one. project_id is not needed — it comes from the saved virtual model, and a different project_id returns 400 (a model can't be moved to another project).

Access: project-level model — org owner or project admin. org-level model — org owner only.

Known issue: a project member's key calling update is rejected with 500 An internal error occurred instead of a 403.

Authorizations

AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Body

Replaces a virtual model's name, strategy and entries. The full model_provider_list is replaced, not merged with the old one.

org_idstringRequired

Must match the key's org.

model_list_idstringRequired

Must exist in the org, else 400 Virtual model not found. project_id is derived from the saved model and cannot be changed here.

model_list_namestringOptional

New name. The old name is read from the saved row, so old_model_list_name is not needed.

default_strategy_namestring · enumOptional

Hyphen forms (e.g. lowest-price) are accepted and stored with underscores.

Example: random_shufflePossible values:

Responses

200

Virtual model updated.

application/json

model_list_idstringOptionalExample: b7248b2e-bb43-11f1-9932-de4251ea43fc

model_list_namestringOptional

project_idstring · nullableOptional

400

Bad Request. Includes: unknown strategy (default_strategy_name must be one of: ...), missing model_list_id on update/delete (model_list_id is required), wrong model_list_id (Virtual model not found for model_list_id: ...), unknown project_id (Project not found for org_id=..., project_id=...), model_list_id sent on create (model_list_id not allowed), unknown model (Invalid model 'x': model not found), or provider not serving the model (Invalid provider 'x' for model 'y').

application/json

401

Missing or invalid API key.

application/json

403

Forbidden. Includes: key from another org (API key does not belong to this organization), another project's model or project_id (API key does not belong to this project), or an org-level action without an org owner's key (API key must belong to an organization owner to perform this operation).

application/json

post/prod/updateVirtualModel

POST /prod/updateVirtualModel HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 241

{
  "org_id": "<ORG_ID>",
  "model_list_id": "<MODEL_LIST_ID>",
  "model_list_name": "frontier-router-v2",
  "default_strategy_name": "priority_routing",
  "model_provider_list": [
    [
      "openai",
      "openai/gpt-5.1",
      1
    ],
    [
      "All Providers",
      "anthropic/claude-4.5-sonnet",
      2
    ]
  ]
}

{
  "model_list_id": "<MODEL_LIST_ID>",
  "model_list_name": "frontier-router-v2",
  "project_id": "<PROJECT_ID>"
}

Delete Virtual Model

post

Deletes a virtual model. Only an org owner's key can call it, and the model must be in the key's project or org-level. project_id is not needed.

Authorizations

AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Body

org_idstringRequired

Must match the key's org.

model_list_idstringRequired

Responses

200

Virtual model deleted.

application/json

model_list_idstringOptional

deletedbooleanOptional

400

Bad Request. Includes: unknown strategy (default_strategy_name must be one of: ...), missing model_list_id on update/delete (model_list_id is required), wrong model_list_id (Virtual model not found for model_list_id: ...), unknown project_id (Project not found for org_id=..., project_id=...), model_list_id sent on create (model_list_id not allowed), unknown model (Invalid model 'x': model not found), or provider not serving the model (Invalid provider 'x' for model 'y').

application/json

401

Missing or invalid API key.

application/json

403

Forbidden. Includes: key from another org (API key does not belong to this organization), another project's model or project_id (API key does not belong to this project), or an org-level action without an org owner's key (API key must belong to an organization owner to perform this operation).

application/json

post/prod/deleteVirtualModel

POST /prod/deleteVirtualModel HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "org_id": "<ORG_ID>",
  "model_list_id": "<MODEL_LIST_ID>"
}

{
  "model_list_id": "<MODEL_LIST_ID>",
  "deleted": true
}