Models

Endpoint

GET https://api.bve.me/v1/models

Requires Authorization: Bearer sk-bve-YOUR_KEY.

This endpoint mirrors the live Fuelix /models catalog for the API account configured behind BVE Gateway. The response follows the OpenAI models list format, then adds BVE annotations describing endpoint compatibility and current gateway availability.

Query parameters

Parameter	Type	Description
search	string	Case-insensitive substring filter on model ID. Returns only models whose ID contains the term. Length 1–200.
category	string	Filter by capability type. One of: chat, embedding, image, tts, transcription, ocr.
endpoint	string	Filter to models that support a specific gateway path. Accepted values: /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/responses, /v1/messages, /v1/images/generations, /v1/images/edits, /v1/audio/speech, /v1/audio/transcriptions. Models without a known endpoint mapping (D1-only custom models) are excluded when this filter is active.
provider	string	Filter by the bve_provider label on each row. Canonical values include anthropic, cohere, cursor, deepseek, google, meta, mistral, openai, and wasikan, but live Fuelix rows can expose additional lowercase provider slugs from owned_by. Safe unknown slugs return an empty list; malformed slugs return 400 invalid_value. D1-only custom models are excluded when this filter is active.
reasoning	string	Filter by reasoning capability. true returns only reasoning models (o3, o3-mini, o4-mini and dated variants); false returns only non-reasoning models. Any other value returns 400 invalid_value.
vision	string	Filter by vision capability. true returns only models that accept image inputs (e.g. gpt-4o, claude-sonnet-4, gemini-2.0-flash); false returns only models that do not accept images. Any other value returns 400 invalid_value.
web_search	string	Filter by native web search capability. true returns only models that natively support the web_search_options parameter (gpt-4o-search-preview, gpt-4.1, gpt-4.1-mini, and dated variants); false returns only models without native web search. Any other value returns 400 invalid_value.
audio_input	string	Filter by audio input capability. true returns only models that accept audio content blocks as input in POST /v1/chat/completions (e.g. gpt-4o-audio-preview, gpt-4o-mini-audio-preview, and dated variants); false returns only models that do not accept inline audio. Distinct from TTS models (bve_category: tts) and STT models (bve_category: transcription). Any other value returns 400 invalid_value.
tool_use	string	Filter by function calling support. true returns only models that accept the tools parameter in POST /v1/chat/completions; false returns models that do not (embedding, TTS, STT, image-generation, and legacy completion-only models). Any other value returns 400 invalid_value.
json_mode	string	Filter by JSON mode / structured output support. true returns only models that support "response_format": { "type": "json_object" } or structured output in chat completions; false returns models that do not. Any other value returns 400 invalid_value.
thinking	string	Filter by extended thinking support. true returns only models that support the thinking parameter for extended thinking in POST /v1/messages (Anthropic Claude Sonnet 4 and Haiku 4.5 families); false returns models that do not. Any other value returns 400 invalid_value.
computer_use	string	Filter by computer use tool support. true returns only models that support Anthropic’s built-in computer use tool types (computer_20241022, text_editor_20241022, bash_20241022, web_search_20250305) in POST /v1/messages; false returns models that do not. Any other value returns 400 invalid_value.
sort_by	string	Sort the returned list. id sorts alphabetically by model ID; created sorts by Unix creation timestamp ascending. Omit to preserve the upstream registration order. Any other value returns 400 invalid_value.
sort_dir	string	Sort direction. asc (default) or desc. Only meaningful when sort_by is also set; accepted but ignored without it. Any other value returns 400 invalid_value.
limit	integer	Maximum number of models to return after all other filters and sorting are applied. Must be between 1 and 200. Any other value returns 400 invalid_value.

All parameters are optional and combinable. For provider, the gateway accepts lowercase provider slugs that match the bve_provider field; safe-but-absent slugs return an empty list rather than a validation error.

