Search Models API¶

Discover the models this deployment serves and what each one can do, from the catalogue the gateway builds out of Amazon Bedrock, Comprehend, Polly and Transcribe. Native route, served without a dialect prefix.

At a glance¶

• Eight filters, combined with AND — modality in and out, route or MCP tool name, region, streaming, Batch API, wildcard pattern, legacy status.
• The ID to send next — every result carries id, its aliases, supported_routes, supported_mcp_tools, regions and per-region inference_profiles.
• Built for agents — published as the search_models MCP tool, and route accepts the MCP tool name an agent means to call next, so it never has to know the HTTP path.
• Richer than the dialect model lists — openai_model_list and anthropic_model_list return names and dates; this returns capabilities.
• Differs from those lists: deprecated models are excluded unless legacy=true, and batch is a best-effort hint that never rejects a request — see Limits and behaviour to know.

export BASE="https://your-host"  # native routes carry no dialect prefix

curl -G "$BASE/search_models" \
  --data-urlencode "route=openai_chat_completion" \
  -H "Authorization: Bearer $API_KEY"

Endpoints¶

How It Works¶

All query parameters are optional. Parameters combine with AND logic — only models matching every supplied filter are returned. Results are sorted by model ID, except that a model filter sorts its matches newest first instead — see the note below. With no filters, every active (non-legacy) model is returned (see the legacy note below for deprecated-model lookups).

Agent workflow: call search_models first to obtain the correct model ID, then pass it to the target endpoint. To compare costs before picking, pass the shortlisted IDs to the Model Pricing API.

Query Parameters¶

Response Fields¶

Each item in the returned list is a ModelDetails object:

The response is a bare JSON array of these objects — no envelope, no pagination:

[
  {
    "id": "anthropic.claude-sonnet-4-5-20250929-v1:0",
    "name": "Claude Sonnet 4.5",
    "provider": "Anthropic",
    "service": "AWS Bedrock Runtime",
    "input_modalities": ["TEXT", "IMAGE"],
    "output_modalities": ["TEXT"],
    "aliases": ["claude-sonnet-4-5", "claude-sonnet-4-5-20250929"],
    "supported_routes": ["/v1/chat/completions", "/v1/responses", "/v1/messages"],
    "supported_mcp_tools": ["openai_chat_completion", "openai_response", "anthropic_message"],
    "regions": ["us-east-1", "us-west-2"],
    "inference_profiles": {"us-east-1": "us.anthropic.claude-sonnet-4-5-20250929-v1:0"},
    "response_streaming": true,
    "batch": true
  }
]

Fields with nothing to report are omitted, so a model with no alias carries no aliases key.

Using search_models as an MCP Tool¶

When MCP is enabled, search_models is exposed as an MCP tool under the same name. AI agents should call it before any other tool to identify which model ID to use.

The route parameter accepts either format — agents can pass the MCP tool name they intend to call next without needing to know the corresponding HTTP path:

{
  "tool": "search_models",
  "arguments": {
    "route": "openai_chat_completion"
  }
}

This is the preferred tool for model discovery — it returns richer metadata than openai_model_list or anthropic_model_list and supports capability-based filtering so agents can select the most appropriate model for their task.

Status Codes¶

Limits and behaviour to know¶

Deprecated models are excluded unless you ask for them. legacy=true returns deprecated models only, not the active ones plus the deprecated ones; run both calls to see the whole catalogue.

batch is advertised on a best-effort basis and never rejects a request. A model with batch: false, or with no batch field, may still run a batch: the authoritative answer is what the backend returns when you submit one. Treat it as a shortlist to start from.

An unrecognised filter value is a 400, an unmatched combination is a 200. A typo in a modality name, an unknown route or MCP tool name, or a region where no model is available, are refused; a valid combination that matches nothing returns an empty array.

service is not comparable with the model_pricing field of the same name. This one carries display names (AWS Bedrock Runtime); model_pricing carries AWS API endpoint identifiers (bedrock-runtime).

A model filter changes the sort order. Results are sorted by model ID, except with a model filter, which sorts its matches newest first by release date, models of unknown release date last.

Request headers¶

Try it¶

The curl examples below use a $BASE variable set to your scheme and host — native routes such as /search_models are not prefixed:

export BASE="https://your-host"

All models accepting TEXT input:

curl -G "$BASE/search_models" \
  --data-urlencode "input_modalities=TEXT" \
  -H "Authorization: Bearer $API_KEY"

Image-generation capable models — route path or MCP tool name, both work:

# Using the API route path
curl -G "$BASE/search_models" \
  --data-urlencode "route=/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY"

# Using the MCP tool name — same result
curl -G "$BASE/search_models" \
  --data-urlencode "route=openai_image_generation" \
  -H "Authorization: Bearer $API_KEY"

Active chat models (legacy models are excluded by default):

curl -G "$BASE/search_models" \
  --data-urlencode "route=openai_chat_completion" \
  -H "Authorization: Bearer $API_KEY"

Active streaming models in us-east-1:

curl -G "$BASE/search_models" \
  --data-urlencode "region=us-east-1" \
  --data-urlencode "streaming=true" \
  -H "Authorization: Bearer $API_KEY"

Chat models advertised for the Batch API:

curl -G "$BASE/search_models" \
  --data-urlencode "route=openai_chat_completion" \
  --data-urlencode "batch=true" \
  -H "Authorization: Bearer $API_KEY"

Everything a wildcard pattern matches, newest first:

curl -G "$BASE/search_models" \
  --data-urlencode "model=claude-sonnet-*" \
  -H "Authorization: Bearer $API_KEY"

Look up a deprecated model (see the legacy=true note above):

curl -G "$BASE/search_models" \
  --data-urlencode "route=openai_chat_completion" \
  --data-urlencode "legacy=true" \
  -H "Authorization: Bearer $API_KEY"

Next steps¶

Next: Model Pricing API · Models catalogue · MCP configuration · Model aliases and wildcards