cURL Examples

All examples use the base URL https://api.bve.me. Replace sk-bve-YOUR_KEY with your API key and admin_bve_YOUR_ADMIN_KEY with your admin key.

Public API

Health check

curl https://api.bve.me/health

Usage snapshot (self-service quota check)

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

Returns live RPM/RPD/monthly counters for your key — does not consume a request.

List models

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

List models — filtered

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

# Vision-capable models only (accept image inputs)
curl "https://api.bve.me/v1/models?vision=true" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

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

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

# Models that support /v1/embeddings
curl "https://api.bve.me/v1/models?endpoint=/v1/embeddings" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

# Search by name substring
curl "https://api.bve.me/v1/models?search=gpt-4o" \
  -H "Authorization: Bearer sk-bve-YOUR_KEY"

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

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

Chat completion (non-streaming)

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is 2 + 2?" }
    ]
  }'

Chat completion (streaming SSE)

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "stream": true,
    "messages": [{ "role": "user", "content": "Count from 1 to 5." }]
  }'

Chat completion with JSON response format

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "response_format": { "type": "json_object" },
    "messages": [{ "role": "user", "content": "Return a JSON object with keys name and age." }]
  }'

Chat completion with function calling (tools)

Models that support function calling (GPT-4o, Claude Sonnet, Gemini, and others) accept a tools array alongside the messages. When the model decides to invoke a function, the response contains a tool_calls array in the assistant message instead of, or in addition to, a content string.

Step 1 — send the request with tool definitions:

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "What is the weather in Paris?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "description": "City name" }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

The assistant responds with finish_reason: "tool_calls" and a tool_calls array. Call your function with the provided arguments, then send the result back as a tool-role message:

Step 2 — return the tool result:

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "What is the weather in Paris?" },
      {
        "role": "assistant",
        "tool_calls": [{
          "id": "call_abc123",
          "type": "function",
          "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
        }]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\"}"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "description": "City name" }
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'

To force the model to always call a specific function, use "tool_choice": { "type": "function", "function": { "name": "get_weather" } } instead of "auto". Use "tool_choice": "none" to disable tool calling entirely for a request.

Chat completion with audio output

Audio-capable models (such as gpt-4o-audio-preview) can generate spoken audio alongside or instead of text. Set modalities to include "audio" and provide an audio object with a voice ID and output format.

Available voices: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse. Available formats: mp3, opus, aac, flac, wav, pcm16, pcm24.

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-audio-preview",
    "modalities": ["text", "audio"],
    "audio": {
      "voice": "alloy",
      "format": "mp3"
    },
    "messages": [
      { "role": "user", "content": "Say hello in a friendly tone." }
    ]
  }'

The response includes an audio field in the assistant message with data (base64-encoded audio) and transcript (the spoken text). Pipe through jq to decode the audio directly to a file:

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-audio-preview",
    "modalities": ["text", "audio"],
    "audio": { "voice": "alloy", "format": "mp3" },
    "messages": [{ "role": "user", "content": "Say hello in a friendly tone." }]
  }' | jq -r '.choices[0].message.audio.data' | base64 -d > hello.mp3

To request only audio (no text in the response), set "modalities": ["audio"]. Omit "text" entirely when the caller will play the audio and does not need a transcript.

Chat completion with image input (vision)

Vision-capable models (gpt-4o, gpt-4.1, Claude Sonnet, Gemini, and others) accept image content in user messages. Pass an array of typed content blocks instead of a plain string:

# Image from an HTTPS URL
curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What does this chart show?" },
          { "type": "image_url", "image_url": { "url": "https://example.com/sales-chart.png" } }
        ]
      }
    ]
  }'

# Control resolution with detail: "low" (faster/cheaper) or "high" (full detail; default)
curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Read all text in this screenshot." },
          { "type": "image_url", "image_url": { "url": "https://example.com/screenshot.png", "detail": "high" } }
        ]
      }
    ]
  }'

# Inline base64-encoded image (data: URL)
curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this image." },
          { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQ..." } }
        ]
      }
    ]
  }'

Find vision-capable models with ?vision=true — see List models — filtered above. See Vision and multimodal content for full validation rules, SDK examples, and audio input.

Reasoning and extended thinking

BVE Gateway supports three distinct reasoning/thinking mechanisms depending on the model family. All are validated before the request reaches Fuelix.

o-series models — reasoning_effort (o3, o3-mini, o4-mini and dated variants):

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o4-mini",
    "messages": [{ "role": "user", "content": "Prove that there are infinitely many prime numbers." }],
    "reasoning_effort": "high"
  }'

Valid values: "low" (fastest), "medium" (balanced), "high" (maximum), "auto" (model decides).

o-series models — max_reasoning_tokens (explicit token budget):

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o3",
    "messages": [{ "role": "user", "content": "What is the time complexity of merge sort?" }],
    "max_reasoning_tokens": 4096
  }'

