API

The same assistant, tools and limits as the app, over HTTPS and JSON. Base URL: https://ai.voltranova-energy.com

Keys

Create a key under Settings → API keys in the app. The key (vnk_...) is shown once and stored only as a hash: copy it then. Revoke it there at any time. Send it on every call:

Authorization: Bearer vnk_xxxxxxxxxxxxxxxxxxxxxxxx

Use of the API counts against the same weekly and monthly limits as the app (see limits). Rate limit: 60 requests per minute per key; over that you get HTTP 429 with Retry-After.

POST /v1/chat/completions (OpenAI-compatible)

For integrations that already speak the OpenAI chat format. Same API key, quotas and gateway as /v1/chat. Models: voltranova-lite, voltranova-pro. These calls run in a low-priority lane: they never go ahead of a person using the website, at most two wait at once (otherwise HTTP 429 with Retry-After), and a running answer is never interrupted. stream: true returns text/event-stream chunks and data: [DONE]; the answer is sent when it is complete (keep-alive comments while it is written).

curl https://ai.voltranova-energy.com/v1/chat/completions \
  -H "Authorization: Bearer vnk_..." -H "Content-Type: application/json" \
  -d '{"model":"voltranova-pro","messages":[{"role":"system","content":"Be brief."},{"role":"user","content":"What is the Boltzmann constant?"}]}'

POST /v1/chat

curl https://ai.voltranova-energy.com/v1/chat \
  -H "Authorization: Bearer $VN_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Hur beräknar man verkningsgraden hos en solcell?", "model": "lite", "answer": "auto"}'

Field	Meaning
text	The question, up to 8,000 characters. Swedish or English.
model	lite (default, free model), pro or max (when your plan includes them and they are open).
answer	auto (your documents first, then web or general knowledge, labelled), docs, general or web.
mode	qa (default) or research (OpenAlex and arXiv).
history	Optional: the last turns, [{"q": "...", "a": "..."}], so a follow-up such as "give me their number" keeps its context.
wait_s	How long the call waits for the answer (default 120, max 600). Slower answers return HTTP 202 and a job id.

{"id": "3f2a9c1d7b10", "status": "done", "text": "...", "sources": [{"name": "report.pdf", "page": 3}],
 "model": "VoltraNova Lite", "tier": "free", "usage": {"prompt_tokens": 1180, "completion_tokens": 240, "latency_s": 41.2}, "notices": []}

GET /v1/jobs/{id} returns the same object (or {"status": "queued" | "running"}).

Tools

GET /v1/tools lists them. POST /v1/tools/{name} with {"params": {...}} runs one deterministic energy tool and returns the numbers with their source and unit. POST /v1/tools/drawing ({"params": {"text": "flange 100 mm outer diameter ..."}}) makes a 3D part (counts as a drawing). POST /v1/tools/fea runs a static analysis (counts as an FEA run).

GET /v1/usage

Your used amounts and limits per week and month, with the reset times.

Errors

HTTP	Body
401	{"error": "...", "code": "bad_key"} missing, wrong or revoked key
429	{"code": "rate_limit"} too many requests, or {"code": "quota", "resource": "tokens", "period": "week", "resets_at": 1793000000} a plan limit is reached; premium use is paused until resets_at (Unix time), the free model stays available (lite_available)
400 / 422	Bad parameters, with an explanation in error or detail
502	The model call failed; nothing is counted for a failed call that produced no tokens

Limits per plan

Weekly windows start Monday 00:00 UTC, monthly windows on the 1st at 00:00 UTC.