# Evidence Bundle (/docs/confidential-bundle)
The Stogas evidence bundle is a public, continuously updated snapshot of the confidential gateway fleet. It tells a verifier which gateway releases and connection keys can currently be trusted.
Verification happens locally. A client downloads one JSON file, checks its embedded evidence, and receives a trusted set of gateways without contacting GitHub, AMD, Sigstore, or drand.
## Endpoints [#endpoints]
```text
Production https://evidence.stogas.ai/bundles/latest.json
Staging https://evidence-staging.stogas.ai/bundles/latest.json
```
Both endpoints support public browser `GET` and `HEAD` requests.
## What a verified bundle provides [#what-a-verified-bundle-provides]
* Gateway releases proven to come from the public Stogas gateway repository and authorized by Stogas.
* Confidential gateway nodes running an approved release on AMD SEV-SNP hardware.
* The attested certificate, TLS, response-signing, and encryption keys for each trusted gateway.
* An `expires_at` deadline after which the snapshot must not be used.
The verifier returns fresh gateways under `nodes`. Cryptographically valid records that are too old for the selected freshness policy appear under `excluded_nodes` and are not trusted for connections.
## Refreshing [#refreshing]
Use `expires_at` as the only refresh deadline. There is no fixed polling interval.
`stogas-verify serve` normally begins fetching a replacement 40–70 seconds before expiry. It retries transient failures every 4–8 seconds and activates a replacement only after complete verification. Application SDKs leave retrieval and scheduling to the application.
Refreshing early does not shorten the current trust window: a verified replacement has its own later expiry. If no valid replacement is available by the current deadline, the client must stop opening new trusted connections.
## Freshness policy [#freshness-policy]
The default verifier policy accepts node evidence that remains no more than three minutes old through bundle expiry. Applications that require a tighter window may select one to three minutes.
Changing this policy affects which gateways enter the local trusted set. It does not change the validity of the bundle or other verified gateways.
For installation and code examples, continue with the [verification quickstart](/docs/confidential-verification). For the underlying guarantees, see the [security model](/docs/confidential-security-model).
# Security Model (/docs/confidential-security-model)
Stogas runs its API gateway inside an AMD SEV-SNP confidential VM. The host can stop or delay the VM, but should not be able to read guest memory, private keys, provider credentials, or request plaintext.
## The verification chain [#the-verification-chain]
1. **Release provenance:** GitHub Actions and Stogas independently authorize the same public source, IGVM hash, launch policy, and SNP measurement.
2. **Hardware attestation:** AMD-signed SNP evidence proves an approved measurement booted on genuine hardware at an accepted security version.
3. **Key binding:** SNP report data binds the node's TLS key, certificate hashes, and application keys to that measured guest.
4. **Freshness:** a signed drand round and the verifier's captured wall clock bound how old the node evidence may be.
No root of trust is accepted from the downloaded bundle. The verifier ships the AMD, Sigstore, drand, and Stogas release roots it trusts.
## Request path [#request-path]
Verification and evidence publication happen outside the inference request path. Once a node is trusted, requests use the normal OpenAI-compatible HTTPS API. This avoids a live dependency on GitHub, Sigstore, Rekor, AMD KDS, drand, or the evidence service for each model request.
`stogas-verify serve` additionally checks that the upstream TLS connection presents a certificate hash and public key belonging to the same verified node.
## Release authorization [#release-authorization]
The Stogas release public key is:
```text
MCowBQYDK2VwAyEAByVn3LvWVbf3YkokMZPvir70vcDu0nNflgXoM0Y8aQU=
```
It signs canonical `stogas.gateway.launch-policy.v1` bytes using the domain separator `stogas gateway launch policy v1\n`. GitHub's attestation must independently bind the exact same launch-policy digest and IGVM digest. A node is trusted only when its SNP measurement belongs to that verified release set.
## Availability [#availability]
A verified bundle can contain records that are no longer fresh enough for a particular client. The verifier reports those records separately and never adds them to that client's trusted set.
The verifier fails closed after bundle expiry. Confidential verification can authenticate a reachable gateway, but it cannot prevent a network, host, or service outage.
## What is not proven [#what-is-not-proven]
Confidential verification does not:
* prove that reviewed code has no vulnerabilities;
* hide traffic timing or destination metadata;
* make an upstream AI provider confidential unless that provider offers its own verified confidential execution;
* prevent the host or operator from stopping service;
* let browser JavaScript inspect the certificate used by `fetch`;
* verify response proofs or provide end-to-end application encryption in the current protocol.
# Verification Quickstart (/docs/confidential-verification)
The verifier checks the gateway release, AMD SEV-SNP evidence, node keys, certificates, and freshness locally. Verification itself makes no network requests.
## Pick an integration [#pick-an-integration]
| Use case | Recommended option |
| --------------------------------------------------------- | -------------------------------------------------------- |
| Use any OpenAI-compatible app with automatic verification | `stogas-verify serve` |
| Inspect a downloaded bundle or verify in CI | `stogas-verify verify` |
| Manage a trust set inside your application | Rust, JavaScript, Python, Go, or C SDK |
| Call the native verifier from another language | [C ABI integrations](/docs/verifier-native-integrations) |
| Verify only GitHub/Sigstore evidence | `stogas-offline-sigstore` |
The native CLI is for existing tools and shell workflows. SDKs are for applications that already own bundle retrieval and connection handling; every SDK uses the same Rust verification core.
## Verified local endpoint [#verified-local-endpoint]
`serve` maintains a verified bundle and exposes a loopback OpenAI-compatible endpoint:
Download the archive for your operating system from [GitHub Releases](https://github.com/StogasAI/verifier/releases), verify it against the published `SHA256SUMS`, and place `stogas-verify` on your `PATH`.
```console
stogas-verify serve
```
Point an existing client at:
```text
http://127.0.0.1:8787/v1
```
The proxy verifies normal WebPKI and hostname rules, then requires the TLS certificate hash and SPKI to match the same attested node. It refreshes in the background before bundle expiry and never installs a local CA.
## Verify a bundle file [#verify-a-bundle-file]
```console
curl -o bundle.json https://evidence.stogas.ai/bundles/latest.json
stogas-verify verify bundle.json
```
`verify` is a command-line interface over the same verification function exposed by every SDK. It reads a file or standard input and writes no verifier state to disk.
## JavaScript, Node, and Bun [#javascript-node-and-bun]
```console
npm install @stogas/verifier
```
```js
import { Verifier } from '@stogas/verifier';
const response = await fetch('https://evidence.stogas.ai/bundles/latest.json');
const verifier = new Verifier();
const result = verifier.verify_bundle(new Uint8Array(await response.arrayBuffer()));
console.log(result.bundle.nodes);
```
Browsers use `@stogas/verifier/browser` and call its default WebAssembly initializer once. Cloudflare Workers and other Worker runtimes use `@stogas/verifier/worker`. Browser code can verify evidence, but browser networking APIs do not expose the peer certificate needed for TLS pinning.
## Python [#python]
Python uses a native PyO3 stable-ABI extension:
```console
pip install stogas-verifier
```
```python
import json
from stogas_verifier import Verifier
result = json.loads(Verifier().verify_bundle(bundle_bytes))
print(result["bundle"]["nodes"])
```
## Go [#go]
```console
go get github.com/StogasAI/verifier/go
```
```go
v, err := verifier.New()
if err != nil { return err }
defer v.Close()
verifiedJSON, err := v.VerifyBundle(bundleBytes)
```
The Go package is a thin cgo binding to the same Rust implementation.
## Rust [#rust]
```console
cargo add stogas-verifier
```
Rust applications use the crate directly. Other native environments can use the bounded C ABI.
## Java, .NET, Swift, Kotlin, and other native languages [#java-net-swift-kotlin-and-other-native-languages]
Release archives include a C header and native library. Java 22+, C# and F#, Swift, Kotlin/Native, C++, Dart, Ruby, and other runtimes with C interoperability can call that same bounded ABI without another verifier implementation.
See [C ABI integrations](/docs/verifier-native-integrations) for the supported binary targets, ownership rules, and the appropriate bridge for each language. These are self-managed native integrations; Rust, JavaScript, Python, and Go remain the first-class packaged SDKs.
## What the SDK returns [#what-the-sdk-returns]
Every SDK returns:
* verified gateway releases;
* fresh trusted nodes and their attested TLS/key material;
* cryptographically valid but locally stale nodes under `excluded_nodes`;
* the verified bundle creation and expiry times.
SDKs intentionally do not fetch bundles, run background tasks, or replace a language's HTTP stack. Applications that need managed refresh and connection pinning should use `serve`. See [Evidence and freshness](/docs/confidential-bundle) for the refresh rules.
# Quickstart (/docs)
Stogas provides one API for supported AI models. Existing OpenAI-compatible clients work by changing the base URL.
## 1. Create an API key [#1-create-an-api-key]
Create a key in the [Stogas dashboard](https://app.stogas.ai), then export it:
```console
export STOGAS_API_KEY="your-key"
```
## 2. Send a request [#2-send-a-request]
```console
curl https://api.stogas.ai/v1/chat/completions \
-H "Authorization: Bearer $STOGAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5-mini",
"messages": [{"role": "user", "content": "Say hello in one sentence."}]
}'
```
Or use the OpenAI Python client:
```python
from openai import OpenAI
client = OpenAI(
api_key="your-key",
base_url="https://api.stogas.ai/v1",
)
response = client.chat.completions.create(
model="openai/gpt-5-mini",
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)
```
## 3. Choose a model [#3-choose-a-model]
Use the [model catalog](https://stogas.ai/catalog), or query it directly:
```console
curl https://api.stogas.ai/v1/models
```
## Verify the confidential gateway [#verify-the-confidential-gateway]
Normal OpenAI-compatible requests need no Stogas-specific inference SDK. If you want to verify the gateway and pin the attested TLS key, continue with the [verification quickstart](/docs/confidential-verification).
# Model Tools (/docs/model-tools)
Tools let a model call something outside normal text generation. The gateway treats tools as either client tools or provider-hosted tools:
* **Client tools** are run by your application or by an MCP server you provide. They do not have a separate tool charge from the gateway. You pay for the model tokens the provider reports.
* **Provider-hosted tools** are run by OpenAI or Anthropic. These can have separate provider charges, so only the hosted tools listed below are available.
OpenAI search-model deployments such as `gpt-5-search-api` expose web retrieval through
`web_search_options`, not through `tools`. Those deployments perform one priced retrieval per
request.
## Chat Completions [#chat-completions]
Chat Completions is intentionally conservative. It is best for normal function calling and simple tool routing.
| Tool type | OpenAI | Anthropic | Billing |
| --------------------------------------- | :----: | :-------: | ----------------------------------------------------------------- |
| `function` | Yes | Yes | Token usage only |
| `custom` | Yes | No | Token usage only |
| Anthropic `mcp_toolset` + `mcp_servers` | No | Yes | Token usage only; MCP server costs are billed outside the gateway |
| Provider-hosted web/search tools | No | No | Use Responses API or OpenAI search-model deployments |
Anthropic Chat custom tools are not available through the OpenAI-compatible Chat Completions
route. Use Anthropic Responses for `custom` tools, or use standard `function` tools on Chat
Completions.
## Responses API [#responses-api]
Responses supports the broader tool surface. Use it when you need hosted web tools, MCP, or custom tools.
| Tool type | OpenAI | Anthropic | Billing |
| --------------------- | :----: | :-------: | ------------------------------------------------------------------------ |
| `function` | Yes | Yes | Token usage only |
| `custom` | Yes | Yes | Token usage only |
| `mcp` | Yes | Yes | Token usage only; MCP server costs are billed outside the gateway |
| `web_search*` | Yes | Yes | Web-search call charge plus provider-reported token usage |
| `web_search_preview*` | Yes | No | OpenAI web-search-preview call charge plus provider-reported token usage |
| `web_fetch*` | No | Yes | Provider-reported token usage only |
Use `max_tool_calls` to bound provider-hosted tool calls. If you omit it for a priced hosted tool, the gateway applies a conservative default cap before the request is sent upstream.
`tool_choice: "none"` disables provider-hosted tool calls for that request, so no hosted-tool call
meter is applied.
## Provider-Hosted Billing [#provider-hosted-billing]
OpenAI Responses web search has separate call meters:
| Tool family | Billing |
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
| `web_search*` | Web-search call price plus search content tokens at model rates |
| `web_search_preview*` on reasoning models | Web-search-preview call price plus search content tokens at model rates |
| `web_search_preview*` on non-reasoning models | Higher web-search-preview call price; search content tokens are not separately billed |
Anthropic Responses web tools are billed as:
| Tool family | Billing |
| ------------- | -------------------------------------------------------- |
| `web_search*` | Web-search call price plus provider-reported token usage |
| `web_fetch*` | Provider-reported token usage only |
Anthropic may use code execution internally as part of web search or web fetch. That bundled behavior is treated as part of the admitted web tool. Standalone code execution is not available.
## MCP Tools [#mcp-tools]
MCP tools connect the model to a remote server. The gateway bills model tokens only; any cost from your MCP server is your responsibility.
For Responses MCP tools:
* use an HTTPS `server_url`
* include `allowed_tools` with explicit tool names or a read-only filter
* avoid approval workflows
For OpenAI Responses, set `require_approval: "never"`.
For Anthropic Chat, use Anthropic's native `mcp_servers` array with matching `tools[].type: "mcp_toolset"` entries.
## Unavailable Provider Tools [#unavailable-provider-tools]
The public API is text-only and does not expose every provider-hosted tool.
| Tool family | Availability |
| ------------------------------------------------------------- | ------------- |
| File search and hosted retrieval | Not available |
| Code interpreter, hosted shell, and standalone code execution | Not available |
| Local shell and patch tools | Not available |
| Computer-use and image-generation tools | Not available |
| Provider memory or tool-loading tools | Not available |
Unavailable tools return `400 invalid_request_error` before a provider request is made.
# Native Verifier Integrations (/docs/verifier-native-integrations)
Stogas release archives contain the bounded `stogas_verifier.h` C interface and native libraries for:
* Linux x86-64 and ARM64;
* macOS x86-64 and ARM64;
* Windows x86-64.
Use a first-class Stogas package when one exists. The C ABI is the escape hatch for other native runtimes; it does not require a second implementation of verification policy.
## Choose a bridge [#choose-a-bridge]
| Environment | Recommended integration |
| --------------------------------------- | ------------------------------------------------------------------- |
| Java 22+, Scala, Clojure, or Kotlin/JVM | Java Foreign Function & Memory API |
| Older JVM applications | JNA or a small JNI adapter |
| C# or F# | .NET `LibraryImport` or `DllImport` / P/Invoke |
| Swift or Objective-C | Native C interoperability with a module map or bridging header |
| Kotlin/Native | `cinterop` generated from `stogas_verifier.h` |
| C or C++ | Include `stogas_verifier.h`; it already provides C++ linkage guards |
| Zig | `@cImport` |
| Dart or Flutter | `dart:ffi` |
| Ruby | `Fiddle` or the `ffi` gem |
| PHP | PHP FFI where enabled |
| Julia | `ccall` |
| Haskell | The standard Haskell FFI |
| OCaml | `ctypes` |
| LuaJIT | LuaJIT FFI |
| Elixir or Erlang | A supervised Port or carefully isolated NIF |
JavaScript, browser, Worker, Node, and Bun applications should use `@stogas/verifier` instead of native FFI. Python should use the PyO3 wheel, Go should use the supplied cgo package, and Rust should use the crate directly.
## ABI contract [#abi-contract]
The interface is intentionally small:
```c
uint32_t stogas_verifier_abi_version(void);
StogasVerifier *stogas_verifier_new(int64_t max_node_age_ms);
char *stogas_verifier_verify_bundle(
const StogasVerifier *verifier,
const uint8_t *bundle,
size_t bundle_len,
int64_t now_unix_ms
);
void stogas_verifier_string_free(char *value);
void stogas_verifier_free(StogasVerifier *verifier);
```
`max_node_age_ms` must be between 60,000 and 180,000 milliseconds. Capture the platform wall clock once immediately before verification and pass Unix time in milliseconds as `now_unix_ms`.
Each verification returns an owned, NUL-terminated JSON envelope:
```json
{ "ok": true, "value": {} }
```
or:
```json
{ "ok": false, "error": "verification failed" }
```
Always release a non-null result with `stogas_verifier_string_free`, and release the verifier with `stogas_verifier_free`. Do not free a verifier while another thread is using it. Check `stogas_verifier_abi_version()` before loading a library version your integration has not tested.
## What Stogas tests [#what-stogas-tests]
The release workflow tests the C boundary directly and uses the same library through the official Go package. Every native archive is built on its target operating system and published with checksums and a GitHub artifact attestation.
Language-specific glue written outside the Stogas repository remains the integrator's responsibility. Treat native-library loading, search paths, process architecture, allocator ownership, and thread use as part of that integration's security boundary.
# API Reference (/docs/reference)
Explore and test all gateway endpoints. Each operation page includes an interactive playground for live requests.
Use `https://api.stogas.ai` as the base URL. Endpoint paths include their API version.
## Endpoints [#endpoints]
## Guides [#guides]
## Authentication [#authentication]
Inference endpoints require a gateway API key:
```http
Authorization: Bearer
Content-Type: application/json
```
`/v1/catalog` and `/v1/models` are public. Get your key from the [dashboard](https://app.stogas.ai).
# Compatibility Notes (/docs/reference/provider-behavior)
Stogas supports OpenAI-compatible Chat Completions and Responses requests across cataloged OpenAI and Anthropic models. The operation pages are the source of truth for accepted fields.
## Routing [#routing]
Choose a public model ID from `/v1/models`. If a slug is available from more than one provider, use `provider` or its `rules` alias:
```json
{
"provider": { "only": ["anthropic"] }
}
```
Do not send both fields. Routing hints are removed before upstream dispatch.
## Important differences [#important-differences]
* Requests are strict: unknown top-level fields return `400` instead of being forwarded.
* The current public surface accepts text content only.
* `stream: true` uses the endpoint's normal Server-Sent Events format.
* OpenAI `max_tokens` is accepted as an alias for `max_completion_tokens` on Chat Completions.
* Anthropic deployments reject requests that set both `temperature` and `top_p`.
* `inference_geo: "global"` uses standard multi-region pricing; `inference_geo: "us"` selects eligible US-only deployments.
* Provider-specific cache controls, service tiers, and hosted tools are accepted only where the catalog can route and bill them correctly.
See [Model Tools](/docs/model-tools) for supported function, MCP, and provider-hosted tools.
## Errors [#errors]
Errors use an OpenAI-compatible `error` object. Common status codes are:
| Status | Meaning |
| ------------: | ------------------------------------------ |
| `400` | Invalid or unsupported request |
| `401` | Missing or invalid API key |
| `402` / `403` | Billing or key policy rejected the request |
| `413` | Request body too large |
| `429` | Stogas or provider rate limit |
| `503` | No provider route was available |
| `504` | Upstream request timed out |
| `529` | Provider overloaded |
Provider validation messages may be returned when useful. Provider credentials, topology, and internal failures are never exposed.
## Cancellation and billing [#cancellation-and-billing]
Disconnecting does not guarantee that the upstream provider stopped. A request may still be billed for usage the provider reports after the client disconnects. Streaming responses may remain open long enough to receive final usage needed for accurate settlement.
# API Security (/docs/reference/security)
## Authentication [#authentication]
Inference endpoints require a bearer API key:
```http
Authorization: Bearer
Content-Type: application/json
```
`/v1/catalog` and `/v1/models` are public. API keys are not accepted in query parameters or cookies.
## Browser access [#browser-access]
The public API allows cross-origin requests and uses bearer authentication rather than cookies:
```http
Access-Control-Allow-Origin: *
```
Do not expose a privileged API key in public browser code. Use a narrowly limited key or your own server when users must not receive the credential.
## Request handling [#request-handling]
* Unknown top-level JSON fields are rejected.
* Compressed bodies are checked after decompression; oversized bodies return `413`.
* Arbitrary client headers are not forwarded to providers.
* Provider response headers are hidden unless they are on the safe diagnostics allowlist.
* Client-supplied private Stogas and Bifrost control headers are rejected.
## Optional diagnostics [#optional-diagnostics]
Request safe response metadata with:
```http
X-Stogas-Return-Extra-Fields: provider,model_requested,latency
```
For request transformation debugging, `raw_request` and `raw_response` may also be requested. These fields can contain prompt or model-output data and should not be logged without an appropriate data policy.
{
"openapi": "3.1.0",
"info": {
"title": "Stogas Gateway API",
"summary": "OpenAI-compatible public API gateway.",
"description": "The Stogas Gateway exposes an OpenAI-compatible surface. Authenticate requests with your Stogas API key, and the gateway will relay the request to the configured upstream provider.",
"version": "1.0.0"
},
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"servers": [
{
"url": "{serverUrl}",
"description": "Gateway origin. Endpoint paths include their API version.",
"variables": {
"serverUrl": {
"default": "https://api.stogas.ai"
}
}
}
],
"paths": {
"/v1/catalog": {
"get": {
"operationId": "getCatalog",
"tags": [
"Catalog"
],
"summary": "Catalog",
"description": "Returns the active public gateway catalog used for model discovery, aliases, routing, and prices.",
"security": [],
"responses": {
"200": {
"description": "Active public catalog.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogResponse"
},
"examples": {
"catalog": {
"value": {
"version": "stogas.gateway.catalog.v1",
"generatedAt": "1970-01-01T00:00:01Z",
"graph": {
"models": {},
"deployments": {},
"providers": {},
"providerEndpoints": {},
"stogasEndpoints": {}
},
"indexes": {
"provider_endpoint_request_slugs": {}
}
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/CatalogUnavailable"
}
}
}
}
},
"components": {
"schemas": {
"CatalogResponse": {
"type": "object",
"required": [
"version",
"generatedAt",
"graph",
"indexes"
],
"properties": {
"version": {
"type": "string",
"example": "stogas.gateway.catalog.v1"
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp assigned to the generated catalog payload."
},
"graph": {
"type": "object",
"description": "Resolved catalog graph: authors, models, deployments, providers, routes, and gateway endpoints.",
"additionalProperties": true
},
"indexes": {
"type": "object",
"description": "Public lookup indexes, including provider-endpoint-scoped request slugs.",
"additionalProperties": true
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"responses": {
"CatalogUnavailable": {
"description": "Internal Server Error: The gateway catalog is not available.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Catalog unavailable",
"type": "internal_error"
}
}
}
}
}
}
},
"tags": [
{
"name": "Catalog",
"description": "Public model and routing discovery."
}
]
}
{
"openapi": "3.1.0",
"info": {
"title": "Stogas Gateway API",
"summary": "OpenAI-compatible public API gateway.",
"description": "The Stogas Gateway exposes an OpenAI-compatible surface. Authenticate requests with your Stogas API key, and the gateway will relay the request to the configured upstream provider.",
"version": "1.0.0"
},
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"servers": [
{
"url": "{serverUrl}",
"description": "Gateway origin. Endpoint paths include their API version.",
"variables": {
"serverUrl": {
"default": "https://api.stogas.ai"
}
}
}
],
"paths": {
"/v1/models": {
"get": {
"operationId": "listModels",
"tags": [
"Catalog"
],
"summary": "List Models",
"description": "Returns an OpenAI-compatible list of catalog model IDs accepted by the gateway.",
"security": [],
"responses": {
"200": {
"description": "OpenAI-compatible model list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelListResponse"
},
"examples": {
"models": {
"value": {
"object": "list",
"data": [
{
"id": "gpt-5.5-latest",
"object": "model",
"created": 1,
"owned_by": "stogas"
}
]
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/CatalogUnavailable"
}
}
}
}
},
"components": {
"schemas": {
"ModelListResponse": {
"type": "object",
"required": [
"object",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelObject"
}
}
}
},
"ModelObject": {
"type": "object",
"required": [
"id",
"object",
"created",
"owned_by"
],
"properties": {
"id": {
"type": "string",
"description": "Model ID or alias accepted by the gateway."
},
"object": {
"type": "string",
"const": "model"
},
"created": {
"type": "integer",
"description": "Stable OpenAI-compatible creation timestamp."
},
"owned_by": {
"type": "string",
"example": "stogas"
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"responses": {
"CatalogUnavailable": {
"description": "Internal Server Error: The gateway catalog is not available.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Catalog unavailable",
"type": "internal_error"
}
}
}
}
}
}
},
"tags": [
{
"name": "Catalog",
"description": "Public model and routing discovery."
}
]
}
{
"openapi": "3.1.0",
"info": {
"title": "Stogas Gateway API",
"summary": "OpenAI-compatible public API gateway.",
"description": "The Stogas Gateway exposes an OpenAI-compatible surface. Authenticate requests with your Stogas API key, and the gateway will relay the request to the configured upstream provider.",
"version": "1.0.0"
},
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"servers": [
{
"url": "{serverUrl}",
"description": "Gateway origin. Endpoint paths include their API version.",
"variables": {
"serverUrl": {
"default": "https://api.stogas.ai"
}
}
}
],
"paths": {
"/v1/chat/completions": {
"post": {
"operationId": "createChatCompletion",
"tags": [
"OpenAI-compatible"
],
"summary": "Chat Completions",
"description": "Create an OpenAI-compatible chat completion. The gateway resolves the requested model and route through the compiled Stogas catalog, applies deployment facts such as implied service tier, rejects unsupported parameters, and then relays the request to the configured provider.",
"parameters": [
{
"$ref": "#/components/parameters/ReturnExtraFields"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful completion. Non-streaming requests return JSON; streaming requests return Server-Sent Events.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionResponse"
}
},
"text/event-stream": {
"schema": {
"type": "string",
"description": "Server-Sent Events stream. Each `data:` frame contains a chat completion chunk; the stream ends with `data: [DONE]`."
},
"example": "data: {\"id\":\"8ee3487c-e5b1-4fe0-9dd6-84bc23ddd5f7\",\"object\":\"chat.completion.chunk\",\"created\":1714343120,\"model\":\"gpt-5.5\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"Hello\"},\"finish_reason\":null}]}\n\ndata: [DONE]\n\n"
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Stogas API key",
"description": "Pass the Stogas API key as `Authorization: Bearer `. This is the canonical OpenAI-compatible header."
},
"authorizationHeader": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"description": "Pass the Stogas API key directly as `Authorization: `. The gateway normalizes this to the canonical Bearer authentication path."
},
"apiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "api-key",
"description": "Catalog-defined authentication alias. The gateway canonicalizes `api-key: ` to `Authorization: Bearer `."
},
"xApiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Catalog-defined authentication alias. The gateway canonicalizes `x-api-key: ` to `Authorization: Bearer `."
},
"xGoogApiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "x-goog-api-key",
"description": "Catalog-defined authentication alias. The gateway canonicalizes `x-goog-api-key: ` to `Authorization: Bearer `."
}
},
"parameters": {
"ReturnExtraFields": {
"name": "X-Stogas-Return-Extra-Fields",
"in": "header",
"schema": {
"type": "string"
},
"description": "Comma-separated catalog-defined Stogas metadata fields to include under `stogas`, such as `provider`, `model_requested`, `model_deployment`, `latency`, `provider_response_headers`, `raw_request`, and `raw_response`."
}
},
"schemas": {
"ChatCompletionRequest": {
"type": "object",
"description": "OpenAI-compatible chat request fields parsed by the Stogas HTTP API.",
"additionalProperties": false,
"required": [
"model",
"messages"
],
"properties": {
"model": {
"type": "string",
"description": "Catalog model or deployment slug to route to, optionally provider-qualified, such as `gpt-5.5-latest`, `gpt-5.5-flex-latest`, or `openai/gpt-5.5-priority-latest`."
},
"provider": {
"$ref": "#/components/schemas/ProviderRoutingPreference",
"description": "Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
},
"rules": {
"$ref": "#/components/schemas/ProviderRoutingPreference",
"description": "Alias for `provider`. Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
},
"messages": {
"type": "array",
"description": "Conversation messages. Stogas currently accepts text-only content only.",
"items": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"audio": {
"type": "object",
"description": "Not supported by the text-only Stogas MVP. Requests that set audio are rejected before upstream dispatch.",
"properties": {
"format": {
"type": "string"
},
"voice": {
"type": "string"
}
}
},
"fallbacks": {
"type": "array",
"description": "Not supported. Stogas fallback policy is server-owned and client-supplied fallbacks are rejected.",
"items": {
"type": "string"
}
},
"function_call": {
"description": "Not supported. Deprecated Chat Completions function-calling fields are rejected; use `tools` and `tool_choice`.",
"oneOf": [
{
"type": "string"
},
{
"type": "object"
}
]
},
"functions": {
"type": "array",
"description": "Not supported. Deprecated Chat Completions function definitions are rejected; use `tools`.",
"items": {
"type": "object"
}
},
"container": {
"description": "Not supported. Stateful provider containers require separate lifecycle, isolation, and pricing controls.",
"oneOf": [
{
"type": "string"
},
{
"type": "object"
}
]
},
"stream": {
"type": "boolean",
"default": false
},
"frequency_penalty": {
"type": "number",
"description": "OpenAI-only Chat Completions frequency penalty. Anthropic deployments reject this field."
},
"logit_bias": {
"type": "object",
"description": "OpenAI-only token bias map. Values must be numbers because the gateway decodes the request into the OpenAI-compatible schema; provider-owned key semantics are left upstream. Anthropic deployments reject this field.",
"additionalProperties": {
"type": "number"
}
},
"logprobs": {
"type": "boolean",
"description": "OpenAI-only Chat Completions log probability output. Anthropic deployments reject this field."
},
"max_tokens": {
"type": "integer",
"minimum": 0,
"description": "Legacy maximum completion token field. Zero is only accepted for Anthropic cache prewarm requests that include an allowed cache_control marker."
},
"max_completion_tokens": {
"type": "integer",
"minimum": 0,
"description": "Maximum completion token cap. Zero is only accepted for Anthropic cache prewarm requests that include an allowed cache_control marker."
},
"metadata": {
"type": "object",
"description": "Application metadata for Stogas telemetry only. Stogas validates this object, logs it internally, and removes it before upstream dispatch.",
"maxProperties": 16,
"propertyNames": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"additionalProperties": {
"type": "string",
"maxLength": 512
}
},
"modalities": {
"type": "array",
"description": "Text-only MVP: when present, this must be exactly [\"text\"]. Image and audio modalities are rejected before upstream dispatch.",
"items": {
"type": "string",
"enum": [
"text"
]
}
},
"n": {
"type": "integer",
"description": "Number of choices to generate. Stogas currently accepts only omitted or `1`; larger values are rejected before upstream dispatch.",
"minimum": 1,
"maximum": 1
},
"parallel_tool_calls": {
"type": "boolean",
"description": "Whether the model may call multiple tools in parallel."
},
"prediction": {
"type": "object",
"description": "Predicted output content used by compatible OpenAI models to reduce latency."
},
"presence_penalty": {
"type": "number",
"description": "OpenAI-only Chat Completions presence penalty. Anthropic deployments reject this field."
},
"prompt_cache_key": {
"type": "string",
"description": "OpenAI-only prompt cache key. Must be non-empty UTF-8 up to 256 bytes and must not contain NUL, CR, or LF. Anthropic deployments reject this field; use `cache_control` instead.",
"minLength": 1,
"maxLength": 256
},
"prompt_cache_retention": {
"type": "string",
"description": "OpenAI-only prompt cache retention policy. Stogas validates that this is a string, normalizes known aliases before dispatch, and rejects this field on Anthropic deployments."
},
"prompt_cache_isolation_key": {
"type": "string",
"description": "Not supported. This provider-specific cache isolation field is outside the current OpenAI/Anthropic public Stogas surface."
},
"cache_control": {
"type": "object",
"description": "Anthropic-only prompt caching control. Stogas accepts `{type:\"ephemeral\"}` with optional `ttl:\"5m\"` or `\"1h\"`, validates explicit cache controls on text content/tool blocks, prices cache writes conservatively for holds, and rejects this field on OpenAI deployments.",
"properties": {
"type": {
"type": "string",
"enum": [
"ephemeral"
]
},
"ttl": {
"type": "string",
"enum": [
"5m",
"1h"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
"reasoning": {
"type": "object",
"description": "Reasoning configuration for models that expose reasoning controls.",
"properties": {
"enabled": {
"type": "boolean"
},
"effort": {
"type": "string"
},
"display": {
"type": "string"
},
"max_tokens": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"reasoning_effort": {
"type": "string",
"description": "Compatibility shortcut for `reasoning.effort`."
},
"reasoning_max_tokens": {
"type": "integer",
"minimum": 1,
"description": "Compatibility shortcut for `reasoning.max_tokens`."
},
"response_format": {
"type": "object",
"description": "Provider-owned output format constraint. Stogas forwards supported OpenAI-compatible fields and leaves provider-specific format details to the selected upstream provider.",
"properties": {
"type": {
"type": "string"
},
"json_schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"schema": {
"type": "object"
},
"strict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"task_budget": {
"type": "object",
"description": "Anthropic-only advisory token budget object for agentic loops. Provider-owned details are forwarded and do not reduce Stogas billing holds.",
"additionalProperties": true
},
"context_management": {
"type": "object",
"description": "Anthropic-only context management object. Provider-owned edit details are forwarded and do not reduce Stogas billing holds.",
"additionalProperties": true
},
"inference_geo": {
"type": "string",
"description": "Anthropic-only deployment routing hint. `global` selects standard multi-region pricing, while `us` selects US-only inference pricing. Stogas sends the selected Anthropic `inference_geo` upstream.",
"enum": [
"global",
"us"
]
},
"safety_identifier": {
"type": "string",
"description": "Client-supplied safety identifiers are not supported. Stogas sets provider-visible safety/user identifiers from the authenticated API key."
},
"seed": {
"type": "integer",
"description": "Best-effort deterministic sampling seed for providers that support it."
},
"service_tier": {
"type": "string",
"description": "Provider service tier selection preserved by the gateway. OpenAI accepts `auto`, `default`, `flex`, and `priority`; `scale` and `provisioned` are not available. Anthropic accepts `auto`, `priority`, `default`, `flex`, `standard`, and `standard_only`; all currently use standard-tier Stogas deployment rates. Anthropic `auto` / `priority` are sent upstream as `auto`, while `default` / `flex` / `standard` / `standard_only` are sent as `standard_only`.",
"enum": [
"auto",
"default",
"flex",
"priority",
"standard",
"standard_only"
]
},
"speed": {
"type": "string",
"description": "Anthropic-only deployment routing hint. `fast` selects cataloged fast-mode deployments where available; `standard` selects normal-speed deployments.",
"enum": [
"fast",
"standard"
]
},
"stream_options": {
"type": "object",
"description": "Additional options for streamed Chat Completions. Requires `stream:true`. Stogas accepts `include_usage` and always forces it to `true`; `include_obfuscation` is not supported on Chat Completions.",
"properties": {
"include_usage": {
"type": "boolean"
}
},
"additionalProperties": false
},
"stop": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "OpenAI-compatible stop sequence or stop sequence array. Stogas validates JSON shape and normalizes the string shorthand to an array before upstream dispatch; provider-owned value limits are left to the selected provider."
},
"stop_sequences": {
"type": "array",
"description": "Anthropic-only stop sequence alias. Stogas rejects this field on OpenAI deployments and rejects requests that set both `stop` and `stop_sequences`.",
"items": {
"type": "string"
}
},
"store": {
"type": "boolean",
"description": "Not supported. Provider retention behavior is server-owned; requests that set store are rejected before upstream dispatch, and OpenAI-bound requests are forced to store:false."
},
"temperature": {
"type": "number",
"default": 1,
"description": "Sampling temperature. Stogas validates JSON shape only; provider-owned numeric bounds are left to the selected provider. Anthropic deployments reject requests that set both `temperature` and `top_p`."
},
"tool_choice": {
"type": [
"string",
"object"
],
"description": "Tool choice. Chat Completions accepts `auto`, `none`, `required`, declared function choices, and custom tool choices where supported."
},
"tools": {
"type": "array",
"description": "Tool definitions. Chat Completions accepts function tools for OpenAI and Anthropic, custom tools where supported, and Anthropic-only `mcp_toolset` entries paired one-to-one with `mcp_servers`.",
"items": {
"type": "object"
}
},
"mcp_servers": {
"type": "array",
"description": "Anthropic Chat only. Remote MCP server definitions paired one-to-one with `tools[].type=\"mcp_toolset\"`; each server must be `type:\"url\"` with an HTTPS URL and unique name.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"url"
]
},
"url": {
"type": "string",
"format": "uri"
},
"name": {
"type": "string"
},
"authorization_token": {
"type": "string",
"description": "Forwarded upstream and redacted from Stogas raw request metadata."
}
},
"required": [
"type",
"url",
"name"
]
}
},
"top_logprobs": {
"type": "integer",
"description": "Provider-owned OpenAI Chat Completions log probability detail."
},
"top_k": {
"type": "integer",
"description": "Anthropic-only sampling control. Rejected for OpenAI deployments."
},
"top_p": {
"type": "number",
"description": "Nucleus sampling control. Stogas validates JSON shape only; provider-owned numeric bounds are left to the selected provider. Anthropic deployments reject requests that set both `temperature` and `top_p`."
},
"user": {
"type": "string",
"description": "Client-supplied user identifiers are not supported. Stogas sets upstream user identity from the authenticated API key."
},
"verbosity": {
"type": "string",
"description": "Text verbosity preference for models that support it."
},
"reasoning_display": {
"type": "string"
},
"web_search_options": {
"type": "object",
"properties": {
"search_context_size": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
"user_location": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"const": "approximate"
},
"approximate": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"region": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"example": {
"model": "gpt-5.5-latest",
"messages": [
{
"role": "user",
"content": "Reflect on the issue of trusting trust"
}
],
"temperature": 0.7
}
},
"ChatCompletionResponse": {
"type": "object",
"description": "Chat completion response",
"properties": {
"id": {
"type": "string",
"description": "Unique completion identifier"
},
"object": {
"type": "string",
"description": "The object type, which is always \"chat.completion\""
},
"created": {
"type": "integer",
"description": "Unix timestamp of creation"
},
"model": {
"type": "string",
"description": "Model used for completion"
},
"choices": {
"type": "array",
"description": "List of completion choices",
"items": {
"$ref": "#/components/schemas/ChatChoice"
}
},
"usage": {
"$ref": "#/components/schemas/ChatUsage"
},
"stogas": {
"type": "object",
"title": "Gateway Metadata",
"description": "Optional Stogas metadata returned when requested with Stogas debug headers.",
"properties": {
"provider": {
"type": "string",
"description": "The upstream AI provider that served the request"
},
"latency": {
"type": "integer",
"description": "Total round-trip latency in milliseconds"
},
"model_requested": {
"type": "string",
"description": "The exact model alias or name requested"
},
"model_deployment": {
"type": "string",
"description": "The upstream model deployment selected by the gateway"
},
"provider_response_headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Catalog-approved response headers from the upstream provider"
},
"raw_request": {
"type": [
"object",
"array",
"string",
"number",
"boolean",
"null"
],
"description": "The translated upstream provider request, returned when requested."
},
"raw_response": {
"type": [
"object",
"array",
"string",
"number",
"boolean",
"null"
],
"description": "The raw upstream provider JSON body, returned when requested."
}
}
}
},
"required": [
"id",
"object",
"created",
"model",
"choices"
],
"example": {
"id": "8ee3487c-e5b1-4fe0-9dd6-84bc23ddd5f7",
"object": "chat.completion",
"created": 1714343120,
"model": "gpt-5.5",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "You can never fully trust code you did not write yourself."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 11,
"total_tokens": 20
},
"stogas": {
"provider": "OpenAI",
"latency": 842,
"model_requested": "gpt-5.5-latest"
}
}
},
"ProviderRoutingPreference": {
"oneOf": [
{
"type": "string",
"description": "Known provider ID or provider slug, such as `openai`, `open-ai`, or `anthropic`."
},
{
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"only"
]
},
{
"required": [
"order"
]
}
],
"properties": {
"only": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Provider IDs or provider slugs allowed to serve this request."
},
"order": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Preferred provider order after the optional `only` filter is applied."
}
},
"description": "Stogas-owned provider routing rules. At least one of `only` or `order` is required."
}
],
"description": "Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
},
"ChatMessage": {
"type": "object",
"required": [
"role"
],
"properties": {
"name": {
"type": "string",
"description": "Optional participant name."
},
"role": {
"type": "string",
"enum": [
"system",
"user",
"assistant",
"tool",
"developer"
]
},
"content": {
"$ref": "#/components/schemas/ChatMessageContent"
},
"tool_call_id": {
"type": "string",
"description": "Tool call ID for tool response messages."
},
"refusal": {
"type": "string",
"description": "Assistant refusal text when provided by the model."
},
"audio": {
"type": "object",
"description": "Not supported in Chat Completions requests. Stogas is text-only for the MVP and rejects message-level audio before upstream dispatch."
},
"reasoning": {
"type": "string",
"description": "Reasoning output when returned by the provider."
},
"reasoning_details": {
"type": "array",
"items": {
"type": "object"
}
},
"annotations": {
"type": "array",
"items": {
"type": "object"
}
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatToolCall"
}
}
}
},
"ChatChoice": {
"type": "object",
"description": "Chat completion choice",
"properties": {
"index": {
"type": "integer",
"description": "Choice index"
},
"message": {
"$ref": "#/components/schemas/ChatAssistantMessage"
},
"finish_reason": {
"type": "string",
"description": "Reason why the model stopped generating",
"enum": [
"stop",
"length",
"tool_calls",
"content_filter",
"error"
]
}
},
"required": [
"index",
"message",
"finish_reason"
]
},
"ChatUsage": {
"type": "object",
"description": "Token usage statistics",
"properties": {
"prompt_tokens": {
"type": "integer",
"description": "Number of tokens in the prompt"
},
"completion_tokens": {
"type": "integer",
"description": "Number of tokens in the completion"
},
"total_tokens": {
"type": "integer",
"description": "Total number of tokens used"
}
},
"required": [
"prompt_tokens",
"completion_tokens",
"total_tokens"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
},
"ChatMessageContent": {
"description": "Message content as either a string or an array of content blocks.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatContentBlock"
}
}
]
},
"ChatToolCall": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"function"
]
},
"function": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"arguments": {
"type": "string"
}
}
}
}
},
"ChatAssistantMessage": {
"type": "object",
"description": "Assistant message",
"properties": {
"role": {
"type": "string",
"enum": [
"assistant"
]
},
"content": {
"$ref": "#/components/schemas/ChatMessageContent",
"description": "Assistant message content"
},
"tool_calls": {
"type": "array",
"description": "Tool calls made by the assistant",
"items": {
"$ref": "#/components/schemas/ChatToolCall"
}
}
},
"required": [
"role"
]
},
"ChatContentBlock": {
"type": "object",
"description": "Text-only chat content block accepted by Stogas.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
}
}
}
},
"responses": {
"BadRequest": {
"description": "Bad Request: The request was malformed, missing required fields, or specifying an unavailable model.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Invalid text completion request: the 'messages' array cannot be empty.",
"type": "invalid_request_error"
}
}
}
}
},
"Unauthorized": {
"description": "Unauthorized: The API key provided was missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Invalid API key",
"type": "authentication_error"
}
}
}
}
},
"PaymentRequired": {
"description": "Payment Required: Returned when your account balance is insufficient or the API key lifetime or recurring spend limit is exhausted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Insufficient balance. Please add funds to your Stogas account to continue making requests.",
"type": "billing_error"
}
}
}
}
},
"Forbidden": {
"description": "Forbidden: The API key is disabled or expired. Expired keys are disabled automatically before the error is returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "API key is disabled",
"type": "permission_denied"
}
}
}
}
},
"NotFound": {
"description": "Not Found: The requested endpoint route does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Not Found: The requested endpoint '/v1/chat/compl' does not exist.",
"type": "invalid_request_error"
}
}
}
}
},
"Conflict": {
"description": "Conflict: The gateway request ID was already finalized, expired, or reused with different hold parameters. Generate a new request ID and retry.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Request already finalized; generate a new requestId",
"type": "invalid_request_error"
}
}
}
}
},
"PayloadTooLarge": {
"description": "Payload Too Large: The request body exceeds the gateway's maximum allowed size.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Payload Too Large: The request body exceeds the maximum allowed size of 100MB.",
"type": "invalid_request_error"
}
}
}
}
},
"RateLimited": {
"description": "Rate Limited: The API key token bucket does not currently have capacity for another request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "API key rate limit exceeded",
"type": "rate_limit_error"
}
}
}
}
},
"InternalError": {
"description": "Internal Server Error: An unexpected error occurred within the gateway or upstream provider.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Upstream provider error",
"type": "gateway_error"
}
}
}
}
},
"ServiceUnavailable": {
"description": "Service Unavailable: The gateway could not reach the billing database while placing the authorization hold. The provider is not called and no usage telemetry is written.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Gateway billing database unavailable",
"type": "gateway_error"
}
}
}
}
}
}
},
"tags": [
{
"name": "OpenAI-compatible",
"description": "Model inference endpoints."
}
],
"security": [
{
"bearerAuth": []
},
{
"authorizationHeader": []
},
{
"apiKeyHeader": []
},
{
"xApiKeyHeader": []
},
{
"xGoogApiKeyHeader": []
}
]
}
{
"openapi": "3.1.0",
"info": {
"title": "Stogas Gateway API",
"summary": "OpenAI-compatible public API gateway.",
"description": "The Stogas Gateway exposes an OpenAI-compatible surface. Authenticate requests with your Stogas API key, and the gateway will relay the request to the configured upstream provider.",
"version": "1.0.0"
},
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"servers": [
{
"url": "{serverUrl}",
"description": "Gateway origin. Endpoint paths include their API version.",
"variables": {
"serverUrl": {
"default": "https://api.stogas.ai"
}
}
}
],
"paths": {
"/v1/responses": {
"post": {
"operationId": "createResponse",
"tags": [
"OpenAI-compatible"
],
"summary": "Responses",
"description": "Create an OpenAI-compatible Responses API response. The gateway resolves the requested model and route through the compiled Stogas catalog, applies deployment facts such as implied service tier, rejects unsupported parameters, and then relays the request to the configured provider.",
"parameters": [
{
"$ref": "#/components/parameters/ReturnExtraFields"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response. Non-streaming requests return JSON; streaming requests return Server-Sent Events.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseObject"
}
},
"text/event-stream": {
"schema": {
"type": "string",
"description": "Server-Sent Events stream. Each `data:` frame contains a Responses API event; the stream ends with `data: [DONE]`."
},
"example": "data: {\"type\":\"response.created\",\"response\":{\"id\":\"8ee3487c-e5b1-4fe0-9dd6-84bc23ddd5f7\",\"object\":\"response\",\"created_at\":1714343120,\"status\":\"in_progress\",\"model\":\"gpt-5.5\",\"output\":[]}}\n\ndata: {\"type\":\"response.output_text.delta\",\"item_id\":\"msg_0192f217-35b0-7e2c-9be7-f4cc24f2a4b0\",\"output_index\":0,\"content_index\":0,\"delta\":\"Hello\"}\n\ndata: [DONE]\n\n"
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Stogas API key",
"description": "Pass the Stogas API key as `Authorization: Bearer `. This is the canonical OpenAI-compatible header."
},
"authorizationHeader": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"description": "Pass the Stogas API key directly as `Authorization: `. The gateway normalizes this to the canonical Bearer authentication path."
},
"apiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "api-key",
"description": "Catalog-defined authentication alias. The gateway canonicalizes `api-key: ` to `Authorization: Bearer `."
},
"xApiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Catalog-defined authentication alias. The gateway canonicalizes `x-api-key: ` to `Authorization: Bearer `."
},
"xGoogApiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "x-goog-api-key",
"description": "Catalog-defined authentication alias. The gateway canonicalizes `x-goog-api-key: ` to `Authorization: Bearer `."
}
},
"parameters": {
"ReturnExtraFields": {
"name": "X-Stogas-Return-Extra-Fields",
"in": "header",
"schema": {
"type": "string"
},
"description": "Comma-separated catalog-defined Stogas metadata fields to include under `stogas`, such as `provider`, `model_requested`, `model_deployment`, `latency`, `provider_response_headers`, `raw_request`, and `raw_response`."
}
},
"schemas": {
"ResponsesRequest": {
"type": "object",
"description": "OpenAI-compatible Responses API request fields parsed by the Stogas HTTP API.",
"additionalProperties": false,
"required": [
"model",
"input"
],
"properties": {
"model": {
"type": "string"
},
"provider": {
"$ref": "#/components/schemas/ProviderRoutingPreference",
"description": "Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
},
"rules": {
"$ref": "#/components/schemas/ProviderRoutingPreference",
"description": "Alias for `provider`. Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
},
"input": {
"description": "Input for the Responses API. Stogas accepts a plain string or an array of Responses input/output items.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ResponsesRequestInputItem"
}
}
]
},
"stream": {
"type": "boolean",
"default": false
},
"background": {
"type": "boolean",
"description": "Not supported. Background Responses require asynchronous lifecycle and reconciliation support, so Stogas rejects this field."
},
"conversation": {
"type": "string",
"description": "Not supported. Provider-side conversation state hides prompt reconstruction before hold placement, so Stogas rejects this field."
},
"fallbacks": {
"type": "array",
"description": "Not supported. Stogas fallback policy is server-owned and client-supplied fallbacks are rejected.",
"items": {
"type": "string"
}
},
"container": {
"description": "Not supported. Stateful provider containers require separate lifecycle, isolation, and pricing controls.",
"oneOf": [
{
"type": "string"
},
{
"type": "object"
}
]
},
"include": {
"type": "array",
"description": "Additional OpenAI Responses fields to request. Values are provider-owned and not enum-mirrored by Stogas; Anthropic-backed deployments reject this OpenAI-only field.",
"items": {
"type": "string"
}
},
"instructions": {
"type": "string"
},
"max_output_tokens": {
"type": "integer",
"minimum": 0,
"description": "Maximum output token cap. Zero is only accepted for Anthropic cache prewarm requests that include an allowed cache_control marker."
},
"max_tool_calls": {
"type": "integer",
"minimum": 1,
"description": "Optional cap for priced hosted Responses tools. If omitted for priced hosted tools, Stogas injects an effective cap of 50 before dispatch. On Anthropic Responses, this field is only accepted when Stogas can translate it to hosted-tool max_uses; token-priced function, custom, and MCP tools must omit it."
},
"metadata": {
"type": "object",
"description": "Application metadata for Stogas telemetry only. Stogas validates this object, logs it internally, and removes it before upstream dispatch.",
"maxProperties": 16,
"propertyNames": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"additionalProperties": {
"type": "string",
"maxLength": 512
}
},
"parallel_tool_calls": {
"type": "boolean",
"description": "Whether the model may call multiple tools in parallel."
},
"previous_response_id": {
"type": "string",
"description": "Not supported. Provider-side continuation state hides prompt reconstruction before hold placement, so Stogas rejects this field."
},
"task_budget": {
"type": "object",
"description": "Anthropic-only advisory token budget object forwarded as output_config.task_budget. Provider-owned details do not reduce Stogas billing holds.",
"additionalProperties": true
},
"context_management": {
"type": "object",
"description": "Anthropic-only context management object forwarded as provider-owned runtime behavior. Stogas does not treat compaction as a hold reduction.",
"additionalProperties": true
},
"inference_geo": {
"type": "string",
"description": "Anthropic-only deployment routing hint. `global` selects standard multi-region pricing, while `us` selects US-only inference pricing. Stogas sends the selected Anthropic `inference_geo` upstream.",
"enum": [
"global",
"us"
]
},
"prompt_cache_key": {
"type": "string",
"description": "OpenAI-only prompt cache key. Must be non-empty UTF-8 up to 256 bytes and must not contain NUL, CR, or LF. Anthropic deployments reject this field; use `cache_control` instead.",
"minLength": 1,
"maxLength": 256
},
"reasoning": {
"type": "object",
"description": "Reasoning configuration for models that expose reasoning controls.",
"properties": {
"effort": {
"type": "string"
},
"summary": {
"type": "string"
},
"generate_summary": {
"type": "string",
"description": "Deprecated upstream alias for `summary`."
},
"max_tokens": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"safety_identifier": {
"type": "string",
"description": "Client-supplied safety identifiers are not supported. Stogas sets provider-visible safety/user identifiers from the authenticated API key."
},
"service_tier": {
"type": "string",
"description": "Provider service tier selection preserved by the gateway. OpenAI accepts `auto`, `default`, `flex`, and `priority`; `scale` and `provisioned` are not available. Anthropic accepts `auto`, `priority`, `default`, `flex`, `standard`, and `standard_only`; all currently use standard-tier Stogas deployment rates. Anthropic `auto` / `priority` are sent upstream as `auto`, while `default` / `flex` / `standard` / `standard_only` are sent as `standard_only`.",
"enum": [
"auto",
"default",
"flex",
"priority",
"standard",
"standard_only"
]
},
"speed": {
"type": "string",
"description": "Anthropic-only deployment routing hint. `fast` selects cataloged fast-mode deployments where available; `standard` selects normal-speed deployments.",
"enum": [
"fast",
"standard"
]
},
"stream_options": {
"type": "object",
"description": "Additional options for streamed Responses. Requires `stream:true`. Stogas accepts `include_obfuscation`; `include_usage` is server-owned and rejected on this route.",
"properties": {
"include_obfuscation": {
"type": "boolean"
}
},
"additionalProperties": false
},
"store": {
"type": "boolean",
"description": "Not supported. Provider retention behavior is server-owned; requests that set store are rejected before upstream dispatch, and OpenAI-bound requests are forced to store:false."
},
"temperature": {
"type": "number",
"default": 1,
"description": "Sampling temperature. Stogas validates JSON shape only; provider-owned numeric bounds are left to the selected provider. Anthropic deployments reject requests that set both `temperature` and `top_p`."
},
"frequency_penalty": {
"type": "number",
"description": "OpenAI-only Responses frequency penalty. Anthropic deployments reject this field."
},
"presence_penalty": {
"type": "number",
"description": "OpenAI-only Responses presence penalty. Anthropic deployments reject this field."
},
"text": {
"type": "object",
"description": "Text output configuration, including structured output format and verbosity.",
"properties": {
"format": {
"type": "object",
"description": "Provider-owned Responses text format. Stogas forwards supported OpenAI-compatible fields and leaves provider-specific format details to the selected upstream provider.",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"schema": {
"type": "object"
},
"strict": {
"type": "boolean"
}
},
"additionalProperties": true
},
"verbosity": {
"type": "string"
}
},
"additionalProperties": true
},
"top_logprobs": {
"type": "integer",
"description": "Provider-owned Responses log probability detail. Anthropic deployments reject this OpenAI-only field."
},
"top_k": {
"type": "integer",
"description": "Anthropic-only sampling control passed through the explicit Stogas allowlist. Rejected for OpenAI deployments."
},
"top_p": {
"type": "number",
"description": "Nucleus sampling control. Stogas validates JSON shape only; provider-owned numeric bounds are left to the selected provider. Anthropic deployments reject requests that set both `temperature` and `top_p`."
},
"tool_choice": {
"type": [
"string",
"object"
],
"description": "Tool choice, such as `auto`, `none`, `required`, or a named tool object."
},
"tools": {
"type": "array",
"description": "Responses API tool definitions accepted by compatible providers. Stogas admits function/custom tools, remote MCP tools with narrowed allowed_tools, priced provider-hosted web search tools, and Anthropic web_fetch tools. See the Model Tools guide for the current provider matrix and billing behavior.",
"items": {
"type": "object"
}
},
"truncation": {
"type": "string"
},
"user": {
"type": "string",
"description": "Client-supplied user identifiers are not supported. Stogas sets upstream user identity from the authenticated API key."
},
"prompt_cache_retention": {
"type": "string",
"description": "OpenAI-only prompt cache retention policy. Stogas validates that this is a string, normalizes known aliases before dispatch, and rejects this field on Anthropic deployments."
},
"stop_sequences": {
"type": "array",
"description": "Anthropic-only stop sequence alias passed through the explicit Stogas allowlist. Stogas rejects this field on OpenAI deployments. Responses does not admit top-level `stop`; Chat rejects requests that set both `stop` and `stop_sequences`.",
"items": {
"type": "string"
}
},
"cache_control": {
"type": "object",
"description": "Anthropic-only prompt caching control. Stogas accepts `{type:\"ephemeral\"}` with optional `ttl:\"5m\"` or `\"1h\"`, validates explicit cache controls on input content/tool blocks, prices cache writes conservatively for holds, and rejects this field on OpenAI deployments.",
"properties": {
"type": {
"type": "string",
"enum": [
"ephemeral"
]
},
"ttl": {
"type": "string",
"enum": [
"5m",
"1h"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
"reasoning.effort": {
"type": "string"
}
},
"example": {
"model": "gpt-5.5-latest",
"input": "Reflect on the issue of trusting trust",
"temperature": 0.7
}
},
"ResponseObject": {
"type": "object",
"description": "Non-streaming OpenAI-compatible Responses API response.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique response identifier generated by the gateway."
},
"object": {
"type": "string",
"enum": [
"response"
],
"description": "The object type, which is always `response`."
},
"created_at": {
"type": "integer",
"description": "Unix timestamp of response creation."
},
"completed_at": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp of response completion."
},
"status": {
"type": "string",
"enum": [
"completed",
"failed",
"in_progress",
"cancelled",
"queued",
"incomplete"
]
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"incomplete_details": {
"type": [
"object",
"null"
],
"properties": {
"reason": {
"type": "string"
}
}
},
"model": {
"type": "string",
"description": "Model used for the response."
},
"output": {
"type": "array",
"description": "Response output items.",
"items": {
"$ref": "#/components/schemas/ResponsesInputItem"
}
},
"output_text": {
"type": "string",
"description": "Convenience concatenation of output text content when available."
},
"background": {
"type": "boolean"
},
"conversation": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
}
}
},
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"instructions": {
"type": [
"string",
"array",
"null"
]
},
"max_output_tokens": {
"type": [
"integer",
"null"
]
},
"max_tool_calls": {
"type": [
"integer",
"null"
]
},
"metadata": {
"type": "object"
},
"parallel_tool_calls": {
"type": "boolean"
},
"previous_response_id": {
"type": [
"string",
"null"
]
},
"prompt_cache_key": {
"type": [
"string",
"null"
]
},
"reasoning": {
"type": "object"
},
"safety_identifier": {
"type": [
"string",
"null"
]
},
"service_tier": {
"type": [
"string",
"null"
]
},
"store": {
"type": "boolean"
},
"temperature": {
"type": "number"
},
"text": {
"type": "object"
},
"tool_choice": {
"type": [
"string",
"object"
]
},
"tools": {
"type": "array",
"items": {
"type": "object"
}
},
"top_logprobs": {
"type": "integer"
},
"top_p": {
"type": "number"
},
"truncation": {
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/ResponsesUsage"
},
"stogas": {
"type": "object",
"title": "Gateway Metadata",
"description": "Optional Stogas metadata returned when requested with Stogas debug headers.",
"properties": {
"provider": {
"type": "string",
"description": "The upstream AI provider that served the request"
},
"latency": {
"type": "integer",
"description": "Total round-trip latency in milliseconds"
},
"model_requested": {
"type": "string",
"description": "The exact model alias or name requested"
},
"model_deployment": {
"type": "string",
"description": "The upstream model deployment selected by the gateway"
},
"provider_response_headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Catalog-approved response headers from the upstream provider"
},
"raw_request": {
"type": [
"object",
"array",
"string",
"number",
"boolean",
"null"
],
"description": "The translated upstream provider request, returned when requested."
},
"raw_response": {
"type": [
"object",
"array",
"string",
"number",
"boolean",
"null"
],
"description": "The raw upstream provider JSON body, returned when requested."
}
}
}
},
"required": [
"id",
"object",
"created_at",
"model",
"output",
"status"
],
"example": {
"id": "8ee3487c-e5b1-4fe0-9dd6-84bc23ddd5f7",
"object": "response",
"created_at": 1714343120,
"completed_at": 1714343121,
"status": "completed",
"error": null,
"incomplete_details": null,
"model": "gpt-5.5",
"output": [
{
"id": "msg_0192f217-35b0-7e2c-9be7-f4cc24f2a4b0",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "You can never fully trust code you did not write yourself."
}
]
}
],
"output_text": "You can never fully trust code you did not write yourself.",
"usage": {
"input_tokens": 9,
"output_tokens": 11,
"total_tokens": 20
}
}
},
"ProviderRoutingPreference": {
"oneOf": [
{
"type": "string",
"description": "Known provider ID or provider slug, such as `openai`, `open-ai`, or `anthropic`."
},
{
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"only"
]
},
{
"required": [
"order"
]
}
],
"properties": {
"only": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Provider IDs or provider slugs allowed to serve this request."
},
"order": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Preferred provider order after the optional `only` filter is applied."
}
},
"description": "Stogas-owned provider routing rules. At least one of `only` or `order` is required."
}
],
"description": "Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
},
"ResponsesRequestInputItem": {
"type": "object",
"description": "Text-only Responses API input item accepted by Stogas. Function calls, tool outputs, reasoning items, files, images, and audio inputs are rejected before upstream dispatch.",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"message",
"input_text",
"output_text",
"refusal"
]
},
"status": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"assistant",
"user",
"system",
"developer"
]
},
"content": {
"$ref": "#/components/schemas/ResponsesRequestMessageContent"
},
"text": {
"type": "string"
},
"refusal": {
"type": "string"
}
}
},
"ResponsesInputItem": {
"type": "object",
"description": "Responses API input or previous output item. Supported item types include messages, function calls and outputs, tool calls, reasoning, and item references.",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"message",
"web_search_call",
"function_call",
"function_call_output",
"mcp_call",
"custom_tool_call",
"custom_tool_call_output",
"mcp_list_tools",
"mcp_approval_request",
"mcp_approval_responses",
"reasoning",
"item_reference",
"refusal"
]
},
"status": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"assistant",
"user",
"system",
"developer"
]
},
"content": {
"$ref": "#/components/schemas/ResponsesMessageContent"
},
"call_id": {
"type": "string"
},
"name": {
"type": "string"
},
"arguments": {
"type": "string"
},
"output": {
"description": "Tool output payload for function_call_output and related output items."
},
"summary": {
"type": "array",
"items": {
"type": "object"
}
},
"encrypted_content": {
"type": "string"
}
}
},
"ResponsesUsage": {
"type": "object",
"description": "Responses API token usage statistics.",
"properties": {
"input_tokens": {
"type": "integer",
"description": "Number of input tokens."
},
"output_tokens": {
"type": "integer",
"description": "Number of output tokens."
},
"total_tokens": {
"type": "integer",
"description": "Total number of tokens."
},
"input_tokens_details": {
"type": "object",
"properties": {
"text_tokens": {
"type": "integer"
},
"audio_tokens": {
"type": "integer"
},
"image_tokens": {
"type": "integer"
},
"cached_tokens": {
"type": "integer"
},
"cached_read_tokens": {
"type": "integer"
},
"cached_write_tokens": {
"type": "integer"
}
}
},
"output_tokens_details": {
"type": "object",
"properties": {
"text_tokens": {
"type": "integer"
},
"audio_tokens": {
"type": "integer"
},
"image_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"accepted_prediction_tokens": {
"type": "integer"
},
"rejected_prediction_tokens": {
"type": "integer"
}
}
},
"cost": {
"type": [
"number",
"null"
],
"description": "Upstream inference cost when available."
}
},
"required": [
"input_tokens",
"output_tokens",
"total_tokens"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
},
"ResponsesRequestMessageContent": {
"description": "Text-only Responses message content as either a string or an array of text content blocks.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ResponsesRequestContentBlock"
}
}
]
},
"ResponsesMessageContent": {
"description": "Responses message content as either a string or an array of content blocks.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ResponsesContentBlock"
}
}
]
},
"ResponsesRequestContentBlock": {
"type": "object",
"description": "Text-only Responses content block accepted by Stogas.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"input_text",
"output_text",
"refusal"
]
},
"text": {
"type": "string"
},
"refusal": {
"type": "string"
}
}
},
"ResponsesContentBlock": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"input_text",
"output_text",
"refusal",
"reasoning_text",
"rendered_content",
"compaction"
]
},
"text": {
"type": "string"
},
"refusal": {
"type": "string"
},
"annotations": {
"type": "array",
"items": {
"type": "object"
}
},
"logprobs": {
"type": "array",
"items": {
"type": "object"
}
},
"signature": {
"type": "string"
},
"citations": {
"type": "object"
}
}
}
},
"responses": {
"BadRequest": {
"description": "Bad Request: The request was malformed, missing required fields, or specifying an unavailable model.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Invalid text completion request: the 'messages' array cannot be empty.",
"type": "invalid_request_error"
}
}
}
}
},
"Unauthorized": {
"description": "Unauthorized: The API key provided was missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Invalid API key",
"type": "authentication_error"
}
}
}
}
},
"PaymentRequired": {
"description": "Payment Required: Returned when your account balance is insufficient or the API key lifetime or recurring spend limit is exhausted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Insufficient balance. Please add funds to your Stogas account to continue making requests.",
"type": "billing_error"
}
}
}
}
},
"Forbidden": {
"description": "Forbidden: The API key is disabled or expired. Expired keys are disabled automatically before the error is returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "API key is disabled",
"type": "permission_denied"
}
}
}
}
},
"NotFound": {
"description": "Not Found: The requested endpoint route does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Not Found: The requested endpoint '/v1/chat/compl' does not exist.",
"type": "invalid_request_error"
}
}
}
}
},
"Conflict": {
"description": "Conflict: The gateway request ID was already finalized, expired, or reused with different hold parameters. Generate a new request ID and retry.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Request already finalized; generate a new requestId",
"type": "invalid_request_error"
}
}
}
}
},
"PayloadTooLarge": {
"description": "Payload Too Large: The request body exceeds the gateway's maximum allowed size.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Payload Too Large: The request body exceeds the maximum allowed size of 100MB.",
"type": "invalid_request_error"
}
}
}
}
},
"RateLimited": {
"description": "Rate Limited: The API key token bucket does not currently have capacity for another request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "API key rate limit exceeded",
"type": "rate_limit_error"
}
}
}
}
},
"InternalError": {
"description": "Internal Server Error: An unexpected error occurred within the gateway or upstream provider.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Upstream provider error",
"type": "gateway_error"
}
}
}
}
},
"ServiceUnavailable": {
"description": "Service Unavailable: The gateway could not reach the billing database while placing the authorization hold. The provider is not called and no usage telemetry is written.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": {
"message": "Gateway billing database unavailable",
"type": "gateway_error"
}
}
}
}
}
}
},
"tags": [
{
"name": "OpenAI-compatible",
"description": "Model inference endpoints."
}
],
"security": [
{
"bearerAuth": []
},
{
"authorizationHeader": []
},
{
"apiKeyHeader": []
},
{
"xApiKeyHeader": []
},
{
"xGoogApiKeyHeader": []
}
]
}