183 lines
14 KiB
Markdown
Executable File
183 lines
14 KiB
Markdown
Executable File
# API Endpoints Reference
|
|
|
|
This reference lists the HTTP surfaces implemented in the gateway as of the
|
|
current code review. It is derived from `apps/gateway/main.ts` and the
|
|
registered route files under `apps/gateway/routes/`.
|
|
|
|
## Conventions
|
|
|
|
- Public inference routes are served from the same origin as the control UI.
|
|
- `/api/*` routes are operator surfaces. If `FROSTY_ADMIN_TOKEN` is set, they
|
|
require `Authorization: Bearer <token>`.
|
|
- Errors use the canonical envelope
|
|
`{ "error": { "message", "type", "param", "code" } }` through the shared error
|
|
helpers.
|
|
- Compatibility prefixes are rewritten before auth and governance. Verified
|
|
aggregator prefixes include `/openai`, `/anthropic`, `/litellm`, `/langchain`,
|
|
and `/pydanticai`.
|
|
|
|
## Health and metadata
|
|
|
|
| Method | Path | Purpose | Source |
|
|
| ------ | -------------- | ---------------------------------------- | ----------------------------------- |
|
|
| `GET` | `/healthz` | Liveness and version check | `apps/gateway/main.ts` |
|
|
| `GET` | `/api/version` | Gateway version and Deno runtime version | `apps/gateway/main.ts` |
|
|
| `GET` | `/metrics` | Prometheus metrics exposition | `apps/gateway/routes/governance.ts` |
|
|
|
|
## Core inference
|
|
|
|
| Method | Path | Purpose | Source |
|
|
| ------ | --------------------------- | --------------------------------------- | ---------------------------------- |
|
|
| `GET` | `/v1/models` | List configured model catalog | `apps/gateway/routes/inference.ts` |
|
|
| `POST` | `/v1/chat/completions` | Canonical chat-completion surface | `apps/gateway/routes/inference.ts` |
|
|
| `POST` | `/v1/completions` | Legacy text-completion surface | `apps/gateway/routes/inference.ts` |
|
|
| `POST` | `/v1/count_tokens` | Token counting on the canonical surface | `apps/gateway/routes/inference.ts` |
|
|
| `POST` | `/v1/responses` | Agentic response loop with tool support | `apps/gateway/routes/inference.ts` |
|
|
| `POST` | `/v1/messages/count_tokens` | Anthropic-style token counting | `apps/gateway/routes/compat.ts` |
|
|
| `POST` | `/v1/messages` | Anthropic Messages-compatible ingress | `apps/gateway/routes/compat.ts` |
|
|
|
|
## Advanced APIs
|
|
|
|
| Method | Path | Purpose | Source |
|
|
| -------- | -------------------------- | --------------------------------------- | --------------------------------- |
|
|
| `POST` | `/v1/embeddings` | Embedding generation | `apps/gateway/routes/advanced.ts` |
|
|
| `POST` | `/v1/images/generations` | Image generation | `apps/gateway/routes/advanced.ts` |
|
|
| `POST` | `/v1/audio/speech` | Text-to-speech | `apps/gateway/routes/advanced.ts` |
|
|
| `POST` | `/v1/audio/transcriptions` | Speech-to-text / transcription | `apps/gateway/routes/advanced.ts` |
|
|
| `POST` | `/v1/files` | Create or upload a provider-backed file | `apps/gateway/routes/advanced.ts` |
|
|
| `GET` | `/v1/files` | List provider-backed files | `apps/gateway/routes/advanced.ts` |
|
|
| `GET` | `/v1/files/:id` | Retrieve file metadata | `apps/gateway/routes/advanced.ts` |
|
|
| `GET` | `/v1/files/:id/content` | Retrieve file content | `apps/gateway/routes/advanced.ts` |
|
|
| `DELETE` | `/v1/files/:id` | Delete a provider-backed file | `apps/gateway/routes/advanced.ts` |
|
|
| `POST` | `/v1/batches` | Create a provider-backed batch job | `apps/gateway/routes/advanced.ts` |
|
|
| `GET` | `/v1/batches` | List batch jobs | `apps/gateway/routes/advanced.ts` |
|
|
| `GET` | `/v1/batches/:id` | Inspect one batch job | `apps/gateway/routes/advanced.ts` |
|
|
| `GET` | `/v1/batches/:id/results` | Fetch batch results | `apps/gateway/routes/advanced.ts` |
|
|
| `POST` | `/v1/batches/:id/cancel` | Cancel a batch job | `apps/gateway/routes/advanced.ts` |
|
|
|
|
## Compatibility and ingress surfaces
|
|
|
|
### Native or vendor-shaped ingress
|
|
|
|
| Method | Path | Purpose | Notes |
|
|
| ------ | -------------------------------------------------- | ------------------------------------------ | ------------------------------------------- |
|
|
| `POST` | `/genai/v1beta/models/:modelAction` | Google GenAI-compatible ingress | `apps/gateway/routes/compat_families.ts` |
|
|
| `POST` | `/cohere/v2/chat` | Cohere v2-compatible ingress | `apps/gateway/routes/compat_families.ts` |
|
|
| `POST` | `/openrouter/v1/chat/completions` | OpenRouter-shaped chat ingress | `apps/gateway/routes/openrouter_ingress.ts` |
|
|
| `POST` | `/openrouter/v1/embeddings` | OpenRouter-shaped embeddings ingress | `apps/gateway/routes/openrouter_ingress.ts` |
|
|
| `GET` | `/openrouter/v1/models` | OpenRouter-shaped model listing | `apps/gateway/routes/openrouter_ingress.ts` |
|
|
| `POST` | `/openai/deployments/:deployment/chat/completions` | Azure deployment-scoped chat ingress | `apps/gateway/routes/azure_ingress.ts` |
|
|
| `POST` | `/openai/deployments/:deployment/completions` | Azure deployment-scoped legacy completions | `apps/gateway/routes/azure_ingress.ts` |
|
|
| `POST` | `/openai/deployments/:deployment/embeddings` | Azure deployment-scoped embeddings | `apps/gateway/routes/azure_ingress.ts` |
|
|
|
|
### Rewritten alias families
|
|
|
|
| Prefix or shape | Effective target | Notes |
|
|
| --------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
| `/openai/*` | Canonical `/v1/*` surface | `/openai/deployments/*` is excluded and handled by Azure ingress |
|
|
| `/anthropic/*` | Canonical `/v1/*` surface with dialect-aware translation | `apps/gateway/routes/compat_families.ts` |
|
|
| `/litellm/*` | Aggregator alias family | Rewrites before auth and governance |
|
|
| `/langchain/*` | Aggregator alias family | Rewrites before auth and governance |
|
|
| `/pydanticai/*` | Aggregator alias family | Rewrites before auth and governance |
|
|
|
|
### Implemented 501 or intentionally deferred compatibility endpoints
|
|
|
|
| Method | Path | Behavior | Source |
|
|
| ------ | --------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
|
|
| `GET` | `/openrouter/v1/generation` | Returns 501; Frosty keeps its own cost accounting | `apps/gateway/routes/openrouter_ingress.ts` |
|
|
| `GET` | `/openrouter/v1/key` | Returns 501; Frosty does not proxy OpenRouter key introspection | `apps/gateway/routes/openrouter_ingress.ts` |
|
|
| `POST` | `/:agg(litellm | langchain | pydanticai)/bedrock/:rest*` |
|
|
| `POST` | `/:agg(litellm | langchain | pydanticai)/model/:rest*` |
|
|
|
|
## Operator API
|
|
|
|
### Providers and config
|
|
|
|
| Method | Path | Purpose |
|
|
| -------- | ------------------------------------- | ---------------------------------------------- |
|
|
| `GET` | `/api/providers` | List configured providers in browser-safe form |
|
|
| `POST` | `/api/providers` | Create a provider account |
|
|
| `PUT` | `/api/providers/:id` | Update a provider account |
|
|
| `DELETE` | `/api/providers/:id` | Delete a provider account |
|
|
| `POST` | `/api/providers/:id/refresh-models` | Refresh provider model list |
|
|
| `GET` | `/api/providers/:id/available-models` | List provider models live (read-only) |
|
|
| `GET` | `/api/providers/health` | Report provider health |
|
|
| `GET` | `/api/config` | Fetch gateway config view |
|
|
| `PUT` | `/api/config` | Persist gateway config updates |
|
|
| `GET` | `/api/proxy-config` | Read gateway-wide proxy config |
|
|
| `PUT` | `/api/proxy-config` | Upsert gateway-wide proxy config |
|
|
| `DELETE` | `/api/proxy-config` | Remove gateway-wide proxy config |
|
|
| `POST` | `/api/config/reload` | Reload in-memory config from durable state |
|
|
| `GET` | `/api/config/export` | Export config payload |
|
|
| `POST` | `/api/config/import` | Import config payload |
|
|
|
|
### Governance and pricing
|
|
|
|
| Method | Path | Purpose |
|
|
| -------- | ------------------------- | ------------------------- |
|
|
| `GET` | `/api/virtual-keys` | List virtual keys |
|
|
| `POST` | `/api/virtual-keys` | Create a virtual key |
|
|
| `PUT` | `/api/virtual-keys/:id` | Update a virtual key |
|
|
| `DELETE` | `/api/virtual-keys/:id` | Delete a virtual key |
|
|
| `GET` | `/api/teams` | List teams |
|
|
| `POST` | `/api/teams` | Create a team |
|
|
| `PUT` | `/api/teams/:id` | Update a team |
|
|
| `DELETE` | `/api/teams/:id` | Delete a team |
|
|
| `GET` | `/api/customers` | List customers |
|
|
| `POST` | `/api/customers` | Create a customer |
|
|
| `PUT` | `/api/customers/:id` | Update a customer |
|
|
| `DELETE` | `/api/customers/:id` | Delete a customer |
|
|
| `GET` | `/api/pricing` | Read pricing catalog |
|
|
| `PUT` | `/api/pricing` | Persist pricing overrides |
|
|
| `POST` | `/api/pricing/force-sync` | Trigger a pricing sync |
|
|
|
|
### Logs, analytics, runtime, and catalog
|
|
|
|
| Method | Path | Purpose |
|
|
| -------- | ---------------------------- | -------------------------------------------------- |
|
|
| `GET` | `/api/logs` | Read live in-memory request log ring |
|
|
| `GET` | `/api/logs/stored` | Read durable stored logs |
|
|
| `GET` | `/api/logs/stats` | Aggregate log statistics |
|
|
| `GET` | `/api/logs/dropped` | Report ring-buffer evictions |
|
|
| `GET` | `/api/logs/filterdata` | Return filter metadata for the logs UI |
|
|
| `POST` | `/api/logs/recalculate-cost` | Recompute stored log costs |
|
|
| `DELETE` | `/api/logs/stored` | Clear stored logs |
|
|
| `GET` | `/api/logs/stream` | Stream live log entries |
|
|
| `GET` | `/api/analytics` | Return analytics rollups |
|
|
| `GET` | `/api/runtime` | Return runtime diagnostics and topology |
|
|
| `GET` | `/api/catalog` | Return the model catalog and provider capabilities |
|
|
| `GET` | `/api/plugins` | List plugin metadata |
|
|
|
|
### Settings, cache, MCP, and Code Mode
|
|
|
|
| Method | Path | Purpose |
|
|
| -------- | ----------------------------- | --------------------------------------------- |
|
|
| `GET` | `/api/settings` | Read effective settings values and provenance |
|
|
| `PUT` | `/api/settings` | Persist partial settings overrides |
|
|
| `GET` | `/api/mcp/clients` | List MCP clients |
|
|
| `POST` | `/api/mcp/clients` | Create an MCP client |
|
|
| `PUT` | `/api/mcp/clients/:id` | Update an MCP client |
|
|
| `DELETE` | `/api/mcp/clients/:id` | Delete an MCP client |
|
|
| `POST` | `/api/mcp/clients/:id/sync` | Sync one MCP client |
|
|
| `POST` | `/api/mcp/sync` | Sync all MCP clients |
|
|
| `GET` | `/api/mcp/tools` | List aggregated MCP tools |
|
|
| `GET` | `/api/mcp/health` | Return MCP health state |
|
|
| `GET` | `/api/mcp/codemode/vfs` | Return Code Mode VFS metadata |
|
|
| `POST` | `/api/mcp/codemode/run` | Execute Code Mode run path |
|
|
| `DELETE` | `/api/cache` | Clear cache |
|
|
| `DELETE` | `/api/cache/by-key` | Clear cache by request shape |
|
|
| `DELETE` | `/api/cache/clear/:requestId` | Clear cache by request id |
|
|
| `GET` | `/mcp` | MCP server discovery surface |
|
|
| `POST` | `/mcp` | MCP server JSON-RPC surface |
|
|
|
|
## Notes for consumers
|
|
|
|
- The control UI talks only to same-origin routes and stores the admin token in
|
|
browser session storage.
|
|
- Several provider-specific route families accept vendor-shaped inputs but still
|
|
resolve against configured Frosty provider accounts rather than blindly
|
|
proxying upstream credentials.
|
|
- Settings currently expose provenance and persistence behavior even where some
|
|
fields are not yet wired into runtime enforcement. That is an implementation
|
|
fact, not a documentation omission.
|