# Only chat models
curl "https://api.bve.me/v1/models?category=chat" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# GPT-4 family only
curl "https://api.bve.me/v1/models?search=gpt-4" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# All models usable with /v1/chat/completions
curl "https://api.bve.me/v1/models?endpoint=/v1/chat/completions" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# All models usable with /v1/embeddings
curl "https://api.bve.me/v1/models?endpoint=/v1/embeddings" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# All Anthropic models
curl "https://api.bve.me/v1/models?provider=anthropic" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# All Google models
curl "https://api.bve.me/v1/models?provider=google" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Combined: embedding models containing "ada"
curl "https://api.bve.me/v1/models?category=embedding&search=ada" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Combined: GPT models that support the Responses API
curl "https://api.bve.me/v1/models?search=gpt&endpoint=/v1/responses" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Combined: OpenAI chat models
curl "https://api.bve.me/v1/models?provider=openai&category=chat" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only reasoning models (o3, o3-mini, o4-mini variants)
curl "https://api.bve.me/v1/models?reasoning=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only reasoning models from OpenAI
curl "https://api.bve.me/v1/models?reasoning=true&provider=openai" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only vision-capable models
curl "https://api.bve.me/v1/models?vision=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Vision-capable chat models only
curl "https://api.bve.me/v1/models?vision=true&category=chat" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Vision-capable models from Anthropic
curl "https://api.bve.me/v1/models?vision=true&provider=anthropic" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only web-search-capable models (gpt-4o-search-preview, gpt-4.1 family)
curl "https://api.bve.me/v1/models?web_search=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models without native web search
curl "https://api.bve.me/v1/models?web_search=false" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Web-search models that also accept images (vision + web search)
curl "https://api.bve.me/v1/models?web_search=true&vision=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that accept audio input in chat completions (gpt-4o-audio-preview family)
curl "https://api.bve.me/v1/models?audio_input=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that do NOT accept audio input (excludes gpt-4o-audio-preview family)
curl "https://api.bve.me/v1/models?audio_input=false" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Audio-input chat models from OpenAI
curl "https://api.bve.me/v1/models?audio_input=true&provider=openai" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that support function calling (tools parameter)
curl "https://api.bve.me/v1/models?tool_use=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that do NOT support function calling (embedding, TTS, STT, image-gen)
curl "https://api.bve.me/v1/models?tool_use=false" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Tool-use models from Anthropic
curl "https://api.bve.me/v1/models?tool_use=true&provider=anthropic" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that support JSON mode / structured output
curl "https://api.bve.me/v1/models?json_mode=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# OpenAI models that support JSON mode
curl "https://api.bve.me/v1/models?json_mode=true&provider=openai" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that support extended thinking (Anthropic claude-sonnet-4 / haiku-4.5 families)
curl "https://api.bve.me/v1/models?thinking=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Models that support both extended thinking and computer use
curl "https://api.bve.me/v1/models?thinking=true&computer_use=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Only models that support Anthropic computer use built-in tools
curl "https://api.bve.me/v1/models?computer_use=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Computer-use-capable models that also accept vision input
curl "https://api.bve.me/v1/models?computer_use=true&vision=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# All models sorted alphabetically by ID
curl "https://api.bve.me/v1/models?sort_by=id" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Five newest models (most recently registered in Fuelix)
curl "https://api.bve.me/v1/models?sort_by=created&sort_dir=desc&limit=5" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Top 10 OpenAI chat models alphabetically
curl "https://api.bve.me/v1/models?provider=openai&category=chat&sort_by=id&limit=10" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

Invalid category, endpoint, provider, reasoning, vision, web_search, audio_input, tool_use, json_mode, thinking, computer_use, sort_by, sort_dir, or out-of-range limit values, or an empty/too-long search value, return 400 invalid_value:

{
  "error": {
    "message": "category: must be one of: chat, embedding, image, ocr, transcription, tts",
    "type": "invalid_request_error",
    "param": "category",
    "code": "invalid_value"
  }
}

{
  "error": {
    "message": "endpoint: must be one of: /v1/chat/completions, /v1/completions, /v1/embeddings, ...",
    "type": "invalid_request_error",
    "param": "endpoint",
    "code": "invalid_value"
  }
}

