sign in →

docs / querying the graph

Querying the graph

Every read endpoint, with the questions it answers.

docs/graph-queriesapi v1

List and filter entities#

GET /v1/domains/{domainId}/entities?type=person&q=teacher&limit=50&offset=0

Filters by kind and by a substring of name or description, most recently updated first. Page with next_offset (max 200 per page).

One entity, with sources#

GET /v1/domains/{domainId}/entities/{entityId}

Returns the entity, its facet, custom attributes, every relationships edge (with direction out or in and the other side's name and kind), and up to 50 provenance rows — the URL and quote behind each fact. Show provenance next to anything you display; it is what makes the graph citable.

Neighborhoods#

GET /v1/domains/{domainId}/entities/{entityId}/neighbors?depth=2

Breadth-first traversal up to three hops, as nodes and edges ready for a graph view (Cytoscape, Sigma, D3). “Who teaches at the festivals this association organizes?” is depth 2.

Relationships by predicate#

GET /v1/domains/{domainId}/relationships?relation=invested_in

Edges of one canonical predicate with both endpoints' names and kinds — an investor-to-portfolio table in one request. Up to 500 edges.

GET /v1/domains/{domainId}/search?q=tea+ceremony&type=event

Keyword and semantic matches merged and ranked; each result says whether it matched by keyword, semantic or both.

Timeline#

GET /v1/domains/{domainId}/timeline?from=2026-10-01&to=2026-12-31
GET /v1/domains/{domainId}/timeline?entity_id={personId}
GET /v1/domains/{domainId}/timeline?granularity=month

Events ordered by start with their participants. With entity_id, any entity's timeline — a person's workshops, an organization's events. With granularity, counts per year, month or day for a histogram.

Map (GeoJSON)#

GET /v1/domains/{domainId}/geo.geojson
GET /v1/domains/{domainId}/geo.geojson?entity_id={organizationId}
GET /v1/domains/{domainId}/geo.geojson?bbox=17.8,59.2,18.3,59.45
GET /v1/domains/{domainId}/geo.geojson?cluster=1&cell=0.5

A GeoJSON FeatureCollection of located entities ([lng, lat]), each feature carrying its connected entities. With entity_id, one entity's footprint: an organization's offices and venues, an event's location. cluster=1 returns grid clusters with counts for zoomed-out views.

Stats and export#

GET /v1/domains/{domainId}/stats
GET /v1/domains/{domainId}/export
GET /v1/domains/{domainId}/export?format=graphml

Stats give totals, entities per kind and the most common relations. Export returns the whole graph — entities, relationships, every facet table and attribute values — as JSON, or as GraphML for Gephi, yEd or Neo4j import.