API Specifications Overview

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

---

API Families

---

Authentication Summary

Platform API Authentication

Gateway API Authentication

---

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:

# 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 — Proxy routes, API key management, analytics, violations, policies

• Platform API Reference — Auth, organizations, members, billing, configuration