Nolvin API documentation

Start here#

Quickstart — a key, one sentence, and your first graph queries in five requests.
Authentication — API keys, scopes, roles, share tokens.
Concepts — projects, domains, the gate, pages and runs, autopilot, provenance.
Querying the graph — entities, neighborhoods, search, timeline, map, export.
Webhooks and events — signed webhooks, polling and server-sent events.
API reference — every endpoint, also as OpenAPI 3.1.

Base URL#

All endpoints live under https://api.nolvin.com (the same API also answers on https://nolvin.com). Versioned endpoints start with /v1. HTTPS only: plain HTTP is redirected.

curl https://api.nolvin.com/api
{"name":"nolvin","description":"Agentic knowledge graph backend","docs":"https://nolvin.com/docs/"}

The API is meant to be called from servers, scripts and agents. Browsers on other sites cannot call it directly (CORS is limited to the Nolvin console) — proxy through your backend, or publish a read-only share link.

Conventions#

Format: Request and response bodies are JSON (Content-Type: application/json). The map endpoint returns GeoJSON; the event streams return text/event-stream.
IDs: UUIDs. Keys are prefixed: API keys nlv_, share tokens shr_, webhook secrets whsec_.
Timestamps: UTC, formatted YYYY-MM-DD HH:MM:SS. Event dates (starts_at, ends_at) are ISO 8601 as stated by the source.
Pagination: Lists that can be long take limit and offset and return next_offset (null on the last page). Event feeds use a since cursor.
Errors: Non-2xx responses carry {"error": "message"}. Server errors add a request_id to quote when you report them.

Status codes#

Code	Meaning
`200` / `201`	OK / created.
`202`	Accepted: work was queued (autopilot, discovery, frontier planning).
`400`	Invalid input; the message says what.
`401`	Missing, unknown or revoked key.
`403`	Authenticated, but not allowed: a read-only key on a write endpoint, an owner-only action, an archived project.
`404`	Not found — also returned for domains outside your project.
`409`	Conflict: a job of that kind is already running, or a rename collides.
`500`	Server error, with `request_id`. Also returned today for a missing or malformed JSON body on most write endpoints — send valid JSON.
`503`	`/healthz` only: the service is degraded.

For AI agents#

A machine-readable description of every endpoint is at /openapi.json, and a plain-text site summary for language models at /llms.txt. Graph data is designed to be quoted: every entity comes with the pages and verbatim snippets it was extracted from.