Developer Documentation

NorthGate AI Gateway

One API endpoint. OpenAI-compatible. 100+ models. Canadian data residency and PIPEDA-aligned audit logging.

01Quickstart

Get from zero to your first API call in under 5 minutes.

Step 1 — Get your API key

Sign up at northgate-ai.polsia.app/auth/signup. Your API key is shown once — store it somewhere safe. Use it in the X-API-Key header on every request.

Your API key is shown only once. If you lose it, regenerate it from your dashboard. The old key is immediately invalidated.

Step 2 — Make your first request

All examples use the X-API-Key header. Replace YOUR_API_KEY with your actual key.

cURL
curl -X POST https://northgate-ai.polsia.app/v1/chat/completions \\ -H "Content-Type: application/json" \\ -H "X-API-Key: YOUR_API_KEY" \\ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Say hello in one sentence."}] }'
Python (requests)
import requests resp = requests.post( "https://northgate-ai.polsia.app/v1/chat/completions", headers={ "Content-Type": "application/json", "X-API-Key": "YOUR_API_KEY" }, json={ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Say hello in one sentence."}] } ) print(resp.json()["choices"][0]["message"]["content"])
JavaScript (fetch)
const resp = await fetch("https://northgate-ai.polsia.app/v1/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", "X-API-Key": "YOUR_API_KEY" }, body: JSON.stringify({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Say hello in one sentence." }] }) }); const data = await resp.json(); console.log(data.choices[0].message.content);

Step 3 — Try different routing strategies

Add ?route=<strategy> to switch how requests are routed to providers:

?route=cheapest
Routes to the lowest-cost model that meets your quality bar. Best for high-volume, cost-sensitive workloads.
?route=fastest
Routes to the lowest-latency provider. Best for real-time user-facing applications.
?route=balanced
Weights cost and latency equally. Good default for general-purpose use.
?route=best_quality
Routes to the best-performing model regardless of cost. Best for high-stakes tasks.
Example — cheapest route
curl -X POST "https://northgate-ai.polsia.app/v1/chat/completions?route=cheapest" \\ -H "Content-Type: application/json" \\ -H "X-API-Key: YOUR_API_KEY" \\ -d '{"model": "gpt-4o-mini", "messages": [{"role":"user","content":"..."}]}'

02API Reference

POST /v1/chat/completions OpenAI-compatible chat completion

Send a chat conversation and receive a model response. Fully OpenAI-compatible — swap your base URL from api.openai.com to northgate-ai.polsia.app and it just works.

Request body

Field Type Required Description
modelrequired string Yes Model ID (e.g. gpt-4o-mini, claude-3-5-sonnet, deepseek-v3). Use ?route= param to let NorthGate choose.
messagesrequired array Yes Array of message objects. Each has role (system/user/assistant) and content (string).
stream boolean No Enable server-sent events streaming. Default: false.
temperature number No Sampling temperature. Range: 0–2. Default: 1.0.
max_tokens integer No Maximum tokens in the response. Default: 16384.
top_p number No Nucleus sampling. Default: 1.
frequency_penalty number No Penalize repeat tokens. Range: -2 to 2. Default: 0.
presence_penalty number No Penalize new topics. Range: -2 to 2. Default: 0.
tools array No Function calling tools. NorthGate passes through to the upstream provider.
response_format object No For structured output ({type:"json_object"}). Requires a system message with "JSON" instruction.

Response

Example response
{ "id": "chatcmpl-3e7f9a2b", "object": "chat.completion", "created": 1718820000, "model": "gpt-4o-mini", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 18, "completion_tokens": 9, "total_tokens": 27 } }

Streaming response

Set "stream": true in your request. Responses come as SSE (text/event-stream) with data: [DONE] to signal end.
POST /v1/embeddings Get text embeddings

Convert text to vector embeddings for RAG, semantic search, and similarity matching.

Field Type Required Description
modelrequired string Yes Embedding model (e.g. text-embedding-3-small, text-embedding-3-large).
inputrequired string | array Yes Text string or array of strings to embed. Max 100 strings per call. Max 8,192 tokens per string.
Example
curl -X POST https://northgate-ai.polsia.app/v1/embeddings \\ -H "Content-Type: application/json" \\ -H "X-API-Key: YOUR_API_KEY" \\ -d '{"model": "text-embedding-3-small", "input": "What is Canadian data sovereignty?"}'
GET /v1/models List available models

Returns a list of all models available through NorthGate AI.

Response
{ "object": "list", "data": [ { "id": "gpt-4o-mini", "object": "model", "created": 1718820000, "owned_by": "openai" }, { "id": "claude-3-5-sonnet-20240620", "object": "model", "created": 1718820000, "owned_by": "anthropic" } ] }
GET /health Health check — no auth required

Returns the gateway health status. Does not require an API key and does not query the database (safe for Neon auto-suspend).

{"status":"healthy","timestamp":"2026-06-19T12:00:00.000Z"}
GET /metrics Prometheus-format metrics — no auth required

Prometheus-compatible metrics endpoint. Exposes request counts, latency histograms, error rates, and token usage broken down by model and provider.

# HELP gateway_requests_total Total requests # TYPE gateway_requests_total counter gateway_requests_total{model="gpt-4o-mini",provider="openai"} 4821 # HELP gateway_latency_ms Request latency in ms # TYPE gateway_latency_ms histogram gateway_latency_ms_bucket{le="100"} 3205 gateway_latency_ms_bucket{le="500"} 4410

03Authentication

API Key Header

Pass your API key on every request using the X-API-Key HTTP header:

X-API-Key: ngt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API keys are SHA-256 fingerprinted server-side. Your full key is never stored — only the fingerprint. Use ?key_format=fingerprint on GET /dashboard to retrieve your masked key display.

Rate Limit Headers

Every response includes rate limit headers so your application can back off gracefully:

Header Description
X-RateLimit-Limit Your plan's request limit for the current period (day or month).
X-RateLimit-Remaining Requests remaining in the current period.
X-RateLimit-Reset Unix timestamp when the limit resets.
Retry-After Seconds to wait before retrying, returned only when the limit is exceeded.

04Routing

Route Strategies

Use the ?route=<strategy> query parameter to control how requests are routed. Each strategy evaluates available providers and picks the best match for the selected criteria.

Strategy Best for
cheapest High-volume batch processing, cost-sensitive pipelines
fastest Real-time user-facing features, low-latency requirements
balanced General-purpose API usage — a good default
best_quality High-stakes tasks where output quality is paramount

Provider List

NorthGate AI currently routes to the following upstream providers:

Provider Models available
OpenAI gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo, text-embedding-3-small, text-embedding-3-large
Anthropic claude-3-5-sonnet-20240620, claude-3-opus-20240229, claude-3-haiku-20240307
Groq llama-3.3-70b-versatile, mixtral-8x7b-32768, gemma2-9b-it (free tier)
DeepSeek deepseek-chat (via BYOK or NorthGate provisioned)

Fallback Behavior

If the primary provider fails or returns an error, NorthGate automatically retries against the next available provider in the fallback chain — with no code changes required from you.

Fallbacks are transparent. The response format stays the same regardless of which provider handled your request.

05Pricing

NorthGate AI is priced per seat, not per token. Upstream token costs are passed through at cost — no markup.

Developer
$0
100 requests / day
Team
$49/mo
10,000 requests / month
Enterprise
Custom
Volume pricing, dedicated support

Upstream token costs (OpenAI, Anthropic, Groq) are billed by those providers directly — NorthGate AI passes the cost through at no markup. Your plan fee covers gateway access, routing intelligence, Canadian data residency, and PIPEDA audit logs.

See the pricing section on the landing page for full feature comparison.