max_reasoning_tokens caps internal reasoning token use. Set to 0 to disable extended reasoning entirely. Combine with reasoning_effort if supported.

Claude extended thinking — thinking (claude-3-7-sonnet and later):

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{ "role": "user", "content": "Step by step: 800 miles apart, one train at 60 mph, one at 80 mph. When do they meet?" }],
    "thinking": { "type": "enabled", "budget_tokens": 5000 }
  }'

budget_tokens must be an integer ≥ 1024. The response includes thinking content blocks alongside the normal text block. Use "type": "disabled" to explicitly turn off thinking for a model that has it on by default.

Gemini 2.5 thinking budget — thinking_config (gemini-2.5-flash, gemini-2.5-pro via OpenRouter):

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{ "role": "user", "content": "Explain the proof of Fermat'\''s Last Theorem at a high level." }],
    "thinking_config": { "thinking_budget": 8000 }
  }'

Set thinking_budget to 0 to disable thinking; any positive integer enables it up to that token cap.

See Reasoning models (o-series) and Claude extended thinking for full parameter rules and SDK examples.

Chat completion with web search

Search-capable OpenAI models (gpt-4o-search-preview, gpt-4.1, and gpt-4.1-mini) can perform live web searches before generating a response. Enable web search by passing the web_search_options object.

Basic — default search context:

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-search-preview",
    "messages": [{ "role": "user", "content": "What are the top Cloudflare announcements this week?" }],
    "web_search_options": {}
  }'

With search_context_size and user_location (gpt-4.1):

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [{ "role": "user", "content": "What is today'\''s weather forecast for San Francisco?" }],
    "web_search_options": {
      "search_context_size": "high",
      "user_location": {
        "type": "approximate",
        "approximate": {
          "city": "San Francisco",
          "region": "California",
          "country": "US",
          "timezone": "America/Los_Angeles"
        }
      }
    }
  }'

search_context_size controls how much web context is retrieved: "low" (fastest, fewer sources), "medium" (default, balanced), or "high" (most sources, highest token cost). All user_location.approximate sub-fields (city, region, country, timezone) are optional strings — include only the ones that are relevant.

Passing a non-object web_search_options (e.g. "web_search_options": "medium") or an invalid search_context_size returns 400 invalid_type / 400 invalid_value before the request reaches Fuelix.

See Web search (OpenAI) for the full parameter reference and validation rules.

Chat completion with web search (streaming SSE)

Web search and streaming are fully compatible — add "stream": true to any web_search_options request and the response body becomes an SSE stream of delta chunks:

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-search-preview",
    "stream": true,
    "messages": [{ "role": "user", "content": "What are the top Cloudflare announcements today?" }],
    "web_search_options": {}
  }'

With search_context_size and user_location (gpt-4.1):

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "stream": true,
    "messages": [{ "role": "user", "content": "What'\''s the latest news in San Francisco?" }],
    "web_search_options": {
      "search_context_size": "high",
      "user_location": {
        "type": "approximate",
        "approximate": {
          "city": "San Francisco",
          "region": "California",
          "country": "US",
          "timezone": "America/Los_Angeles"
        }
      }
    }
  }'

Each data: line is a delta chunk in the standard chat.completion.chunk SSE format; the stream terminates with data: [DONE]. Requests with web_search_options emit "webSearch": true in the BVE Gateway structured request log regardless of whether stream is set — useful for filtering Logpush exports by request type.

Embeddings

curl https://api.bve.me/v1/embeddings \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox"
  }'

Legacy text completions

curl https://api.bve.me/v1/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "The sky is",
    "max_tokens": 50
  }'

Anthropic Messages API

curl https://api.bve.me/v1/messages \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Anthropic-Version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Explain quantum entanglement briefly." }]
  }'

Responses API

curl https://api.bve.me/v1/responses \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Summarize the water cycle.",
    "max_output_tokens": 256
  }'

Text-to-speech

curl https://api.bve.me/v1/audio/speech \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello, world!",
    "voice": "alloy"
  }' \
  --output speech.mp3

Audio transcription (OpenAI Whisper)

curl https://api.bve.me/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -F "file=@audio.mp3" \
  -F "model=whisper-1"

Audio transcription (Groq Whisper — faster)

curl https://api.bve.me/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -F "file=@audio.mp3" \
  -F "model=whisper-large-v3"

Audio transcription (Groq distil-Whisper — fastest)

curl https://api.bve.me/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -F "file=@audio.mp3" \
  -F "model=distil-whisper-large-v3-en"

Image generation

curl https://api.bve.me/v1/images/generations \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-3",
    "prompt": "A sunset over a mountain range",
    "n": 1
  }'

OCR — extract text from a document or image

