Portal And API Gateway¶

Last updated: 2026-06-28

Portal is the hosted product surface for developers who do not want to run router infrastructure. The API gateway sits between customer API keys and managed Cortensor router pools. The target mental model is an OpenAI-style hosted inference API backed by managed Cortensor router pools.

flowchart LR
  Customer["Developer / customer app"] --> Gateway["Cortensor API Gateway"]
  Portal["Portal web app"] --> Gateway
  Gateway --> Keys["Key issuer<br/>local or Unkey"]
  Gateway --> Usage["Usage storage<br/>Supabase"]
  Gateway --> PoolMap["Model alias<br/>router pool mapping"]
  PoolMap --> Router["Managed router pool"]
  Router --> Network["Cortensor network"]

V1 Product Shape¶

Layer	Role
Portal web app	Account, auth, API keys, usage, billing visibility, docs, profile, and playground/product UX.
Auth layer	Clerk or Supabase Auth are viable V1 options.
Durable state	Supabase stores users, organizations, key metadata, usage events, request logs, billing ledger, plans, model access, and router pools.
Key/rate-limit layer	Unkey or local mode handles API key issuing, verification, revocation, and rate-limit enforcement.
Gateway/backend	Product/business logic, entitlement checks, model routing, usage capture, and error/request IDs.
Router pools	Managed Cortensor routers and dedicated-backed sessions provide inference execution.

Portal Routes¶

Route	Purpose
`/portal/usage`	Usage events and summaries.
`/portal/api-keys`	API key create/list/revoke UI.
`/portal/billing`	Billing-plan surface.
`/portal/docs`	Customer quickstart content.
`/portal/profile`	Account/profile settings.

Gateway Endpoints¶

Endpoint	Purpose
`/health`	Gateway health and configured router pool aliases.
`/portal/api-keys`	Management API for key create/list/revoke.
`/portal/usage-summary`	Usage summary for a portal user.
`/v1/models`	Public model list for OpenAI-compatible clients.
`/v1/chat/completions`	OpenAI-compatible chat completions route, including SSE streaming.
`/v1/messages`	Anthropic-compatible messages route, including SSE streaming.
`/v1/completions`	Legacy Cortensor gateway envelope routed to managed router `/api/v3/completions`.

Request Path¶

customer -> gateway -> API key verification -> rate limit -> model/router pool -> router /api/v3/completions -> usage writeback

Customer Examples¶

OpenAI non-streamOpenAI SSEAnthropic SSE

curl https://api.cortensor.app/v1/chat/completions \
  -H "Authorization: Bearer $CORTENSOR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "oss-20b",
    "messages": [{"role": "user", "content": "Summarize Cortensor in one sentence."}],
    "max_tokens": 48
  }'

curl -N https://api.cortensor.app/v1/chat/completions \
  -H "Authorization: Bearer $CORTENSOR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "oss-20b",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a short reply."}],
    "max_tokens": 48
  }'

curl -N https://api.cortensor.app/v1/messages \
  -H "x-api-key: $CORTENSOR_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "oss-20b",
    "max_tokens": 48,
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a short reply."}]
  }'

Product Principles¶

Principle	Meaning
Stable product surface	Customer integrations use Portal-facing models and hosted compatibility routes, not raw router internals.
Replaceable backend	Router pools, session IDs, and managed model mappings can change without breaking customers.
Centralized enforcement	Auth, quotas, rate limits, billing, and observability live in the product/gateway layer.
Decentralized execution	Actual inference still flows through managed Cortensor routers and sessions.
Conservative V1	Early Portal versions prioritize hosted inference simplicity over exposing all raw network controls.

Current hosted compatibility scope:

Text input and text output are the primary supported path.
Tool/function calling is not exposed on the hosted compatibility routes.
The gateway adapts router text streaming into provider-shaped SSE events.
Provider-compatible routes are intended for common chat/message integrations; advanced provider-specific features require explicit support before use.

Configuration¶

Env	Meaning
`PORTAL_ROUTER_POOLS_JSON`	Customer model alias to router pool URL.
`PORTAL_ROUTER_MODEL_SESSIONS_JSON`	Model alias to router session IDs.
`PORTAL_ROUTER_MODEL_AUTH_KEYS_JSON`	Model-level upstream router auth.
`PORTAL_ROUTER_SESSION_AUTH_KEYS_JSON`	Session-specific upstream router auth.
`PORTAL_DEFAULT_MODEL`	Default model alias.
`PORTAL_UNKEY_*`	Hosted key issuing/revocation.
`PORTAL_SUPABASE_*`	Key metadata and usage storage.

See Portal Implementation Notes for the implementation ledger.