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.

POST/v1/chat/completions
200streamingtext/event-stream

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

FieldTypeNotes
modelstringOptional. north-auto, or any id listed at GET /v1/models.
messagesarrayUp to 6 system, user and assistant messages. The last must be from the user.
streambooleanServer-sent events in the OpenAI chunk format.
stream_options.include_usagebooleanAdds a final chunk with token usage, cost_usd (dollars) and credits_charged.
max_tokensintegerCaps the answer (16 to 512). north-auto may pick less.
searchbooleanNorth 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_route on the response, or the first chunk: which model north-auto chose, why, whether it searched, and the token budget.
  • agent events while streaming: stages (routing, searching, reading, writing), the search query, and each source with whether it was kept.
  • sources on 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.

LimitValueNotes
Daily quota90,000 tokensOne quota shared by every model. Resets at 00:00 UTC.
Weekly allowance450,000 tokensOnly used by Burst. Resets Monday 00:00 UTC.
Burst2xOff by default. When on, keeps going after the daily quota; each token costs two from the weekly allowance.
Context per turn6,144 tokensOlder turns of a long thread are dropped first.
Requests8 per minuteAll 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"
  }
}
StatusCodeMeaning
400bad_messages · invalid_json · invalid_fieldThe body isn’t valid. param names the field when there is one.
400too_heavy · light_limitThe ask is too big for a light request, or won’t fit in 4,096 tokens.
400model_not_foundUse north-auto or an id from GET /v1/models.
401invalid_api_keyMissing, wrong or revoked key.
402insufficient_creditsNot enough balance left for this request’s worst case.
403not_approved · unverified · api_access_unavailableThe account can’t use the API yet.
405 · 413 · 415method_not_allowed · too_large · unsupported_media_typeUse the documented method; keep bodies under 64 KB; send JSON.
422refused · rephraseThe safety check declined the request as written.
429rate_limitedOver 10 requests a minute. Wait the number of seconds in Retry-After.
503server_busy · upstream_unreachable · safety_unavailableThe model server is busy or unreachable. Retry after Retry-After seconds. Nothing was charged.
502 · 504upstream_error · upstream_timeoutThe model server didn’t answer in time. Nothing was charged.
500server_errorOur 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.