Developers
Novix developer resources
The Novix task API, the Novix command line, the Novix MCP server, and every machine-readable file this site publishes.
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. |
The machine-readable description of all of it is an OpenAPI 3.1 document at /openapi.json, which is the whole public surface and nothing else. 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 let Novix post the finished task to you instead.
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, 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.
Where the token comes from
The credential is the integration webhook token Novix already issues to every caller that has no browser session. There is no separate developer account and no second auth scheme, which is why this one step needs the dashboard.
- Open the integrations page in the Novix dashboard, at app.getnovix.ai/app/integrations.
- Pick a connected integration and open its settings.
- Copy the
token=value out of the webhook URL it shows, and choose the member under "Tasks run as" so the token names somebody.
The token is stored at ~/.config/novix/config.json when you use novix login, written 0600 inside a 0700 directory, and it is never printed or logged.
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. 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. 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. It is not versioned in the URL path, because there has only ever been one version, and a /v1/ prefix with no /v2/ beside it describes nothing. What you can rely on is what happens next.
- 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.