{
  "error": {
    "message": "provider: must be a lowercase provider slug (2-32 chars, letters, numbers, '_' or '-')",
    "type": "invalid_request_error",
    "param": "provider",
    "code": "invalid_value"
  }
}

Response

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1715367049,
      "owned_by": "openai",
      "bve_available": true,
      "bve_availability": "callable",
      "bve_category": "chat",
      "bve_endpoints": ["/v1/chat/completions", "/v1/completions", "/v1/responses"],
      "bve_provider": "openai",
      "bve_reasoning": false,
      "bve_vision": true,
      "bve_web_search": false,
      "bve_audio_input": false,
      "bve_tool_use": true,
      "bve_json_mode": true,
      "bve_thinking": false,
      "bve_computer_use": false
    }
  ]
}

Each model entry includes thirteen BVE-injected fields:

• bve_available — true when the gateway currently considers the model routable on the live Fuelix account after applying global D1 block policy; false when the model is still visible in Fuelix /models but the gateway would reject requests for it
• bve_availability — one of:
  • callable — listed by Fuelix and routable by default
  • listed_unavailable — listed by Fuelix, but live account probes currently fail by default
  • registry_broken — intentionally marked broken in the gateway registry by default
  • unclassified — listed by Fuelix but not yet verified in the gateway’s live capability snapshot by default
• bve_category — the capability class of the model (chat, embedding, image, tts, transcription, ocr)
• bve_endpoints — the exact API paths this model can be called at (use these to route requests without guessing)
• bve_provider — the model creator/origin (anthropic, cohere, cursor, deepseek, google, meta, mistral, openai, wasikan)
• bve_reasoning — true for reasoning models (o3, o3-mini, o4-mini and dated variants) that accept reasoning_effort and max_reasoning_tokens; false for all other models
• bve_vision — true for models that accept image inputs in message content (e.g. image_url content blocks); false for text-only models. Image-generation models (imagen-*, gemini-*-image) are false — they produce images rather than accept them as input
• bve_web_search — true for models with native web_search_options support (gpt-4o-search-preview, gpt-4o-mini-search-preview, and the gpt-4.1 family including gpt-4.1-mini and gpt-4.1-nano); false for all other models. Use ?web_search=true to filter the model list to only these models
• bve_audio_input — true for models that accept audio content blocks (input_audio type) as inline input in POST /v1/chat/completions messages (gpt-4o-audio-preview and gpt-4o-mini-audio-preview families); false for all other models. Distinct from TTS models (which generate audio) and STT models (which transcribe audio files at /v1/audio/transcriptions). Use ?audio_input=true to filter the model list to only these models
• bve_tool_use — true for models that accept the tools array parameter for function calling in POST /v1/chat/completions; false for embedding, TTS, STT, image-generation, and legacy completion-only models. Use ?tool_use=true to get only function-calling-capable models, or ?tool_use=false to get non-chat models
• bve_json_mode — true for models that support "response_format": { "type": "json_object" } or structured output (json_schema) in chat completions; false for embedding, TTS, STT, image-generation, and models that do not accept JSON output constraints. Use ?json_mode=true to filter to only JSON-capable models
• bve_thinking — true for models that support the thinking parameter for extended thinking in POST /v1/messages (Anthropic Claude Sonnet 4, Claude Haiku 4.5, and later variants); false for all other models. Use ?thinking=true to get only extended-thinking-capable models
• bve_computer_use — true for models that support Anthropic’s built-in computer use tool types (computer_20241022, text_editor_20241022, bash_20241022, web_search_20250305) without a custom input_schema in POST /v1/messages. Applies to Claude Sonnet 4+ and Haiku 4.5+ models; Cursor-branded wrappers are excluded. Use ?computer_use=true to filter to only computer-use-capable models

bve_endpoints by model family

