List models — GET /v1/ai/mcp/models
Searches the model catalog — the one GET /v1/models lists, every OpenRouter model among it as last synced — by text, class, family, capability or free, and answers each match with its class, family, whether it is free, its list price (per token and per million; variable for a router billed at the answering model's price; a resold model's every vendor rate and conditional rate as billed), context window, output bound, expiry and capabilities.
GET /v1/ai/mcp/models
| Address | https://api.hanzo.ai/v1/ai/mcp/models |
| Method | GET |
| Operation | aiModels |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Searches the model catalog — the one GET /v1/models lists, every OpenRouter model among it as last synced — by text, class, family, capability or free, and answers each match with its class, family, whether it is free, its list price (per token and per million; variable for a router billed at the answering model's price; a resold model's every vendor rate and conditional rate as billed), context window, output bound, expiry and capabilities.
Request
7 fields.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | — | Q matches the model's id, name, description or owner, ignoring case. |
class | query | string | — | Class keeps one class: premium (third-party frontier models), ours (Hanzo's priced models) or free. |
family | query | string | — | Family keeps one Hanzo family: enso, zen, kai or zoo. |
capability | query | string | — | Capability keeps the models that have it: tools, vision or reasoning, or a modality they take or give (text, image, audio, file, video, decision). |
free | query | boolean | — | Free keeps the models a call to which bills nothing (bounded by the free allowances instead of a balance). |
zdr | query | boolean | — | ZDR keeps only models eligible for Zero Data Retention (excludes free and data-shared routes). |
limit | query | integer | — | Limit is the most models to answer, 1 to 500; 0 answers 50. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | aiModels | ok |
default | problem-details | refused |
200 body — 24 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
models | body | aiModel[] | — | Models are the matches, in the catalog's order. |
models[].capabilities | body | string[] | — | Capabilities are tools, vision and reasoning, those the model supports. |
models[].class | body | string | — | Class is premium, ours or free. |
models[].context_window | body | integer (int64) | — | ContextWindow is the most tokens the model reads at once, absent when the catalog does not say. |
models[].expires | body | string | — | Expires is the day the model's vendor stops serving it (2006-01-02), absent when it states none. |
models[].family | body | string | — | Family is the Hanzo family (enso, zen, kai, zoo), absent for a third-party model. |
models[].free | body | boolean | — | Free is whether a call bills nothing. |
models[].id | body | string | — | ID is the model's id, the one a completion or a decision names. |
models[].inputs | body | string[] | — | Inputs are the modalities the model reads. |
models[].max_output_tokens | body | integer (int64) | — | MaxOutputTokens is the most one answer may hold, absent when the catalog does not say. |
models[].name | body | string | — | Name is the model's display name. |
models[].outputs | body | string[] | — | Outputs are the modalities the model writes. |
models[].pricing | body | aiPrice | — | |
models[].pricing.completion | body | string | — | Completion is the price of one output token, a decimal string. |
models[].pricing.input_per_million | body | number (double) | — | InputPerMillion is the price of a million input tokens. |
models[].pricing.output_per_million | body | number (double) | — | OutputPerMillion is the price of a million output tokens. |
models[].pricing.overrides | body | object[] | — | Overrides are the vendor's conditional rates as billed, each with its condition: min_prompt_tokens, or utc_start, utc_end and utc_days. |
models[].pricing.overrides[].* | body | any | — | |
models[].pricing.prompt | body | string | — | Prompt is the price of one input token, a decimal string. |
models[].pricing.rates | body | object | — | Rates is every rate a resold model's vendor states, in the vendor's names and units (USD per token for prompt, completion, input_cache_read, input_cache_write, internal_reasoning; per request; per search for web_search), as billed: the vendor's rate times our margin, exact. |
models[].pricing.rates.* | body | string | — | |
models[].pricing.variable | body | boolean | — | Variable is true for a router that bills each answer at the price of the model that gave it; the figures above are then that router's ceiling. |
models[].zdr | body | boolean | — | ZDR is whether the model is eligible for Zero Data Retention (non-free, non-data-shared commercial route). |
total | body | integer (int64) | — | Total is how many models matched, before Limit. |
Failure carries the platform error shape — see Errors.
Examples
hanzo ai mcp modelsimport { Configuration, AiApi } from 'hanzoai';
const api = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.aiModels();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AiApi(client).ai_models()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.AiAPI.AiModels(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, ai_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = ai_api::ai_models(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AiApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new AiApi(client).aiModels();curl https://api.hanzo.ai/v1/ai/mcp/models \
-H "Authorization: Bearer $HANZO_API_KEY"Tool ai, op aiModels — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "ai",
"arguments": {
"op": "aiModels",
"input": {}
}
}
}'