# Gateway API Reference

The TruePortAI Gateway is a **transparent reverse proxy**. Your existing AI SDK code requires **only a base URL change** — no other code modifications needed.

**Base URL**: `https://gateway.trueportai.com`

**Authentication**: All gateway routes require an `x-api-key` header with a valid TruePortAI API key (`sk-...`).

---

## Overview

```mermaid
graph LR
    A["Your App\n(OpenAI SDK)"] -->|"base_url = https://gateway.trueportai.com/trueportai-services/openai/v1"| B["TruePortAI Gateway"]
    B --> C["OpenAI API\nhttps://api.openai.com/v1"]
    B --> D["Anthropic API\nhttps://api.anthropic.com/v1"]
    B --> E["Google Gemini\nhttps://generativelanguage.googleapis.com/v1beta"]
    B --> F["Azure OpenAI\nhttps://{resource}.openai.azure.com"]
```

---

## Provider Routes

### OpenAI Compatible

| Method | Path | Description |
|--------|------|-------------|
| `ANY` | `/trueportai-services/openai/v1/{path}` | Proxy to `https://api.openai.com/v1/{path}` |

**Integration example — Python:**
```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-trueportai-key",          # Your TruePortAI key
    base_url="https://gateway.trueportai.com/trueportai-services/openai/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

**Integration example — Node.js:**
```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-trueportai-key',
  baseURL: 'https://gateway.trueportai.com/trueportai-services/openai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
```

---

### Anthropic Compatible

| Method | Path | Description |
|--------|------|-------------|
| `ANY` | `/trueportai-services/anthropic/v1/{path}` | Proxy to `https://api.anthropic.com/v1/{path}` |

**Integration example — Python:**
```python
import anthropic

client = anthropic.Anthropic(
    api_key="sk-your-trueportai-key",
    base_url="https://gateway.trueportai.com/trueportai-services/anthropic/v1"
)

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
```

---

### Google Gemini Compatible

| Method | Path | Description |
|--------|------|-------------|
| `ANY` | `/trueportai-services/google/v1beta/{path}` | Proxy to `https://generativelanguage.googleapis.com/v1beta/{path}` |

---

### Azure OpenAI Compatible

| Method | Path | Description |
|--------|------|-------------|
| `ANY` | `/trueportai-services/azure/{resource}/{deployment}/{path}` | Proxy to `https://{resource}.openai.azure.com/openai/deployments/{deployment}/{path}` |

**Integration example — Python:**
```python
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key="sk-your-trueportai-key",
    azure_endpoint="https://gateway.trueportai.com/trueportai-services/azure/my-resource/gpt-4o-deploy",
    api_version="2024-02-01"
)
```

---

## Management API

Base path: `/trueportai-services/api/v1`

**Authentication**: `Authorization: Bearer {scoped_platform_jwt}`

---

### API Key Management

#### `POST /keys`

Create a new TruePortAI API key.

**Request Body:**
```json
{
  "owner": "production-app",
  "rate_limit_rpm": 120
}
```

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `owner` | string | No | — | Human-readable label |
| `rate_limit_rpm` | integer | No | `60` | Requests per minute limit |

**Response** `201 Created`:
```json
{
  "id": "64b1f2e3a4c5d6e7f8901234",
  "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "owner": "production-app",
  "is_active": true,
  "rate_limit_rpm": 120,
  "created_at": "2024-01-15T10:30:00Z"
}
```

> **Important**: The full `key` value is returned **only once** at creation. Store it securely.

---

#### `GET /keys`

List all API keys for the authenticated tenant.

**Query Parameters:**

| Param | Type | Description |
|-------|------|-------------|
| `limit` | integer | Page size (default: 20, max: 100) |
| `offset` | integer | Pagination offset (default: 0) |

**Response** `200 OK`:
```json
[
  {
    "id": "64b1f2e3a4c5d6e7f8901234",
    "key": "sk-xxxx...yyyy",
    "owner": "production-app",
    "is_active": true,
    "rate_limit_rpm": 120,
    "created_at": "2024-01-15T10:30:00Z"
  }
]
```

---

### Analytics API

#### `GET /analytics/logs`

Retrieve usage logs for the authenticated tenant.

**Query Parameters:**

| Param | Type | Description |
|-------|------|-------------|
| `limit` | integer | Page size (default: 50, max: 500) |
| `offset` | integer | Pagination offset |
| `api_key` | string | Filter by specific API key |
| `provider` | string | Filter by provider: `openai`, `anthropic`, `google`, `azure` |
| `start_date` | datetime | ISO 8601 start range |
| `end_date` | datetime | ISO 8601 end range |