bve_category	Model family	bve_endpoints
chat	GPT / O-series (gpt-*, o3, o4-mini)	["/v1/chat/completions", "/v1/completions", "/v1/responses"]
chat	Claude / Gemini (claude-*, gemini-*, gemma-*)	["/v1/chat/completions", "/v1/completions", "/v1/messages"]
chat	Groq / Llama / Cohere / Mistral	["/v1/chat/completions", "/v1/completions"]
embedding	OpenAI / Cohere / Gemini embeddings	["/v1/embeddings"]
image	Imagen / Gemini image models	["/v1/images/generations", "/v1/images/edits"]
tts	tts-1, tts-1-hd	["/v1/audio/speech"]
transcription	Whisper / gpt-4o-transcribe* families	["/v1/audio/transcriptions"]
ocr	mistral-ocr	["/v1/chat/completions"]

Legacy completion-only base models (gpt-3.5-turbo-instruct, babbage-002, davinci-002) return bve_endpoints: ["/v1/completions"] only — they do not support the chat completions API.

bve_provider by model creator

bve_provider	Model prefix patterns
openai	gpt-*, o3, o3-*, o4-*, tts-*, whisper-*, distil-whisper-*, text-embedding-*, dall-e-*, gpt-image-*, babbage-*, davinci-*
anthropic	claude-*, c-* (e.g. c-haiku-4-5 aliases)
google	gemini-*, gemma-*, gemma2-*, translategemma-*, imagen-*
cohere	command-*, embed-*
deepseek	deepseek-*
meta	llama-*
mistral	mistral-*, mixtral-*
cursor	cursor-c-* (Cursor-branded Claude wrappers)
wasikan	wasikan-*

bve_provider refers to the model creator, not the hosting infrastructure — Fuelix routes all models regardless of origin. D1-only custom models that don’t match a known prefix omit bve_provider and are excluded from ?provider= filtered results.

/v1/completions for chat models

All chat models include /v1/completions in bve_endpoints via the completions emulation layer: the gateway translates legacy POST /v1/completions requests into POST /v1/chat/completions upstream and transforms the response to text_completion format. Streaming (stream: true) is supported — SSE chunks use object: "text_completion" format.

Fuelix-listed models that do not yet have a usable gateway capability snapshot remain visible in the list with bve_availability: "unclassified". As long as Fuelix still lists them and no explicit global block exists, the gateway now routes them by default. Live Fuelix models without a matching gateway registry entry may still omit bve_category or bve_endpoints until the local snapshot is updated.

Supported endpoints

The gateway exposes and maintains the following confirmed working endpoints:

• GET /v1/models — List live Fuelix models (filtered per-key and per global allowlist policy, with gateway availability annotations)
• GET /v1/models/:id — Get a single model by ID
• POST /v1/chat/completions — Chat completions (SSE streaming; NDJSON for Gemini)
• POST /v1/completions — Legacy text completions (emulated via chat; streaming not supported)
• POST /v1/embeddings — Embedding generation
• POST /v1/responses — OpenAI Responses API; GET/DELETE /v1/responses/:id
• POST /v1/messages — Anthropic Messages API (Anthropic response format); GET /v1/messages/:id
• POST /v1/images/generations — Image generation (with empty-data retry guard)
• POST /v1/images/edits — Image editing (multipart/form-data)
• POST /v1/audio/speech — Text-to-speech (binary audio stream)
• POST /v1/audio/transcriptions — Speech-to-text transcription (multipart/form-data)
• Files API — GET/POST /v1/files; GET/DELETE /v1/files/:id; GET /v1/files/:id/content
• Assistants API — GET/POST /v1/assistants; full CRUD on /v1/assistants/:id and sub-resources
• Threads API — POST /v1/threads; full CRUD on /v1/threads/:id and sub-resources
• Vector Stores API — GET/POST /v1/vector_stores; full CRUD on /v1/vector_stores/:id

Unsupported endpoints

The following are not available. Requests to these paths return 404 route_not_found:

