Model/api/DEVELOPER_API.md

# Frox AI Developer API

An OpenAI-compatible developer API with **API keys, authentication, rate
limiting, and usage tracking**, layered in front of the Morph model server.

```
Developer client  ->  Developer Gateway (:8080)  ->  Morph model server (:8000)
  Bearer frx-...        auth + rate limit + usage        raw /v1 inference
```

## Run

```bash
# 1. Start the model server (raw inference, no auth)
python scripts/serve.py --family classic --model ./ckpt --port 8000

# 2. Start the developer gateway in front of it
export MORPH_UPSTREAM_URL=http://localhost:8000
export MORPH_ADMIN_TOKEN=choose-a-strong-admin-secret
uvicorn api.developer_gateway:app --host 0.0.0.0 --port 8080
```

## Issue an API key (admin)

```bash
curl -X POST http://localhost:8080/dev/keys \
  -H "X-Admin-Token: $MORPH_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "plan": "pro"}'
# -> { "key": "frx-....", "plan": "pro", "rpm_limit": 120, ... }
```

The secret is shown **once**. Store it securely.

## Call the API (developer)

Use it exactly like the OpenAI API — just change the base URL and key:

```bash
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer frx-...." \
  -H "Content-Type: application/json" \
  -d '{"model": "classic", "messages": [{"role":"user","content":"Hi"}], "stream": true}'
```

Works with the official OpenAI SDKs:

```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8080/v1", api_key="frx-....")
resp = client.chat.completions.create(
    model="classic",
    messages=[{"role": "user", "content": "Hello"}],
)
```

## Endpoints

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| POST | `/dev/keys` | admin | Issue a new API key |
| DELETE | `/dev/keys/{key}` | admin | Revoke a key |
| GET | `/dev/usage` | key | This key's usage counters |
| GET | `/v1/models` | key | List available models |
| POST | `/v1/chat/completions` | key | Chat completion (stream or full) |
| GET | `/health` | none | Gateway + upstream health |

## Plans & rate limits

| Plan | Requests / min |
|------|----------------|
| free | 20 |
| pro | 120 |
| scale | 600 |

## Production notes

- Swap the JSON `KeyStore` for a real database (interface is small: `create`,
  `get`, `revoke`, `record_usage`).
- Set `MORPH_ADMIN_TOKEN` (without it, key management is open — dev only).
- Restrict `MORPH_CORS_ORIGINS` to your real client origins.
- Rate limiting is in-memory per process; use Redis for multi-instance.