Gateway quickstart

These examples are the canonical documented API examples for public beta. They are executed by the SOL-47 documentation gate against the current route handlers.

0. List models (public)

GET /api/gateway/v1/models

Expected: HTTP 200 JSON catalog. No API key required for discovery metadata.

1. List providers (public)

GET /api/gateway/v1/providers

Expected: HTTP 200 JSON. Responses must not include raw provider secrets.

2. Store your API key

export ETHEN_GATEWAY_KEY="***"

Create keys in the Gateway API Keys UI for your project. Keys are stored hashed.

3. Chat completion (API key required)

curl -X POST https://your-project.ethen.dev/api/gateway/v1/chat/completions \
  -H "Authorization: Bearer $ETHEN_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "What is an AI Gateway?"}
    ]
  }'

Request shape (schema):

• model (string, required) — prefer a model with a current price and certification path such as openai/gpt-4o-mini; or request an ethen/* smart alias (see Smart routing) and let the Gateway resolve the best provider/model for the request
• messages (array of { role, content }, required)
• stream (boolean, optional)

Without a key, the same request must return JSON 401/403 (fail closed). With a valid project-scoped key and configured upstream credentials, the response is an OpenAI-compatible chat.completion object plus an ethen metadata namespace.

Representative success shape

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 42,
    "total_tokens": 56
  },
  "ethen": {
    "request_id": "gwrun_example",
    "trace_id": "gwtrace_example",
    "provider": "openai"
  }
}

4. Streaming

curl -X POST https://your-project.ethen.dev/api/gateway/v1/chat/completions \
  -H "Authorization: Bearer $ETHEN_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count to five."}
    ]
  }'

Streaming uses SSE (chat.completion.chunk objects). Unauthenticated streaming requests also fail closed.

Limits and honesty

• Live upstream execution requires configured provider credentials and may incur provider cost — use a bounded test key.
• Payment collection is implemented in code but is not live-certified or production-ready on Ethen for this release; provider bills remain external until live certification.
• See Certification status and known limits.