API · v1
Docs
The North ML API speaks the OpenAI Chat Completions format. Change the base URL, use your key, ask for north-auto.
Quickstart
Create a key in the console, then call the API. The request below streams; the response arrives as server-sent events.
Authentication
Send your key as a Bearer token: Authorization: Bearer nm_…. Keys belong to your account and can be revoked at any time. Keep them out of browser code. Every response carries an X-Request-Id header; quote it if you contact us.
Models
GET /v1/models lists what the API serves right now, with each model’s context length. No key is needed.
Loading the live model list…
The API serves North ML’s own open-weight models only. Paid features may be added.
Chat completions
POST /v1/chat/completions
| Field | Type | Notes |
|---|---|---|
| model | string | Optional. north-auto, or any id listed at GET /v1/models. |
| messages | array | Up to 6 system, user and assistant messages. The last must be from the user. |
| stream | boolean | Server-sent events in the OpenAI chunk format. |
| stream_options.include_usage | boolean | Adds a final chunk with token usage, cost_usd (dollars) and credits_charged. |
| max_tokens | integer | Caps the answer (16 to 512). north-auto may pick less. |
| search | boolean | North extension. false turns off live web search. |
Streaming
With "stream": true you get standard chat.completion.chunk events ending in data: [DONE]. Some chunks have empty choices and an agent field instead; OpenAI SDKs pass them through and you can ignore them. An error before the first byte is an ordinary JSON error with a status code. An error after streaming starts arrives as a final error chunk.
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"north-auto","choices":[{"index":0,"delta":{"role":"assistant","content":""}}],"north_route":{"routed_to":"ink-1","reason":"lookup","search":true}}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"north-auto","choices":[],"agent":{"type":"status","stage":"searching"}}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"north-auto","choices":[{"index":0,"delta":{"content":"Flare-1 shipped"}}]}
data: [DONE]North extensions
north_routeon the response, or the first chunk: which model north-auto chose, why, whether it searched, and the token budget.agentevents while streaming: stages (routing, searching, reading, writing), the search query, and each source with whether it was kept.sourceson non-streamed responses: the pages it read.- Header
x-north-balance-usd: your balance in dollars after the request. The credit headers remain on non-streamed responses.
Pricing and cost
Everything is priced in US dollars. Each request is charged at the dollar rate of the model that answered, on what it actually used: your prompt (including the search results the model read) and its answer. Every response reports its cost as usage.cost_usd. Before a request runs we hold its worst case (at most 4,096 tokens); when it finishes you’re charged what it used. Refused, failed and timed-out requests cost nothing. Free monthly balance is spent first, then the balance you’ve bought, which never expires.
Loading the live rates…
Research limits
Research in Aspect (chat, research and code) shares one quota, called the Parallax quota in limit messages. It’s separate from your API balance: research never uses balance, and API calls never use the research quota.
| Limit | Value | Notes |
|---|---|---|
| Daily quota | 90,000 tokens | One quota shared by every model. Resets at 00:00 UTC. |
| Weekly allowance | 450,000 tokens | Only used by Burst. Resets Monday 00:00 UTC. |
| Burst | 2x | Off by default. When on, keeps going after the daily quota; each token costs two from the weekly allowance. |
| Context per turn | 6,144 tokens | Older turns of a long thread are dropped first. |
| Requests | 8 per minute | All models run on one shared machine. |
A question uses tokens for your question, the earlier turns it rereads, the pages it reads (up to about 1,900 tokens with web search on), any thinking, and the answer. Before each answer it reserves the most it could use, then charges what it actually used. If a limit is reached mid-answer, it stops at the end of a sentence and says why. Temporary chats count the same as saved ones.
Errors
Every error, on every endpoint, has the same shape and a stable code. Branch on the code, not the message.
{
"error": {
"message": "Too many requests. Try again in 24 seconds.",
"code": "rate_limited",
"type": "rate_limit_error",
"param": null,
"request_id": "req_3f9a1c7e2b4d5a60"
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | bad_messages · invalid_json · invalid_field | The body isn’t valid. param names the field when there is one. |
| 400 | too_heavy · light_limit | The ask is too big for a light request, or won’t fit in 4,096 tokens. |
| 400 | model_not_found | Use north-auto or an id from GET /v1/models. |
| 401 | invalid_api_key | Missing, wrong or revoked key. |
| 402 | insufficient_credits | Not enough balance left for this request’s worst case. |
| 403 | not_approved · unverified · api_access_unavailable | The account can’t use the API yet. |
| 405 · 413 · 415 | method_not_allowed · too_large · unsupported_media_type | Use the documented method; keep bodies under 64 KB; send JSON. |
| 422 | refused · rephrase | The safety check declined the request as written. |
| 429 | rate_limited | Over 10 requests a minute. Wait the number of seconds in Retry-After. |
| 503 | server_busy · upstream_unreachable · safety_unavailable | The model server is busy or unreachable. Retry after Retry-After seconds. Nothing was charged. |
| 502 · 504 | upstream_error · upstream_timeout | The model server didn’t answer in time. Nothing was charged. |
| 500 | server_error | Our side. Quote request_id if you write to us. |
Status
GET /api/status reports whether the model server is reachable and busy. It returns booleans and counts only, never a URL or a key. The badge in the footer reads from it.