API reference

List API keys — All keys of the project, newest first, including revoked ones. #

200 { keys: [{ id, name, scope, created_at, last_used_at, revoked_at }] }

Create an API key #

201 { id, key, scope } — key is nlv_… and is shown only once

Rotate an API key — Issues a new secret for the key; the old one stops working immediately. #

200 { id, key }

errors 404 key not found

Revoke an API key #

200 { ok: true }

Get the current project #

200 { id, name, role, scope }

Rename the project #

200 { ok: true }

errors 400 name required

Delete the project — Permanently deletes every domain, graph, key, invite and membership of the project. #

200 { deleted, domains, users }

errors 400 pass ?confirm=<project name> to delete

List members #

200 { members: [{ id, email, name, role, created_at }] }

Change a member's role #

200 { ok: true }

Remove a member #

200 { ok: true }

errors 400 cannot remove the last owner

Create an invite #

201 { token, role, accept_path }

List invites #

200 { invites: [{ id, role, created_at, accepted_by, accepted_at }] }

Create a domain — Creates an empty domain. To build one from a sentence instead, use autopilot. #

201 { id, name, ontology }

errors 400 name is required

List domains #

200 { domains: [{ id, name, description, ontology, max_depth, max_pages, max_spend_usd, archived, crawl_state, created_at, entity_count, page_count }] }

Get a domain #

200 { id, name, description, ontology, attributes, max_depth, max_pages, max_spend_usd, archived, crawl_state, active_run, published_spec_version, created_at }

errors 404 domain not found

Update a domain — Adding a custom attribute with a new key sends the domain's extracted pages back for a full read on their next re-scrape. #

200 { ok: true }

errors 400 cannot remove types with existing entities: … · 400 invalid attributes: … · 400 nothing to update

Archive a domain — Stops crawling, re-scrapes and spend. Data is kept. #

200 { ok: true }

Unarchive a domain #

200 { ok: true }

Delete a domain — Permanently deletes the domain and its whole graph. #

200 { deleted }

errors 400 pass ?confirm=<domain name> to delete

Graph scorecard — Deterministic 0–100 quality score with components (coverage, precision, connectivity, corroboration, facets, diversity) and the underlying metrics. #

200 { scorecard: { score, components, metrics } }

Start an autopilot domain #

202 { id, stage: "brief" }

errors 400 prompt: describe the domain in one sentence · 400 prompt too long (max 500 chars)

Get autopilot state #

200 { autopilot: { domain_id, prompt, stage, cycle, max_cycles, brief, last_report, history, error, assessed_at, created_at, updated_at } | null }

Retry a failed stage #

200 { ok: true }

errors 409 autopilot is not in a failed state

Add a source — Registers the URL and queues it immediately. #

201 { url, queued }

errors 400 valid http(s) url required

Add sources in bulk #

201 { queued }

Add sources from a sitemap #

201 { sitemap, discovered, queued }

List sources #

200 { sources: [{ id, url, created_at, host, pages_seen, pages_extracted }] }

Remove a source — Removes the source only; its pages and entities stay. #

200 { ok: true }

errors 404 source not found

Crawl one source #

200 { queued }

Crawl all sources — Queues every source not yet crawled. #

200 { queued }

Re-scrape the domain now — Queues every extracted page. Unchanged pages cost nothing; changed pages are read as a diff. #

200 { queued }

Discover sources — Runs an agentic web search for candidate sources. Results are suggestions: review them and add the ones you want. #

202 { queued: true }

errors 409 a discovery is already running for this domain

List discovery runs #

200 { discoveries: [{ id, status, started_at, finished_at, result, sources: [{ url, reason, kinds }], summary, queries_tried }] } — last 5

Plan the frontier — Ranks unexplored links, queues the best, and runs gap searches. Also runs weekly on its own. #

202 { queued: true }

errors 409 a frontier plan is already running for this domain

List frontier plans #

200 { plans: [{ id, status, started_at, finished_at, result, selected, searches, notes, enqueued, frontier_added }] } — last 5

Frontier counts #

200 { frontier: [{ status, n }] } — status: candidate | planned | crawled | rejected

List pages #

200 { pages: [{ id, url, depth, status, last_mode, error, source_host, run_id, fetched_at }], next_offset }

List crawl runs #

200 { runs: [{ id, status, started_at, finished_at, pages_total, pages_done, pages_unchanged, pages_deterministic, pages_agentic, pages_irrelevant, pages_skipped, pages_failed, entities_added, tokens_input, tokens_output, spend_usd }] } — last 20

Pause crawling #

200 { crawl_state: "paused" }

Resume crawling #

200 { crawl_state: "running", requeued }

Cancel the active run #

200 { cancelled: true, cancelled_pages }

errors 400 no active run

List recipes — Legacy deterministic extractors and their health. #

200 { recipes: [{ id, url, version, status, consecutive_failures, last_run_at, last_error, created_at }] }

Invalidate a recipe #

200 { ok: true }

errors 404 recipe not found

List failed pages #

200 { failed: [{ id, url, depth, error, fetched_at, source_host }] } — last 200

Requeue failed pages #

200 { requeued }

errors 400 pass page_ids or all=true

List dead letters — Pages that failed extraction three times. #

200 { dead_letters: [{ id, url, depth, error, status, created_at }] }

