Gateway quickstart

This quickstart produces one grounded result: an authenticated chat-completion response from the verified Gateway endpoint. It avoids unverified account-creation labels and focuses on the steps represented in the current route and key-management sources.

Exact workspace and project onboarding controls vary by environment, and the managed Gateway can remain setup-required until platform dependencies are configured.

The goal of this quickstart is not to exercise every Gateway feature. It is to create a reliable baseline that can be repeated after configuration changes. Record the model identifier, key metadata, request body, response identifiers, and final status from the first successful call. When streaming is added, retain the response headers and event sequence as a second baseline. These records make later routing, fallback, cost, and provider experiments easier to interpret because the application already has a known-good request path.

Prerequisites

A successful first request needs a usable project key, an environment in which the managed Gateway is configured, and a model that is not blocked by catalog or provider readiness. The repository does not establish the exact account-creation sequence, so begin from an existing project context. When the product reports setup-required, resolve that platform condition before diagnosing the request body or changing routing options.

Use a server environment that can keep the Gateway key private and send HTTPS requests to the approved deployment.

Before sending a request, confirm four independent conditions. The key must be active and include gateway:invoke. The requested model must not be catalog-only or blocked by an unsupported modality. At least one provider must remain eligible after project restrictions, policy, credential, availability, and circuit-breaker checks.

The exact account and project creation controls are not part of the inspected sources, so this procedure begins with an existing project. A setup-required message means the environment is missing platform or provider configuration; creating another request body will not resolve that state.

You need access to a project in which an owner or admin can create a Gateway key.

The target model must be present in the catalog and report a runnable state rather than catalog-only, missing-key, or unsupported-modality status.

At least one eligible provider must be configured and permitted by project and policy controls.

The procedure assumes an existing project and a user who can create a key. Because exact onboarding controls are not verified, the quickstart begins at the first grounded product state: a project with key management available and at least one runnable model route.

The chat handler requires gateway:invoke, a model identifier, and at least one message. Streaming begins with a role chunk, continues with delta chunks, includes usage in the final chunk, and ends with [DONE].

A successful non-streaming response uses an OpenAI-style chat.completion object with an ethen extension. Usage summaries aggregate requests, input tokens, output tokens, and estimated cost. Estimated cost is not an invoice.

The project must also have a route that can become runnable: catalog recognition alone is not enough.

Create an API key

Create the key from the approved API-keys surface and copy the raw value at once. The service stores a hash plus metadata rather than a recoverable secret. The metadata can include the key name, environment, prefix, suffix, scopes, creation and update times, last-used time, expiry, and revocation state. Keep the raw key in a server-side secret store and do not place it in source control, browser code, URLs, or request metadata.

The supplied implementation allows project owners and admins to create or revoke keys. It does not establish a dedicated rotation button, so rotation should be treated as an overlap procedure: create a replacement, update callers, verify the replacement, then revoke the old key.

Use the approved API-keys surface for the current project; the raw value is revealed once and only its hash plus metadata is stored.

Keep the default gateway:invoke scope when the key will call chat completions; gateway:read alone is not sufficient for the verified handler.

Record the key securely at creation because the raw value cannot be recovered from the metadata listing.

Create a project-scoped key and capture the raw value immediately. The management surface can continue to show identifying metadata, status, scopes, and timestamps, but it cannot reveal the original secret after creation.

A project owner or admin can create a Gateway key when the key-management surface is configured. Authentication errors occur before provider execution, so retrying against another provider cannot repair them.

Send a request

Keep the first response unchanged as the comparison baseline.

Use the relative endpoint POST /api/gateway/v1/chat/completions. The minimum body contains model and messages; the handler also recognizes temperature, max_tokens, max_completion_tokens, stream, metadata, and providerOptions.gateway. Start without optional routing controls so the first result tests the default project route.

A successful non-streaming response uses an OpenAI-style chat.completion object and includes an ethen extension. Record the request ID, trace ID, selected provider, selected model alias, attempt count, fallback state, warnings, and usage. Those fields confirm more than the visible answer text: they show which route executed and whether fallback occurred.

POST to /api/gateway/v1/chat/completions with a Bearer token, a model identifier, and at least one message.

A minimal supported body uses model and messages; temperature and completion-token fields are optional.

A successful non-streaming response uses a chat.completion shape and adds an ethen object with route and attempt context.

Minimal request

curl -sS "${ETHEN_BASE_URL}/api/gateway/v1/chat/completions" \
  -H "Authorization: Bearer ${ETHEN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_RUNNABLE_MODEL_ID",
    "messages": [
      {"role": "user", "content": "Reply with a short confirmation."}
    ]
  }'

The expected result is a JSON chat-completion object. Confirm the ethen metadata and response identifiers before treating the integration as ready.

