The Nova REST API.

Base URL

https://api.novaaiops.com/v1

All endpoints are under the /v1 prefix. Versioning is date-pinned in the API-Version request header for breaking-change isolation; the URL path version increments only on full v2 cuts.

Authentication

Authenticate every request with a bearer token. Tokens are issued from the admin UI under Settings → API Tokens, scoped per role (Read-Only, Operator, Admin), and rotatable without downtime.

curl https://api.novaaiops.com/v1/incidents \
  # bearer token, scoped to your tenant
  -H "Authorization: Bearer $NOVA_TOKEN" \
  -H "API-Version: 2026-04-01"

Tokens never expire on their own; rotate them on a schedule that matches your security policy. Compromised tokens revoke instantly via the same Settings UI.

Incidents

The incident lifecycle endpoints. Cover the same surface the on-call UI uses: create, ack, resolve, timeline, autogen postmortems, and inline comments.

Alerts

Read alert state, manage silences, and define alert rules. Silencing returns a deterministic ID so you can revoke it programmatically from the same client.

Services and SLOs

The service catalog and SLO posture. /services/{name}/dependencies returns the resolved upstream/downstream graph used by the topology view.

Runbooks and agents

Runbooks define safe automated remediations; agents are the policy-bound executors. Every /runbooks/{id}/run writes to the agent audit ledger so an external system can replay or review the action.

On-call and schedules

Read who is on call right now, manage schedules, apply overrides, and define escalation policies. Same data model the on-call UI and Slack/Teams bots consume.

Synthetic checks

Create black-box probes that hit a URL or TCP port from one or more regions on a schedule. Results stream into the same alert pipeline as agent telemetry, so a failed probe pages on-call.

Audit logs

Every privileged action lands in the audit log: agent executions, alert silences, user role changes, runbook approvals. Each entry includes actor, target, before/after, and a request ID that ties back to the originating API call.

Webhooks

Subscribe to events for incidents, alerts, agent actions, and audit. Each delivery is signed with HMAC-SHA256; rotate the secret without dropping in-flight deliveries via the rotate endpoint.

Users, tokens, and SCIM

User management and API token rotation. SCIM 2.0 is exposed at /scim/v2 for automated provisioning from Okta, Azure AD, or any SCIM-capable IdP.

Dashboards and NovaQL

NovaQL is Nova's metric query language. Run ad-hoc queries against the same TSDB the UI uses, and persist results as panels inside dashboards.

Integrations

Connect, test, and sync provider integrations programmatically. /integrations/{provider}/connect returns an OAuth or device-flow URL the user has to complete in a browser; everything else is callable headless.

Quick example, Python

import os, requests

resp = requests.get(
    "https://api.novaaiops.com/v1/incidents",
    params={"status": "open"},
    headers={
        "Authorization": f"Bearer {os.environ['NOVA_TOKEN']}",
        "API-Version": "2026-04-01",
    },
)
resp.raise_for_status()
for inc in resp.json()["data"]:
    print(inc["id"], inc["severity"], inc["title"])

Quick example, Node

const res = await fetch("https://api.novaaiops.com/v1/incidents?status=open", {
  headers: {
    "Authorization": `Bearer ${process.env.NOVA_TOKEN}`,
    "API-Version": "2026-04-01",
  },
});
const { data } = await res.json();
data.forEach(inc => console.log(inc.id, inc.severity, inc.title));

Rate limits

Defaults: 100 requests/minute per token, 10K requests/day per tenant. Bursts above the per-minute cap return 429 Too Many Requests with a Retry-After header. Enterprise plans raise both limits; ask sales if you need more.

Errors and pagination

Every non-2xx response uses the same envelope so clients can switch on error.code without inspecting the HTTP status. request_id is the right thing to quote when you email support.

{
  "error": {
    "code": "incident_not_found",
    "message": "No incident with id=inc_12abf3 in tenant=acme-prod.",
    "request_id": "req_01HXY8N9V2W4M2A0Q9P1B2C3D4"
  }
}

Status codes you'll see: 400 validation, 401 bad token, 403 token lacks scope, 404 resource missing, 409 state conflict (e.g. acking a resolved incident), 422 semantic conflict, 429 rate limit, 500 on our side.

List endpoints are cursor-paginated. Pass ?limit=N (max 200, default 50) and ?cursor=X (the value returned in next_cursor on the previous page). When next_cursor is omitted you've reached the end.

{
  "data": [ /* ... up to N items ... */ ],
  "next_cursor": "eyJpZCI6Imluc18xMjNhYmYzIn0"
}

POST endpoints accept an optional Idempotency-Key header. If you replay the same key within 24 hours, Nova returns the original response instead of creating a duplicate. Use it for any write that you might retry on a network blip.

OpenAPI spec

The full spec lives at api.novaaiops.com/v1/openapi.json. Drop it into Swagger UI, Postman, Insomnia, or any OpenAPI client to generate types and SDKs.

Talk to a human

If you're integrating against the API and run into anything weird, email developers@novaaiops.com. Same-day reply during business hours, faster on Slack if you're an enterprise customer.