Send a document or image URL to mistral-ocr via the chat completions endpoint. The model returns the extracted text as the assistant message content.

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-ocr",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": { "url": "https://example.com/invoice.pdf" }
          }
        ]
      }
    ]
  }'

Pass a text prompt alongside the image to guide extraction:

curl https://api.bve.me/v1/chat/completions \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-ocr",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Extract all line items and totals from this invoice." },
          {
            "type": "image_url",
            "image_url": { "url": "https://example.com/invoice.pdf" }
          }
        ]
      }
    ]
  }'

mistral-ocr is endpoint-locked to /v1/chat/completions. Sending it to /v1/messages, /v1/completions, or /v1/responses returns 400 model_endpoint_mismatch.

Admin API

Create API key

curl -X POST https://api.bve.me/admin/api-keys \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-client",
    "rpm_limit": 60,
    "rpd_limit": 10000
  }'

Create a model-restricted key

curl -X POST https://api.bve.me/admin/api-keys \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "embeddings-only",
    "allowed_models": ["text-embedding-3-small", "text-embedding-3-large"]
  }'

List all API keys

curl https://api.bve.me/admin/api-keys \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

List active keys whose name contains “prod”

curl "https://api.bve.me/admin/api-keys?status=active&name=prod" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Get a single API key

curl https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Update key limits

curl -X PATCH https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rpm_limit": 120, "rpd_limit": 20000 }'

Rotate a key

curl -X POST https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Suspend a key

curl -X POST https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/suspend \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Unsuspend a key

curl -X POST https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/unsuspend \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Revoke a key

curl -X POST https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/revoke \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Bulk suspend API keys

curl -X POST https://api.bve.me/admin/api-keys/bulk-suspend \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "661f9511-f3ac-52e5-b827-557766551111"
    ]
  }'

Bulk unsuspend API keys

curl -X POST https://api.bve.me/admin/api-keys/bulk-unsuspend \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "661f9511-f3ac-52e5-b827-557766551111"
    ]
  }'

Bulk revoke API keys

curl -X POST https://api.bve.me/admin/api-keys/bulk-revoke \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "661f9511-f3ac-52e5-b827-557766551111"
    ]
  }'

Get quota status for a key

curl https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/quota \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Reset quota counters for a key

Reset all windows (minute, day, and month) at once — useful to unblock a key after a runaway process:

curl -X POST https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/reset-quota \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Reset only the per-minute window:

curl -X POST https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/reset-quota \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"window": "minute"}'

Valid window values: "minute", "day", "month", "all" (default when body is absent).

Per-key daily and monthly usage history

# All recorded history (last 12 monthly rows, last 90 daily rows)
curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/usage" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Limit to a date range
curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/usage?from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Limit to last 7 daily rows and 1 monthly row
curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/usage?daily_limit=7&monthly_limit=1" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Per-key audit log (lifecycle events)

# All lifecycle events for a key
curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/audit" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Events in a date range
curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/audit?since=2026-05-01&until=2026-05-31" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Filter to a single action type
curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/audit?action=api_key.rotated" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Per-key aggregate stats (sampled logs)

curl "https://api.bve.me/admin/api-keys/550e8400-e29b-41d4-a716-446655440000/stats" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Returns request count, token totals, latency percentiles (p50, p95), and error rates from the 1%-sampled log for this key only. For exact totals, use the /usage endpoint above.

View usage statistics

curl https://api.bve.me/admin/usage \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Usage for a specific key and date range

curl "https://api.bve.me/admin/usage?key_id=550e8400-e29b-41d4-a716-446655440000&from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Audit logs

curl https://api.bve.me/admin/audit-logs \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Audit logs for a specific key

curl "https://api.bve.me/admin/audit-logs?target_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Audit logs filtered by action type

# Only key-rotation events
curl "https://api.bve.me/admin/audit-logs?action=api_key.rotated" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only revocation events
curl "https://api.bve.me/admin/audit-logs?action=api_key.revoked" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Audit logs filtered by actor type

# Only actions taken by admin users (dashboard/direct API)
curl "https://api.bve.me/admin/audit-logs?actor_type=admin_user" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only actions taken by the system (automated/scheduled)
curl "https://api.bve.me/admin/audit-logs?actor_type=admin" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Audit logs filtered by target type

# Only events that affected API keys
curl "https://api.bve.me/admin/audit-logs?target_type=api_key" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only events that affected the model allowlist
curl "https://api.bve.me/admin/audit-logs?target_type=model_allowlist" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Combine: admin-user actions on API keys
curl "https://api.bve.me/admin/audit-logs?actor_type=admin_user&target_type=api_key" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Valid target_type values: api_key, model, admin_user, model_allowlist.

Audit logs in a date range with full-text search

