Developers
Novix developer resources
The Novix task API and its OpenAPI spec, authentication and webhooks, the Novix command line, and the Novix MCP server.
Novix is built to be reached from wherever you already work, so most of its surface is connectors rather than an API. Three things are for calling directly: a task API, a command line, and an MCP server. All three do the same one thing, which is to hand Novix a problem and read back the diagnosis and the pull request.
The Novix task API
Two routes. They are what the command line and the MCP server are written against, and the implementation is backend/app/routers/tasks.py.
| Detail | Value |
|---|---|
| Base URL | https://app.getnovix.ai/api/public |
| Create a task | POST {base}/tasks |
| Read a task | GET {base}/tasks/{id} |
| Authentication | Authorization: Bearer {token}, or X-Novix-Token: {token} |
| Runs as | The workspace member bound to that integration. Required to create a task, not to read one. |
This is a live, reachable REST API, not a description of one. Confirm it yourself before reading a line of client code, with no token and no account:
curl https://app.getnovix.ai/api/health
{"status": "ok", ...}
curl -i -X POST https://app.getnovix.ai/api/public/tasks -d '{"prompt": "x"}'
HTTP/2 401
api-version: v1
{"detail": "Unknown or missing API token", "error": "unauthenticated"}The second call is refused because it carries no token, and that refusal is itself the proof: a real server routed the request, checked a real credential, and answered with the documented shape rather than a 404. The machine-readable description of the whole surface is an OpenAPI 3.1 document at /openapi.json. Point a generator at it and you have a client:
curl https://getnovix.ai/openapi.json
The path says public because it needs no browser session, never because it needs no credential. A token resolves to exactly one workspace, and that is the only workspace the request can touch.
Creating a task takes a prompt, and optionally a source (which doubles as the dedupe key) and a callback URL:
curl -X POST https://app.getnovix.ai/api/public/tasks \
-H "Authorization: Bearer $NOVIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt": "checkout 500s when a promo code is applied twice"}'
{"id": "<task id>", "status": "queued"}The task id is a Novix task id: one task is one run, so there is no second identifier to keep in sync. Poll it with GET {base}/tasks/{id}, which is free and unmetered, or pass callbackUrl on the create and Novix posts the finished task to you instead — a webhook you name per request rather than one you register in advance.
The Novix command line
Published on npm as @novix-ai/cli. Node 18 or newer, and nothing to install:
npx -y @novix-ai/cli login npx -y @novix-ai/cli diagnose "checkout 500s when a promo code is applied twice"
It waits for the run and prints the verdict, the confidence, the root cause, the files involved and the pull request link. The commands are diagnose, status, login, whoami, token, logout and version. In CI, set NOVIX_API_TOKEN instead of logging in; there is deliberately no --token flag, because a secret on the command line lands in your shell history.
The Novix MCP server
Published on npm as @novix-ai/mcp-server. It hands Novix to Claude Code, Claude Desktop, Cursor or any other MCP client over stdio, so an agent that hits a bug it does not want to chase can pass it to Novix and keep going. In Claude Code that is one command:
claude mcp add --env NOVIX_API_TOKEN=<your token> --transport stdio novix \ -- npx -y @novix-ai/mcp-server
| Tool | What it does |
|---|---|
| novix_run_task | Hands a problem to Novix. Spends real money: one accepted call starts a full run. Returns a task id straight away. |
| novix_get_status | Polls one task. Free and unmetered. Once the run has succeeded it returns the whole diagnosis: verdict, confidence, summary, root cause, the files involved, the pull request URL and the size of the diff. |
Both tools answer twice, as text and as structured content matching the output schema each one declares, so a client that understands structured output reads the task fields under their own names. That is the whole surface, because that is the whole API. The transport is stdio: the client launches the server itself, so there is no Novix endpoint to point an MCP client at and no second credential to manage.
Authentication: browser sign-in
Run novix login. The terminal prints a short code and opens the signed-in dashboard. Approving that matching code gives the terminal an ordinary integration token bound to you. There is no token to hunt through a webhook URL and no separate developer account.
- Run novix login in the terminal.
- Sign in to the dashboard page it opens, if you are not already signed in.
- Confirm the short code matches, then choose Approve sign-in. The terminal stores the credential and confirms the workspace and member it runs as.
The token is stored at ~/.config/novix/config.json when you use novix login, written 0600 inside a 0700 directory. It is never logged; novix token prints it only when you explicitly need to move it into a CI secret store.
Rate limits and backoff
Every limited response says how much of your allowance is left, so a client can slow itself down instead of finding the ceiling by hitting it. That includes a refusal: an unauthenticated call, an unbound token, an unknown task, all carry these headers, not only a 200 or a 201. Both generations of the IETF header go out, so read whichever your HTTP library already understands.
| Header | What it says |
|---|---|
| RateLimit-Limit | How many requests this policy allows in its window. |
| RateLimit-Remaining | How many are left, counting the one you just made. |
| RateLimit-Reset | Seconds until a slot frees up. It is a sliding window, so this is when the oldest request ages out rather than the top of a fixed minute. |
| RateLimit-Policy and RateLimit | The same two facts as structured fields: `"tasks-create";q=30;w=60` and `"tasks-create";r=29;t=47`. The name is the policy only, never anything that identifies you. |
| Retry-After | On a 429 only, in seconds, and never zero. Waiting exactly this long is always enough. |
The ceilings today are 30 creates a minute and 240 polls a minute per integration, and 60 requests a minute from one IP address, counted before the token is read, which is the one a single machine meets first. Creating is far tighter than polling because every accepted create starts a paid run and every poll costs nothing.
Versioning and deprecation
This API is v1, and every response carries an API-Version header naming it, so you can confirm the version without parsing behaviour:
curl -i https://app.getnovix.ai/api/health | grep -i api-version api-version: v1
Both task routes also answer at a /api/public/v1/tasks alias, for a caller or a scanner that specifically checks a URL for a version segment. It is the identical route, not a second one: there has only ever been one version, so the alias and the base path above answer exactly alike, and the base path is what stays canonical in this document, the CLI and the MCP server.
- A breaking change ships at a new path. The routes on this page keep answering; they are not altered underneath a client that already works.
- Adding is not breaking. A new optional field on a request, or a new field on a response, can arrive at any time. Parse what you need and ignore the rest.
- A retirement is announced in the response itself. A route being retired carries `Deprecation` and `Sunset` headers (RFC 9745 and RFC 8594) for at least 90 days before it stops answering, so a client learns from a request it already makes rather than from an outage.
- Nothing is deprecated today. No route carries either header, which is why you will not see one.
Machine-readable files
Everything an agent needs to read this site without rendering it. All of them are on the marketing origin, getnovix.ai.
| File | What it is |
|---|---|
| /openapi.json | The OpenAPI 3.1 description of this API: the two task routes and the health endpoint, with their schemas and their refusals. |
| /llms.txt | A plain-text map of the site: what every public page is, in one file. |
| /sitemap.xml | Every indexable page. |
| /robots.txt | What may be crawled. The dashboard and the auth funnels are excluded. |
| /.well-known/security.txt | RFC 9116 security contact, also served at /security.txt. Both are canonical. |
| Accept: text/markdown | Most public pages answer in Markdown when you ask for it, on the same URL. Every one of them also has a .md sibling, so /pricing.md returns Markdown with no header at all. |
curl -H "Accept: text/markdown" https://getnovix.ai/pricing curl https://getnovix.ai/pricing.md
Status, honestly
The task API is live and in production. Both npm packages are 0.x, and they are early: each is covered by its own test suite driving the real built artifact against a stub of the task API, and neither has had a long life against production. Treat your first real call as the real test, and tell us when something is wrong at support@getnovix.ai.
There is no per-person API token in Novix and none of this adds one. The only per-person credential is the browser session cookie, and it is never usable from a script.