sign in →

docs / quickstart

Quickstart

From an API key to a queryable knowledge graph. Five requests; the agents do the rest.

docs/quickstartapi v1

1. Get an API key#

Sign in to the console (or create an account), open any domain's API page and create a project key. Owners can also create keys through the API. Keep it in an environment variable:

export NOLVIN_KEY=nlv_…

A full key can build and change graphs; a read key can only query. See Authentication.

2. Describe the domain#

Start an autopilot domain with one sentence. Say what belongs, where, and any fields you need — “with contact info” adds email and phone attributes.

curl https://api.nolvin.com/v1/domains/autopilot \
  -H "Authorization: Bearer $NOLVIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Japanese crafts, arts and cooking courses in Stockholm, with contact info", "max_spend_usd": 10}'
{"id": "71dc3e2d-…", "stage": "brief"}

The response is 202: the work runs in the background. Defaults: 150 pages, a $25 monthly spend cap, three crawl-and-assess cycles.

3. Follow progress#

Poll the autopilot state. The stage moves through brief, discover, crawling, assess and grow and settles at steady; a first graph is usually queryable within the first crawl.

curl https://api.nolvin.com/v1/domains/$DOMAIN/autopilot -H "Authorization: Bearer $NOLVIN_KEY"
{"autopilot": {"stage": "crawling", "cycle": 0, "max_cycles": 3,
  "brief": {"name": "Japansk kultur i Stockholm", "language": "sv", "region": "Stockholm",
            "include": ["…"], "attributes": [{"key": "email", …}, {"key": "phone", …}], …}, …}}

For live progress, stream GET /v1/domains/$DOMAIN/events or register a webhook for crawl.finished. The scorecard gives a 0–100 quality score at any point.

4. Query entities#

curl "https://api.nolvin.com/v1/domains/$DOMAIN/entities?type=object&limit=20" -H "Authorization: Bearer $NOLVIN_KEY"
{"entities": [{"id": "…", "type": "object", "name": "Etnografiska museet",
   "description": "Museum i Stockholm med samlingar …", "aliases": "[]", …}],
 "next_offset": 20}

Open one entity to see its facet, attributes, relationships and sources:

curl https://api.nolvin.com/v1/domains/$DOMAIN/entities/$ENTITY -H "Authorization: Bearer $NOLVIN_KEY"
{"entity": {…}, "facet": {"category": "museum", "identifier": null},
 "attributes": {"email": "info@…", "phone": "08-…"},
 "relationships": [{"relation": "organizes", "direction": "out", "name": "…", "type": "event", …}],
 "provenance": [{"url": "https://…", "snippet": "…", "created_at": "…"}]}

5. Timeline and map#

Any entity projects onto a timeline through its events and onto a map through its locations:

curl "https://api.nolvin.com/v1/domains/$DOMAIN/timeline?entity_id=$ENTITY&from=2026-10-01" -H "Authorization: Bearer $NOLVIN_KEY"
curl "https://api.nolvin.com/v1/domains/$DOMAIN/geo.geojson?entity_id=$ENTITY" -H "Authorization: Bearer $NOLVIN_KEY"

The GeoJSON drops straight into Leaflet, MapLibre or any GIS tool. Next: Querying the graph.

Without autopilot#

Prefer to choose sources yourself? Create a domain, publish a gate, add sources and crawl:

curl https://api.nolvin.com/v1/domains -H "Authorization: Bearer $NOLVIN_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Nordic climate tech", "description": "Climate tech startups, investors and events in the Nordics"}'
curl https://api.nolvin.com/v1/domains/$DOMAIN/spec -H "Authorization: Bearer $NOLVIN_KEY" -H "Content-Type: application/json" \
  -d '{"instructions": "Include: companies whose main product reduces emissions … Exclude: news about large incumbents …"}'
curl -X POST https://api.nolvin.com/v1/domains/$DOMAIN/spec/$SPEC/publish -H "Authorization: Bearer $NOLVIN_KEY"
curl https://api.nolvin.com/v1/domains/$DOMAIN/sources -H "Authorization: Bearer $NOLVIN_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.org/members"}'

Test the gate on a single page first with POST …/dry-run: it extracts without writing to the graph.