curl "https://api.bve.me/admin/audit-logs?since=2026-05-01&until=2026-05-31&search=rotated&limit=50" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Request logs

curl https://api.bve.me/admin/request-logs \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Request logs filtered by model and endpoint

curl "https://api.bve.me/admin/request-logs?model=gpt-4o&endpoint=/v1/chat/completions" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Request logs in a time window

curl "https://api.bve.me/admin/request-logs?since=2026-05-01T00:00:00Z&until=2026-05-31T23:59:59Z&limit=50" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

List global model allowlist

# All entries
curl https://api.bve.me/admin/model-allowlist \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only enabled models
curl "https://api.bve.me/admin/model-allowlist?enabled=true" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only blocked models
curl "https://api.bve.me/admin/model-allowlist?enabled=false" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Search by model ID substring (case-insensitive)
curl "https://api.bve.me/admin/model-allowlist?search=claude" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Combine: blocked models containing "gpt"
curl "https://api.bve.me/admin/model-allowlist?search=gpt&enabled=false" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Inspect a single model’s allowlist status

curl https://api.bve.me/admin/model-allowlist/gpt-4o \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Always returns 200. Example response for a working model:

{
  "model": "gpt-4o",
  "available": true,
  "category": "chat",
  "bve_category": "chat",
  "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,
  "registry": {
    "working": true,
    "broken": false
  },
  "allowlist": {
    "enabled": true,
    "created_at": "2026-05-21T11:00:00.000Z"
  }
}

Example response for a model not yet registered in D1:

{
  "model": "some-unknown-model",
  "available": false,
  "category": null,
  "bve_category": null,
  "bve_provider": null,
  "bve_reasoning": false,
  "bve_vision": false,
  "bve_web_search": false,
  "bve_audio_input": false,
  "bve_tool_use": false,
  "bve_json_mode": false,
  "bve_thinking": false,
  "registry": {
    "working": false,
    "broken": false
  },
  "allowlist": null
}

URL-encode slashes in model IDs:

curl "https://api.bve.me/admin/model-allowlist/openai%2Fgpt-4o" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Disable a model globally

POST /admin/model-allowlist only accepts exact live Fuelix model IDs. If Fuelix /models is unavailable, the write fails with 400 validation_error instead of creating an unverified D1 row.

curl -X POST https://api.bve.me/admin/model-allowlist \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-4o-mini", "enabled": false }'

Remove a model from the allowlist

curl -X DELETE "https://api.bve.me/admin/model-allowlist/gpt-4o-mini" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Gateway statistics

curl https://api.bve.me/admin/stats \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Returns key counts by status, current-month request and token totals, and per-isolate request cap diagnostics.

Model statistics (sampled request logs)

# Top 50 models by request count (default)
curl "https://api.bve.me/admin/model-stats" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Top 10 models by total tokens this month
curl "https://api.bve.me/admin/model-stats?sort_by=total_tokens&limit=10&since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only Anthropic models, sorted by p95 latency ascending
curl "https://api.bve.me/admin/model-stats?provider=anthropic&sort_by=p95_latency_ms&sort_dir=asc" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Models used on the Responses API only
curl "https://api.bve.me/admin/model-stats?endpoint=/v1/responses" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Stats for a single key, all models, pretty-printed
curl -s "https://api.bve.me/admin/model-stats?key_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $ADMIN_KEY" | jq '.models[] | {model, request_count, total_tokens}'

Counts reflect the 1%-sampled log. Multiply by ~100 for an order-of-magnitude of actual traffic.

Endpoint statistics (sampled request logs)

# All endpoints, default sort (most requests first)
curl "https://api.bve.me/admin/endpoint-stats" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Endpoints sorted by p95 latency (slowest first)
curl "https://api.bve.me/admin/endpoint-stats?sort_by=p95_latency_ms&sort_dir=desc" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Endpoints with most errors, last 7 days
curl "https://api.bve.me/admin/endpoint-stats?sort_by=error_count&since=2026-05-24T00:00:00Z" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Endpoint breakdown for a single model
curl "https://api.bve.me/admin/endpoint-stats?model=gpt-4o" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Key leaderboard (sampled request logs)

# Top 20 keys by request count (default)
curl "https://api.bve.me/admin/key-stats" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Top 10 keys by total tokens
curl "https://api.bve.me/admin/key-stats?sort_by=total_tokens&limit=10" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Keys with highest error count this month
curl "https://api.bve.me/admin/key-stats?sort_by=error_count&since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Keys that used the Responses API specifically
curl "https://api.bve.me/admin/key-stats?endpoint=/v1/responses" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Keys that used a specific model, pretty-printed
curl -s "https://api.bve.me/admin/key-stats?model=gpt-4o&limit=5" \
  -H "Authorization: Bearer $ADMIN_KEY" | jq '.keys[] | {key_id, key_name, request_count, total_tokens}'