Introduction

BVE Gateway is an OpenAI-compatible API gateway that proxies requests to the Fuelix AI platform. It runs as a Cloudflare Worker on the edge with no cold-start latency.

Base URL: https://api.bve.me/v1

OpenAPI spec: https://api.bve.me/openapi.json

What it does

• Accepts OpenAI-format requests from any client or SDK
• Authenticates callers with hashed API keys stored in Cloudflare D1
• Enforces per-minute, per-day, and per-month request quotas using Cloudflare Durable Objects
• Forwards requests to Fuelix and streams responses back without buffering
• Records usage asynchronously via ctx.waitUntil

Supported endpoints

Unauthenticated

Method	Path	Description
GET	/health	Health check
GET	/openapi.json	OpenAPI 3.1 spec

Public API (Authorization: Bearer sk-bve-YOUR_KEY)

Method	Path	Description
GET	/v1/usage	Real-time quota snapshot for the authenticated key (does not consume quota)
GET	/v1/models	List available models
GET	/v1/models/:id	Get a single model
POST	/v1/chat/completions	Chat completions (streaming supported)
POST	/v1/completions	Legacy text completions (emulated via chat completions; streaming supported)
POST	/v1/embeddings	Text embeddings
POST	/v1/responses	OpenAI Responses API (GPT models only)
GET	/v1/responses/:id	Retrieve a stored response by ID
DELETE	/v1/responses/:id	Delete a stored response by ID
POST	/v1/messages	Anthropic Messages API (Anthropic response format)
GET	/v1/messages/:id	Anthropic Messages API — individual message
POST	/v1/audio/speech	Text-to-speech (binary audio stream)
POST	/v1/audio/transcriptions	Audio transcription (Whisper)
POST	/v1/images/generations	Image generation (Imagen 3/4; not dall-e-3)
POST	/v1/images/edits	Image editing (multipart/form-data)
GET/POST	/v1/files	Files API — list / upload
GET/DELETE	/v1/files/:id	Files API — retrieve / delete
GET	/v1/files/:id/content	Files API — download file content
GET/POST	/v1/assistants	Assistants API — list / create
GET/POST/DELETE	/v1/assistants/:id	Assistants API — manage assistant
*	/v1/assistants/:id/…	Assistants sub-resources (steps, files, etc.)
POST	/v1/threads	Threads API — create thread
GET/POST/DELETE	/v1/threads/:id	Threads API — manage thread
*	/v1/threads/:id/…	Thread sub-resources (messages, runs, steps)
GET/POST	/v1/vector_stores	Vector Stores API — list / create
GET/POST/DELETE	/v1/vector_stores/:id	Vector Stores — manage store
*	/v1/vector_stores/:id/…	Vector Store sub-resources (files, batches)

Shared upstream account

Files, Assistants, Threads, and Vector Stores all share the same Fuelix upstream account. Objects created by one API key are visible to all other keys on this gateway.

Admin API (Authorization: Bearer admin_bve_YOUR_ADMIN_KEY)

Method	Path	Description
POST	/admin/api-keys	Create API key
GET	/admin/api-keys	List API keys
GET	/admin/api-keys/:id	Get a single API key
PATCH	/admin/api-keys/:id	Update key name or limits
POST	/admin/api-keys/:id/rotate	Rotate (replace) the raw key value
POST	/admin/api-keys/:id/suspend	Suspend an active key
POST	/admin/api-keys/:id/unsuspend	Unsuspend a suspended key
POST	/admin/api-keys/:id/revoke	Permanently revoke a key
POST	/admin/api-keys/bulk-suspend	Suspend up to 100 active keys in one request
POST	/admin/api-keys/bulk-unsuspend	Unsuspend up to 100 suspended keys in one request
POST	/admin/api-keys/bulk-revoke	Permanently revoke up to 100 keys in one request
GET	/admin/api-keys/:id/quota	Real-time quota status and remaining capacity
POST	/admin/api-keys/:id/reset-quota	Reset Durable Object quota counters for a key
GET	/admin/api-keys/:id/stats	Per-key aggregate stats from sampled logs (latency percentiles, token totals, error breakdown)
GET	/admin/api-keys/:id/audit	Per-key lifecycle event history (create, update, suspend, rotate, revoke); 404s if key not found
GET	/admin/api-keys/:id/usage	Per-key daily and monthly usage history (404s if key not found)
GET	/admin/stats	Gateway-wide aggregate statistics (key counts, monthly totals, isolate cap status)
GET	/admin/usage	Usage statistics
GET	/admin/model-stats	Per-model aggregate statistics (request counts, token sums, latency from sampled logs)
GET	/admin/endpoint-stats	Per-endpoint aggregate statistics (request counts, latency percentiles, error rate from sampled logs)
GET	/admin/key-stats	Per-key leaderboard — top keys by request count, with token totals and latency
GET	/admin/audit-logs	Audit log entries
GET	/admin/request-logs	Sampled request log entries
GET	/admin/model-allowlist	List global model allowlist
GET	/admin/model-allowlist/:model	Inspect allowlist status and registry metadata for one model
POST	/admin/model-allowlist	Add or update model allowlist entry using an exact live Fuelix model ID
DELETE	/admin/model-allowlist/:model	Remove model from allowlist

See the Admin API Overview for full details on each endpoint.

Key design decisions

• API keys are never stored in plain text. Only sha256(key + pepper) is stored.
• Streaming SSE responses pass through without buffering — response.body is piped directly.
• Rate limiting uses a Cloudflare Durable Object (ApiKeyLimiter) per key. If the DO fails, the request is allowed (fail-open) to avoid blocking legitimate traffic.
• Usage is recorded asynchronously — it does not add latency to the request path.

Next steps

Quickstart Make your first API call in under a minute — install the SDK and send a chat completion.

Authentication Key format, CORS headers, and all auth error codes explained.

Chat Completions Full request/response reference for /v1/chat/completions with streaming.

Usage Snapshot Query your key's real-time quota counters without consuming a request.

Rate Limits & Quotas Per-key RPM/RPD limits, monthly caps, and Retry-After handling.

Admin API Provision keys, view usage, manage model access, and inspect request logs.