# API Specifications Overview

TruePortAI exposes two families of REST APIs, all served behind **AWS CloudFront** at `https://gateway.trueportai.com`.

---

## API Families

```mermaid
graph TD
    CF["https://gateway.trueportai.com"] --> GW["Gateway & Management API\n/trueportai-services/*"]
    CF --> PB["Platform Backend API\n/platform/api/*"]

    subgraph "Gateway API (/trueportai-services)"
        GP1["/openai/v1/{path} — OpenAI Proxy"]
        GP2["/anthropic/v1/{path} — Anthropic Proxy"]
        GP3["/google/v1beta/{path} — Google Proxy"]
        GP4["/azure/{resource}/{deploy}/{path} — Azure Proxy"]
        GP5["/api/v1/keys — API Key Management"]
        GP6["/api/v1/analytics/logs — Usage Logs"]
        GP7["/api/v1/analytics/stats — Statistics"]
        GP8["/api/v1/analytics/violations — Violations"]
        GP9["/api/v1/policies — Policy Rules"]
    end

    subgraph "Platform API (/platform/api)"
        PP1["/global/auth/* — Auth & JWT"]
        PP2["/global/tenants — Org Management"]
        PP3["/service/info — Tenant Info"]
        PP4["/service/members — Team Management"]
        PP5["/service/invites — Invitations"]
        PP6["/service/catalog/plans — Plan Catalog"]
        PP7["/service/subscriptions — Billing"]
        PP8["/service/configs — Config Management"]
        PP9["/service/storage — Storage Settings"]
        PP10["/admin/* — Platform Admin"]
    end

    GW --> GP1 & GP2 & GP3 & GP4 & GP5 & GP6 & GP7 & GP8 & GP9
    PB --> PP1 & PP2 & PP3 & PP4 & PP5 & PP6 & PP7 & PP8 & PP9 & PP10
```

---

## Authentication Summary

### Platform API Authentication

```mermaid
sequenceDiagram
    Client->>Platform API: POST /platform/api/global/auth/login
    Platform API-->>Client: global_access_token (JWT: {sub})
    Client->>Platform API: POST /platform/api/global/auth/select-tenant
    Platform API-->>Client: scoped_access_token (JWT: {sub, tid, role, env})
    Client->>Platform API: GET /platform/api/service/... (scoped routes)
    Note over Client: Use scoped_access_token for all service routes
```

### Gateway API Authentication

```mermaid
sequenceDiagram
    Client->>Gateway API: POST /trueportai-services/api/v1/keys
    Note over Client: Use scoped_access_token for management
    Gateway API-->>Client: {key: "sk-xxx..."}
    Client->>Gateway API: POST /trueportai-services/openai/v1/chat/completions
    Note over Client: Use sk-xxx for proxy routes
```

---

## Complete Endpoint Reference

### Platform API — Global (Public / Global JWT)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/platform/api/global/auth/register` | None | Register new user |
| `POST` | `/platform/api/global/auth/login` | None | Login → global JWT |
| `POST` | `/platform/api/global/auth/otp/request` | None | Request OTP code |
| `POST` | `/platform/api/global/auth/otp/verify` | None | Verify OTP → JWT |
| `POST` | `/platform/api/global/auth/forgot-password` | None | Send reset email |
| `POST` | `/platform/api/global/auth/reset-password` | Reset token | Set new password |
| `PUT` | `/platform/api/global/auth/password` | Global JWT | Change password |
| `POST` | `/platform/api/global/auth/select-tenant` | Global JWT | Get scoped JWT |
| `POST` | `/platform/api/global/tenants` | Global JWT | Create organization |
| `GET` | `/platform/api/global/tenants` | Global JWT | List my organizations |
| `GET` | `/platform/api/global/tenants/check-availability` | None | Check slug |

### Platform API — Service (Scoped JWT required)

| Method | Path | Min Role | Description |
|--------|------|---------|-------------|
| `GET` | `/platform/api/service/info` | viewer | Get tenant info |
| `POST` | `/platform/api/service/auth/switch-environment` | viewer | Switch env |
| `GET` | `/platform/api/service/members` | viewer | List members |
| `POST` | `/platform/api/service/invites` | admin | Invite user |
| `DELETE` | `/platform/api/service/members/{user_id}` | admin | Remove member |
| `GET` | `/platform/api/service/catalog/plans` | viewer | List plans |
| `POST` | `/platform/api/service/subscriptions` | admin | Activate plan |
| `GET` | `/platform/api/service/configs` | viewer | Get configs |
| `PUT` | `/platform/api/service/configs/{key}` | admin | Update config |
| `GET` | `/platform/api/service/storage` | admin | Get storage config |
| `PUT` | `/platform/api/service/storage` | admin | Update storage config |

