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

---

Provider Routes

OpenAI Compatible

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

Integration example — 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:

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:

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:

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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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:

{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "retry_after": 47
}