• GET /v1/batches (Batches) — not supported by Fuelix
• native Gemini /v1beta/* — use Gemini models via /v1/chat/completions
• native Cohere /v1/chat, /v2/chat, /v1/embed, /v2/embed — use Cohere models via BVE endpoints
• native OpenRouter /api/v1/*
• native Mistral /v1/fim/completions, /v1/agents/completions
• /openai/v1/chat/completions

Gateway capability categories

The gateway maintains a capability registry for annotation and endpoint validation. The lists below describe that registry, not the exact live Fuelix account snapshot returned by GET /v1/models. Use the live model list as the source of truth for what the current account actually exposes.

Models are categorized under six capability types, strictly enforced per endpoint:

1. Chat models

Exposed on POST /v1/chat/completions (and optionally /v1/messages / /v1/responses if enabled with keys):

• c-haiku-4-5
• claude-3-5-haiku
• claude-3-5-haiku-20241022
• claude-4-sonnet
• claude-haiku-4
• claude-haiku-4-5
• claude-haiku-4-5-20251001
• claude-haiku-4-5-bedrock
• claude-sonnet-4
• claude-sonnet-4-20250514
• claude-sonnet-4-5
• claude-sonnet-4-5-20250929
• claude-sonnet-4-5-bedrock
• claude-sonnet-4-6
• claude-sonnet-4-legacy
• command-a-03-2025
• command-r
• command-r-08-2024
• command-r-plus
• command-r-plus-08-2024
• command-r7b-12-2024
• cursor-c-4-sonnet
• cursor-c-sonnet-4-6
• gemini-2.0-flash
• gemini-2.0-flash-001
• gemini-2.5-flash
• gemini-2.5-flash-lite
• gemini-2.5-pro
• gemini-3-flash
• gemini-3-flash-preview
• gemini-3-pro
• gemini-3-pro-preview
• gemini-3.1-flash-lite
• gemini-3.1-flash-lite-preview
• gemini-3.1-pro
• gemini-3.1-pro-preview
• gemini-3.5-flash
• gemma-4-26b-a4b-it
• gemma-4-31b-it
• gemma2-9b-it
• gpt-4.1
• gpt-4.1-2025-04-14
• gpt-4.1-mini
• gpt-4.1-mini-2025-04-14
• gpt-4.1-mini-canada
• gpt-4.1-nano
• gpt-4.1-nano-2025-04-14
• gpt-4o
• gpt-4o-2024-05-13
• gpt-4o-2024-08-06
• gpt-4o-2024-11-20
• gpt-4o-audio-preview
• gpt-4o-audio-preview-2024-10-01
• gpt-4o-audio-preview-2024-12-17
• gpt-4o-mini
• gpt-4o-mini-2024-07-18
• gpt-4o-mini-audio-preview
• gpt-4o-mini-audio-preview-2024-12-17
• gpt-4o-mini-search-preview
• gpt-4o-mini-search-preview-2025-03-01
• gpt-4o-search-preview
• gpt-4o-search-preview-2025-03-11
• gpt-5
• gpt-5-2025-08-07
• gpt-5-chat
• gpt-5-chat-2025-08-07
• gpt-5-mini
• gpt-5-mini-2025-08-07
• gpt-5-nano
• gpt-5-nano-2025-08-07
• gpt-5.2
• gpt-5.2-2025-12-11
• gpt-5.2-chat
• gpt-5.2-chat-2025-12-11
• gpt-5.4
• gpt-5.4-2026-03-05
• gpt-5.4-mini
• gpt-5.4-nano
• gpt-oss-20b
• llama-3.1-70b-versatile
• llama-3.1-8b-instant
• llama-3.2-11b-vision-preview
• llama-3.2-1b-preview
• llama-3.2-3b-preview
• llama-3.3-70b-specdec
• llama-3.3-70b-versatile
• llama-4-maverick-17b-128e
• llama-4-scout-17b-16e
• mistral-large
• mistral-large-24.02
• mixtral-8x7b-32768
• o3
• o3-mini
• o4-mini

2. Embedding models

Exposed on POST /v1/embeddings only:

• embed-english-light-v3.0
• embed-english-v3.0
• embed-multilingual-light-v3.0
• embed-multilingual-v3.0
• gemini-embedding-001
• text-embedding-3-large
• text-embedding-3-small
• text-embedding-ada-002

3. Image models

Exposed on POST /v1/images/generations and POST /v1/images/edits:

• gemini-3.1-flash-image
• imagen-3
• imagen-3-fast
• imagen-4
• imagen-4-ultra

4. TTS models

Exposed on POST /v1/audio/speech only:

• tts-1
• tts-1-hd

5. Transcription models

Exposed on POST /v1/audio/transcriptions only:

• distil-whisper-large-v3-en
• gpt-4o-mini-transcribe
• gpt-4o-transcribe
• gpt-4o-transcribe-2025-03-20
• gpt-4o-transcribe-diarize
• gpt-4o-transcribe-diarize-2025-03-20
• whisper-1
• whisper-large-v3
• whisper-large-v3-turbo

6. OCR model (special case)

Exposed as a specialized OCR capability model:

• mistral-ocr

Note: Fuelix does not host a dedicated OCR endpoint. mistral-ocr responds through chat-compatible routing and is strictly mapped to POST /v1/chat/completions. Using it on non-chat endpoints returns a mismatch error.

Embedding model guard

The gateway enforces a capability check for embedding models. Sending an embedding model to any endpoint other than /v1/embeddings returns a 400 error immediately:

{
  "error": {
    "message": "Model 'text-embedding-3-large' does not support endpoint '/v1/chat/completions' (embedding model, use POST /v1/embeddings instead)",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_endpoint_mismatch"
  }
}

TTS model guard

Text-to-speech models (tts-1, tts-1-hd) can only be used with POST /v1/audio/speech. Sending them elsewhere returns a 400 immediately:

{
  "error": {
    "message": "Model 'tts-1' does not support endpoint '/v1/chat/completions' (text-to-speech model, use POST /v1/audio/speech instead)",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_endpoint_mismatch"
  }
}

STT model guard

Transcription models (whisper-1, gpt-4o-transcribe* families) can only be used with POST /v1/audio/transcriptions. Sending them elsewhere returns a 400 immediately:

{
  "error": {
    "message": "Model 'whisper-1' does not support endpoint '/v1/chat/completions' (speech-to-text model, use POST /v1/audio/transcriptions instead)",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_endpoint_mismatch"
  }
}

Image model guard

Image models can only be used with POST /v1/images/generations or POST /v1/images/edits. Sending them elsewhere returns a 400 immediately:

{
  "error": {
    "message": "Model 'imagen-3' does not support endpoint '/v1/chat/completions' (image generation model, use POST /v1/images/generations instead)",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_endpoint_mismatch"
  }
}

All capability guards fire after the model availability and per-key allowlist checks. See Errors for a full list of model error codes.

Response headers

BVE Gateway adds the following headers to every /v1/models response:

Header	Example	Description
X-Request-Id	550e8400-…	UUID for this request
X-BVE-Latency	48	Total gateway latency in milliseconds
X-BVE-Cache	HIT	Model list cache status — see Model list caching

Model list caching

BVE Gateway caches the Fuelix model list in-memory using a Stale-While-Revalidate (SWR) strategy. The X-BVE-Cache response header tells you whether your request was served from cache or fetched fresh.

Value	Description
HIT	Served from a fresh in-memory cache entry (data is less than 4 minutes old)
STALE	Served from a stale cache entry (between 4 and 5 minutes old); a background refresh is already in progress
MISS	Cache was empty or expired; fetched fresh from Fuelix upstream

Cache TTLs:

• Soft TTL: 4 minutes — within this window, every request gets HIT
• Hard TTL: 5 minutes — between 4–5 minutes, requests get STALE and a background refresh is triggered via waitUntil; after 5 minutes, the entry is evicted and the next request gets MISS

The cache is per-isolate. Because Cloudflare Workers may run in multiple isolates simultaneously, you can observe different X-BVE-Cache values from concurrent requests in different isolates.

Note

X-BVE-Cache is only present on GET /v1/models responses. All other endpoints omit this header.

# Inspect the cache status without the full response body
curl -s -I https://api.bve.me/v1/models \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  | grep -i x-bve-cache
# X-BVE-Cache: HIT

cURL example

curl https://api.bve.me/v1/models \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

SDK examples

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

const models = await client.models.list();
for (const model of models.data) {
  console.log(model.id);
}

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

models = client.models.list()
for model in models.data:
    print(model.id)

Retrieve a single model

GET https://api.bve.me/v1/models/:id

Returns a single model object. The response includes the same capability annotations as the list endpoint for models in the static registry: bve_category, bve_endpoints, bve_provider, bve_reasoning, bve_vision, bve_web_search, bve_audio_input, bve_tool_use, bve_json_mode, bve_thinking, and bve_computer_use. Like the list endpoint, successful detail responses also include bve_available and bve_availability so clients can read the effective routability boolean and the underlying live registry/snapshot state from the same payload.

curl https://api.bve.me/v1/models/gpt-4o \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

Response:

{
  "id": "gpt-4o",
  "object": "model",
  "created": 1715367049,
  "owned_by": "openai",
  "bve_available": true,
  "bve_availability": "callable",
  "bve_category": "chat",
  "bve_endpoints": ["/v1/chat/completions", "/v1/completions", "/v1/responses"],
  "bve_provider": "openai",
  "bve_reasoning": false,
  "bve_vision": true,
  "bve_web_search": false,
  "bve_audio_input": false,
  "bve_tool_use": true,
  "bve_json_mode": true,
  "bve_thinking": false,
  "bve_computer_use": false
}

Models registered only in D1 (via the admin model allowlist) still include bve_available and bve_availability, but are returned without bve_category, bve_endpoints, or bve_provider when their type cannot be determined from the static registry. Unlike GET /v1/models, the detail endpoint stays strict: if Fuelix lists a model but the gateway currently marks it unavailable, GET /v1/models/:id returns 403 model_not_available instead of returning a 200 response with bve_available: false.

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

const model = await client.models.retrieve('gpt-4o');
console.log(model.id, model.owned_by);

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

model = client.models.retrieve("gpt-4o")
print(model.id, model.owned_by)

Notes

• Model availability is determined by both the live Fuelix catalog and BVE Gateway’s current availability policy. GET /v1/models can surface Fuelix-listed models with bve_availability: "unclassified" even before the local capability snapshot is refreshed. Those rows remain routable by default as long as Fuelix still lists them and no explicit global block exists.
• bve_available is the effective routing boolean after D1 global block policy is applied. bve_availability remains the underlying default registry/snapshot state. Live Fuelix-listed rows with bve_availability: "unclassified" can therefore appear with bve_available: true, while listed_unavailable and registry_broken rows remain blocked.
• The allowed_models field is enforced by the gateway at request time. If a key has allowed_models set, requests for any model not in that list are rejected with 403 model_not_allowed before reaching Fuelix. A null or empty allowlist removes only the per-key filter; global D1 blocks and live availability checks still apply. See API Keys for how to restrict a key to specific models.
• The model list is filtered per-key: a key with allowed_models: ["gpt-4o"] only sees gpt-4o in its GET /v1/models response. A key with allowed_models: null or [] sees every non-globally-blocked model from the live Fuelix catalog, including entries with bve_available: false. Globally blocked models (via POST /admin/model-allowlist with enabled: false) are excluded from all responses. See Model Allowlist for details.
• A live Fuelix model can appear in GET /v1/models with bve_available: false. That means Fuelix lists it, but the gateway would still reject direct requests with 403 model_not_available based on the current live-account or registry snapshot.

Next steps

Chat Completions Use a chat or reasoning model to generate completions via POST /v1/chat/completions

Embeddings Generate text embeddings for semantic search and RAG using an embedding model

Admin API: Model Allowlist Globally block or enable models across all keys

Admin API: API Keys Restrict individual keys to specific model IDs via allowed_models