### Platform API — Admin (Platform Admin only)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/platform/api/admin/tenants` | List all tenants |
| `GET` | `/platform/api/admin/tenants/{id}` | Get tenant detail |
| `PUT` | `/platform/api/admin/tenants/{id}/status` | Suspend/activate |
| `GET` | `/platform/api/admin/users` | List all users |
| `GET` | `/platform/api/admin/stats` | Platform statistics |
| `GET` | `/platform/api/admin/configs` | Global configs |
| `PUT` | `/platform/api/admin/configs/{key}` | Update global config |

### Gateway API — Proxy Routes (API Key: `x-api-key: sk-...`)

| Method | Path | Description |
|--------|------|-------------|
| `ANY` | `/trueportai-services/openai/v1/{path}` | OpenAI proxy |
| `ANY` | `/trueportai-services/anthropic/v1/{path}` | Anthropic proxy |
| `ANY` | `/trueportai-services/google/v1beta/{path}` | Google Gemini proxy |
| `ANY` | `/trueportai-services/azure/{resource}/{deployment}/{path}` | Azure OpenAI proxy |

### Gateway API — Management (Scoped JWT)

| Method | Path | Min Role | Description |
|--------|------|---------|-------------|
| `POST` | `/trueportai-services/api/v1/keys` | admin | Create API key |
| `GET` | `/trueportai-services/api/v1/keys` | member | List API keys |
| `PATCH` | `/trueportai-services/api/v1/keys/{id}` | admin | Update key (enable/disable) |
| `DELETE` | `/trueportai-services/api/v1/keys/{id}` | admin | Delete API key |
| `GET` | `/trueportai-services/api/v1/analytics/logs` | member | Usage logs |
| `GET` | `/trueportai-services/api/v1/analytics/stats` | member | Aggregated stats |
| `GET` | `/trueportai-services/api/v1/analytics/violations` | member | Violations list |
| `GET` | `/trueportai-services/api/v1/analytics/violations/{id}` | member | Violation detail |
| `GET` | `/trueportai-services/api/v1/policies` | member | List policy rules |
| `POST` | `/trueportai-services/api/v1/policies` | admin | Create policy rule |
| `PUT` | `/trueportai-services/api/v1/policies/{id}` | admin | Update policy rule |
| `DELETE` | `/trueportai-services/api/v1/policies/{id}` | admin | Delete policy rule |

### Health Endpoints (Public)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Platform backend health |
| `GET` | `/trueportai-services/health` | Gateway service health |

---

## Common Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization: Bearer {token}` | Yes (Platform API) | JWT bearer token |
| `x-api-key: sk-{key}` | Yes (Gateway Proxy) | TruePortAI API key |
| `Content-Type: application/json` | Yes (POST/PUT) | Request body format |
| `X-Tenant-Slug: {slug}` | Dev only | Override tenant (dev/localhost) |

---

## Rate Limits

| Endpoint Group | Limit | Window | Response on Exceed |
|---------------|-------|--------|-------------------|
| Gateway Proxy | Configurable per key (default: 60 RPM) | 1 minute | `429` with `Retry-After` |
| Platform Auth `/login` | 10 attempts | 15 minutes | `429` |
| Platform Management | 300 requests | 1 minute | `429` |
| Analytics queries | 60 requests | 1 minute | `429` |

---

## Pagination

All list endpoints use **offset-based pagination**:

```text
# Request
GET /trueportai-services/api/v1/analytics/logs?limit=50&offset=100

# Response envelope
{
  "items": [...],
  "total": 5420,
  "limit": 50,
  "offset": 100
}
```

---

## Versioning

The API follows URL-based versioning:
- Current stable: `v1` (`/api/v1/`)
- Breaking changes increment the version
- Deprecated versions are supported for 6 months after new version release

---

## Detailed API Documentation

For full request/response schemas and examples, see:

- [Gateway API Reference](gateway-api.md) — Proxy routes, API key management, analytics, violations, policies
- [Platform API Reference](platform-api.md) — Auth, organizations, members, billing, configuration