# 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)

```http
GET /api/gateway/v1/models
```

```bash
curl -sS https://your-project.ethen.dev/api/gateway/v1/models
```

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

## 1. List providers (public)

```http
GET /api/gateway/v1/providers
```

```bash
curl -sS https://your-project.ethen.dev/api/gateway/v1/providers
```

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

## 2. Store your API key

```bash
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)

```bash
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](/docs/gateway/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

```json
{
  "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

```bash
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](/docs/resources/certification-and-limits).