Gateway overview

The AI Gateway is Ethen’s request path for selecting an eligible provider, invoking a model, and returning a response with route metadata. Use this overview before you create credentials or depend on a particular provider.

The product surface identifies the managed Gateway as Beta and may report setup-required conditions even though the locked manifest records GA maturity.

A useful way to read the Gateway is as a sequence of independently observable decisions rather than a single model call. The application proves its identity with an Ethen key, the handler validates the request and model status, the routing runtime narrows provider choices, and an adapter performs the outbound call. Logs and usage then describe what happened. This sequence is also the product boundary: Model Library can tell you that a model is known, and Model Intelligence can help compare models, but only a successful Gateway request demonstrates that a provider route executed in the current project and environment.

What the Gateway does

The Gateway owns execution decisions after a client has selected a model identifier. Model Library is the catalog and status surface, while Model Intelligence presents profiles and comparative research. Neither surface substitutes for the runtime checks that occur when a request arrives. A catalog entry can therefore be discoverable even when credentials, policy, provider health, or project configuration prevent execution.

The Gateway accepts chat-completion requests at the verified inbound route and resolves them through Ethen routing controls.

It separates a requested model from the provider that ultimately executes it.

It returns OpenAI-style output plus Ethen request, trace, provider, attempt, and fallback metadata.

Use the Gateway when the application needs one Ethen entry point for chat completion while retaining route and attempt context. Model research belongs in Model Intelligence, and catalog browsing belongs in Model Library; neither surface performs the provider invocation described here.

The verified inbound chat route is POST /api/gateway/v1/chat/completions. Runtime cards distinguish runnable models, configured providers, setup-required providers, and unsupported modalities.

The product surface groups model catalog, provider status, request logs, usage tracking, API-key management, and BYOK. The models endpoint returns catalog data together with parser diagnostics rather than a strict OpenAI models payload.

Core capabilities

The Gateway surface combines several concerns that are related but not interchangeable. The catalog answers whether Ethen knows about a model. Provider status describes whether a project has the configuration needed to attempt that model. The routing runtime evaluates provider availability, policy, project restrictions, credentials, circuit state, aliases, and timeout settings before an adapter is called. Request logs and usage records describe the resulting operation after the handler has accepted it. API-key management authenticates the application to Ethen, while BYOK supplies a provider credential for an eligible outbound route.

This separation matters when a model appears in the catalog but cannot run. A catalog-only record is not a routing failure; it is a readiness state. A missing provider key is not an invalid Ethen API key; it is an outbound credential problem. An unsupported modality is not repaired by changing the provider order. Treat each status as a different decision point instead of reducing them to a single available or unavailable label.

Its core surfaces cover the model catalog, provider status, request logs, usage tracking, API-key management, and project-scoped BYOK.

The status model distinguishes catalog-only models, configured providers, runnable models, setup-required providers, and unsupported modalities.

Where configured, routing supports provider order, allow-listing, model aliases, provider timeouts, retries, and fallbacks.

The core surfaces answer different operational questions. The catalog identifies known models, provider status reports configuration, logs explain individual requests, usage summarizes consumption, API keys authenticate callers, and BYOK supplies provider credentials for eligible outbound routes.

Chat responses add Ethen request, trace, provider, attempt, and fallback metadata to an OpenAI-style response.

Array-form message content is accepted, but image entries are normalized to a placeholder by the inspected chat route.

Request flow

A request is authenticated, validated, checked against model runtime status and project budget, then passed to the routing runtime.

Routing removes unavailable or circuit-open providers before applying request and project constraints.

The selected adapter executes the request, while logs, attempts, and usage records are written from the chat handler.

The request path is deliberately ordered. Authentication and request validation happen before runtime readiness and budget checks; only an eligible request reaches provider routing. This ordering helps locate failures without treating every rejection as a model or provider problem.

The verified inbound chat route is POST /api/gateway/v1/chat/completions.

For the initial test, begin with one authenticated chat-completions request, then inspect the returned Ethen metadata before introducing routing overrides.

Supported workloads

The inspected public handler supports chat-completion requests and optional SSE streaming.

The models handler exposes catalog records with parser diagnostics rather than a strict OpenAI models response.

Array-form message content is accepted, but image entries are normalized to a placeholder in the current chat route.

The verified public workload is chat completion, with optional SSE delivery. The models route is useful for catalog and parser diagnostics, but it should not be presented as evidence that every listed model can execute or that all OpenAI endpoints are implemented.

Where to begin

For a new integration, establish the smallest verified path first: create or obtain a project-scoped Gateway key, choose a model whose runtime status is runnable, and send one non-streaming chat-completions request. Confirm the returned request and trace identifiers, selected provider, attempt count, fallback state, and usage fields before adding routing overrides. Streaming, provider-specific order, aliases, timeouts, and BYOK are easier to evaluate after a baseline request succeeds.

The managed surface is labeled Beta and may display setup-required states. That product posture should guide deployment decisions even though the locked documentation manifest carries a GA maturity value.

Start with the quickstart when you need a first successful request.

Read authentication and API-key guidance before distributing credentials.

Use provider routing, logs, and error documentation when moving from a test request to an operated integration.

A first integration should establish one non-streaming request, then add streaming, route controls, and operational review in separate steps. That sequence leaves a clean baseline for comparing provider attempts, fallback behavior, and usage records.

The managed surface is labeled Beta and can be setup-required; neither a catalog row nor a visible route proves that a provider can execute the request.

Keep the first integration deliberately narrow. Confirm that the project has an active Gateway key, read the catalog response to identify the requested model, and send a non-streaming chat request without provider overrides. A successful response should include the selected provider and attempt information alongside the completion. Those fields matter because a returned model response proves only that one eligible route succeeded at that moment; it does not convert catalog presence into a permanent availability promise.

Model Library and Model Intelligence serve different jobs. The Library exposes catalog and status information, while Model Intelligence organizes research-oriented profiles, comparisons, and charts. Neither surface performs the authenticated routing work handled by the Gateway. Applications should therefore use research data to inform a choice, catalog state to understand readiness, and Gateway response metadata to confirm what executed.