**Response** `200 OK`:
```json
{
  "items": [
    {
      "id": "64b1f2e3a4c5d6e7f8901234",
      "timestamp": "2024-01-15T10:30:00Z",
      "api_key": "sk-xxxx...yyyy",
      "path": "/chat/completions",
      "method": "POST",
      "status_code": 200,
      "latency_ms": 845.2,
      "request_size_bytes": 1024,
      "response_size_bytes": 4096,
      "provider": "openai",
      "model": "gpt-4o",
      "prompt_tokens": 150,
      "completion_tokens": 320,
      "cost_usd": 0.00470
    }
  ],
  "total": 1284,
  "offset": 0,
  "limit": 50
}
```

---

#### `GET /analytics/stats`

Aggregated statistics for the dashboard.

**Query Parameters:**

| Param | Type | Description |
|-------|------|-------------|
| `period` | string | `24h`, `7d`, `30d`, `90d` (default: `7d`) |

**Response** `200 OK`:
```json
{
  "period": "7d",
  "total_requests": 15420,
  "total_cost_usd": 184.32,
  "total_tokens": {
    "prompt": 2450000,
    "completion": 980000,
    "total": 3430000
  },
  "avg_latency_ms": 782.4,
  "error_rate_pct": 0.8,
  "by_provider": {
    "openai": 11200,
    "anthropic": 3100,
    "google": 1120
  },
  "by_model": {
    "gpt-4o": 8400,
    "gpt-4o-mini": 2800,
    "claude-3-5-sonnet-20241022": 3100,
    "gemini-1.5-pro": 1120
  },
  "violations": {
    "total": 23,
    "by_type": {
      "pii": 14,
      "injection": 6,
      "bias": 2,
      "exfiltration": 1
    },
    "critical": 5,
    "high": 11
  }
}
```

---

### Violations API

#### `GET /analytics/violations`

Retrieve detected violations with filtering.

**Query Parameters:**

| Param | Type | Description |
|-------|------|-------------|
| `severity` | string | `critical`, `high`, `medium`, `low` |
| `type` | string | `pii`, `bias`, `injection`, `exfiltration` |
| `start_date` | datetime | ISO 8601 range start |
| `end_date` | datetime | ISO 8601 range end |
| `limit` | integer | Default: 20 |
| `offset` | integer | Default: 0 |

**Response** `200 OK`:
```json
{
  "items": [
    {
      "id": "VIO-001",
      "usage_log_id": "64b1f2e3a4c5d6e7f8901234",
      "type": "pii",
      "severity": "critical",
      "direction": "request",
      "description": "SSN detected in user prompt",
      "auto_blocked": false,
      "detected_at": "2024-01-15T10:30:00Z",
      "model_version": "pii-ner-roberta-v2.1"
    }
  ],
  "total": 23
}
```

---

#### `GET /analytics/violations/{violation_id}`

Get full details of a specific violation including the redacted payload.

**Response** `200 OK`:
```json
{
  "id": "VIO-001",
  "usage_log_id": "64b1f2e3a4c5d6e7f8901234",
  "type": "pii",
  "severity": "critical",
  "direction": "request",
  "description": "SSN detected in user prompt",
  "redacted_payload": {
    "original_prompt_preview": "My SSN is [REDACTED] and I need...",
    "entities_found": [
      { "type": "SSN", "confidence": 0.97 }
    ]
  },
  "auto_blocked": false,
  "detected_at": "2024-01-15T10:30:00Z",
  "model_version": "pii-ner-roberta-v2.1"
}
```

---

### Policy Rules API

#### `GET /policies`

List all governance policy rules for the tenant.

**Response** `200 OK`:
```json
[
  {
    "id": "pol-001",
    "name": "Block credit card numbers",
    "action": "block",
    "trigger_type": "regex",
    "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\\b",
    "is_active": true,
    "priority": 1
  }
]
```

---

#### `POST /policies`

Create a new policy rule.

**Request Body:**
```json
{
  "name": "Redact phone numbers",
  "action": "redact",
  "trigger_type": "regex",
  "pattern": "\\b\\d{3}[-.]?\\d{3}[-.]?\\d{4}\\b",
  "is_active": true,
  "priority": 2
}
```

| `action` | Behavior |
|----------|----------|
| `block` | Request stopped; 403 returned to client |
| `redact` | Matching tokens replaced with `[REDACTED]` |
| `alert` | Violation logged; notification sent |
| `log` | Silent audit only |

---

## Health Check

### `GET /health`

**Response** `200 OK`:
```json
{
  "status": "healthy",
  "version": "v1.0.0",
  "services": {
    "mongodb": "connected",
    "redis": "connected"
  }
}
```

---

## Error Reference

| Status | Code | Description |
|--------|------|-------------|
| `401` | `UNAUTHORIZED` | Missing or invalid `x-api-key` |
| `403` | `FORBIDDEN` | Key exists but `is_active = false` |
| `429` | `RATE_LIMITED` | Requests per minute exceeded |
| `503` | `CIRCUIT_OPEN` | Downstream provider temporarily unavailable |
| `502` | `UPSTREAM_ERROR` | Provider returned an error |
| `400` | `BAD_REQUEST` | Malformed request body |

**Error response shape:**
```json
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "retry_after": 47
}
```