Requeue a dead letter #

200 { ok: true }

errors 404 not found

Discard a dead letter #

200 { ok: true }

Usage and spend #

200 { days: [{ day, pages_unchanged, pages_deterministic, pages_agentic, pages_failed, tokens_input, tokens_output, spend_usd }], totals }

List gate versions #

200 { specs: [{ id, version, status, instructions, include_patterns, exclude_patterns, allowed_hosts, language, created_at, published_at }] }

Create a draft gate #

201 { id, version, status: "draft" }

Publish a gate version #

200 { ok: true, version }

errors 404 spec not found

Test a gate on one URL — Fetch, gate and extract one page without writing to the graph. Costs one extraction. #

200 { url, gate_rejection, relevant, confidence, page_class, entities, relationships, next_urls, model, cost_usd, markdown, tokens }

List entities #

200 { entities: [{ id, type, name, description, aliases, created_at, updated_at }], next_offset }

Get an entity — The entity with its facet, custom attributes, relationships and up to 50 provenance rows. #

200 { entity, facet, attributes, relationships: [{ relation, direction, entity_id, name, type }], provenance: [{ snippet, url, created_at }] }

errors 404 not found

Traverse the neighborhood #

200 { root, nodes: [{ id, name, type }], edges: [{ source, relation, target }] }

List relationships #

200 { relationships: [{ id, relation, source_entity_id, target_entity_id, source_name, source_type, target_name, target_type }] } — up to 500

Search entities — Keyword and semantic search merged, best first. #

200 { results: [{ id, type, name, description, match, score }], semantic_enabled }

errors 400 q is required

Timeline — Events with their participants, ordered by start. With entity_id, the events connected to any entity. #

200 { timeline: [{ id, name, description, starts_at, ends_at, participants }] } or { granularity, buckets: [{ bucket, n }] }

Map (GeoJSON) — Located entities as a GeoJSON FeatureCollection, each with its connected entities. With entity_id, one entity's footprint. #

200 GeoJSON FeatureCollection — properties: { entity_id, name, description, address, connected }

Graph statistics #

200 { totals: { entities, relationships, facts, pages }, entities_by_type, top_relations, pages_by_status, pages_by_mode, recipes_by_status }

Export the graph #

200 { domain, entities, relationships, facets: { locations, events, persons, objects, attributes } } or GraphML

Rename an entity — The old name is kept as an alias. #

200 { ok: true, name }

errors 409 an entity of this type with that name exists — merge instead

Merge into another entity — This entity's edges, provenance and names move to the survivor. #

200 { ok: true, survivor, aliases }

Replace an entity's facet — Replaces the whole facet; omitted fields become null. Location: lat, lng, address. Event: starts_at, ends_at. Person: aliases, role. Object: category, identifier. #

200 { ok: true }

Delete an entity #

200 { ok: true }

Delete a relationship #

200 { ok: true }

Curation audit log #

200 { audit: [{ id, user_id, action, subject_id, details, created_at }] } — last 100

Create a share link #

201 { id, token, views, public_base } — token is shr_… and is shown only once

List share links #

200 { shares: [{ id, views, created_at, revoked_at }] }

Revoke a share link #

200 { ok: true }

Shared domain metadata #

200 { name, description, views }

errors 404 invalid share token

Shared entities — Needs the graph or search view. #

200 { entities: [{ id, type, name, description }] }

errors 403 view not shared

Shared timeline — Needs the timeline view. #

200 { timeline: [{ id, name, description, starts_at, ends_at }] }

errors 403 view not shared

Shared map — Needs the map view. #

200 GeoJSON FeatureCollection

errors 403 view not shared

List webhooks #

200 { webhooks: [{ id, url, events, active, created_at }] }

Create a webhook #

201 { id, secret, events } — secret is whsec_… and is shown only once

Rotate a webhook secret #

200 { secret }

errors 404 webhook not found

Delete a webhook #

200 { ok: true }

Send a test delivery — Dispatches a test crawl.finished to the domain's subscribed webhooks. #

200 { ok: true, note }

List deliveries #

200 { deliveries: [{ id, event_type, payload, status, attempts, last_error, created_at, delivered_at }] } — last 50

Poll domain events #

200 { events: [{ id, type, payload, created_at }], cursor }

Stream domain events (SSE) — Events: run.update, page.update, crawl.finished, budget.hit. Resumes from Last-Event-ID; the server closes the stream after about four minutes, so reconnect. #

200 text/event-stream

List agent runs #

200 { agents: [{ id, kind, label, status, started_at, finished_at, tokens_input, tokens_output, result, domain_name, domain_id }] }

Agent run activity #

200 { run, activity: [{ id, ts, text }] }

errors 404 agent run not found

Poll agent activity #

200 { activity: [{ id, ts, text, agent_run_id, kind, label, status }], cursor }

Stream agent activity (SSE) — Event name: agent.activity. #

200 text/event-stream

Send feedback #

201 { id, status: "new" }

List your feedback #

200 { feedback: [{ id, category, status, description, fix_url, fix_summary, created_at, … }] }

Service description #

200 { name, description, docs }

Health check — 503 when the database is unreachable or the scheduler is stale. #

200 { ok, db, cron, cron_age_minutes, queued_pages, dead_pages_pending }