Keep the first request intentionally small. A model identifier, one message, and the Bearer header are enough to exercise authentication, readiness checks, routing, provider execution, logging, and response serialization without introducing optional settings.

Usage summaries aggregate requests, input tokens, output tokens, and estimated cost; estimated cost is not an invoice.

Stream a response

After the non-streaming request succeeds, set stream to true. The server responds as text/event-stream, emits an opening role chunk, sends zero or more content deltas, includes usage in the final chunk, and ends with [DONE]. Retain the stream, request, and trace response headers with the event sequence.

A provider-stream failure is still a failure even when the handler sends an error chunk and then closes with [DONE]. Client code should inspect the event payload, not treat the sentinel by itself as proof of successful completion. Reconnect and resume guarantees are not defined in the supplied implementation.

Set stream to true to request text/event-stream delivery.

The stream begins with a role chunk, emits delta chunks, includes a final usage-bearing chunk, and ends with [DONE].

Treat an error chunk followed by [DONE] as a failed stream even though the transport closed cleanly.

Streaming should be tested after the non-streaming path succeeds. A client must distinguish content deltas from the final usage-bearing chunk and must treat a provider-stream error as failure even when the server subsequently emits [DONE].

A stream can fail after provider selection, so routing success and complete client delivery are separate outcomes.

The raw key is revealed once; only its hash and metadata remain available afterward.

Review usage

A successful first request should leave three matching views: the HTTP response, the request log, and the usage event. The request and trace identifiers connect them. If any view is absent, keep the test in draft status and investigate configuration or persistence before expanding the integration.

For the baseline request, compare the response usage with the matching usage event instead of judging success from generated text alone. Confirm the request count, input tokens, output tokens, model, provider, route, and trace. A missing or zero estimate should be recorded as unavailable telemetry rather than converted into a statement that the request had no cost.

Repeat the same check after enabling streaming. The final usage-bearing event should agree with the persisted request and usage records when persistence completes. If the stream closes without a normal final usage chunk, keep the partial-delivery status visible and investigate the stream error before using the result as a production baseline.

Use response identifiers to correlate the call with Gateway logs and usage records.

Check selected provider, attempt count, fallback state, token totals, latency, and estimated cost rather than relying only on visible text.

Remember that estimated cost is operational telemetry, not a final invoice.

Usage review confirms that the request produced an accounting event, but it does not prove a final invoice. Compare request count and token totals with the response and trace rather than assuming a zero or missing estimate means no work occurred.

After the request succeeds, compare the response metadata with the usage record for the same trace. Input and output token counts should be interpreted separately, and estimated cost should remain labeled as an estimate. If the trace is absent from the expected usage view, confirm the project and route before assuming the request was not recorded.

Troubleshooting

If the response succeeds but the expected provider or fallback state differs, do not discard the baseline. Keep the request and trace IDs, compare the returned route metadata with project restrictions, and confirm whether aliases, provider order, or policy changed the eligible route.

Resolve the earliest failing layer. missing_api_key, invalid_api_key, revoked_api_key, expired_api_key, and insufficient_scope belong to authentication. setup_required, model_catalog_only, provider_key_missing, and model_not_runnable indicate readiness or provider configuration. budget_exceeded occurs before provider execution. provider_stream_error belongs to partial streaming delivery.

When a provider attempt exists, compare its provider, model, latency, success state, and redacted error with the final route metadata. If no attempt exists, changing provider order or adding a fallback cannot repair the request.

A missing or malformed Bearer token produces an authentication error before model routing.

Catalog-only, missing-key, setup-required, non-runnable, and budget errors identify different remediation paths.

If a provider fails, inspect attempt metadata and logs before retrying, because project policy or credentials may make a repeat request fail the same way.

When the quickstart fails, use the exact error code to choose the next action. Key errors, setup-required states, catalog-only models, missing provider credentials, budget enforcement, and provider failures belong to different layers and should not be troubleshot interchangeably.

Before expanding the integration, keep the first request minimal: one model, one message, no routing overrides, and streaming disabled until the non-streaming path succeeds.

Exact account-creation and project-creation controls are not verified, and setup-required states must be resolved in the current environment before the procedure can complete.

Work through failures in processing order. A missing or malformed Bearer token must be corrected before model or provider diagnostics are useful. After authentication succeeds, verify that the requested model is known, that its runtime status is not catalog-only, and that an eligible provider has the required project configuration. Budget rejection is separate from provider failure and should be investigated through the project’s usage and budget records.

For a streaming test, confirm the non-streaming request first. The stream should begin with an assistant-role event, continue with text deltas, include final usage information, and end with [DONE]. Treat an error event as a failed request even when the connection later closes normally. The quickstart does not define account-creation buttons, workspace roles, or a universal production base URL; those details remain environment-dependent.