HTTP API & SPARQL protocol

Every SDK is a thin wrapper over one HTTP API. If there’s no SDK for your language — or you want the native SPARQL Protocol — call it directly. The first-party TypeScript and Python SDKs are generated from the same API contract; see Types & generated models for the shapes they expose.

Conventions

Base URL: https://db.eu.littlebigbrain.com (hosted data plane). See endpoints.
Auth: Authorization: Bearer <stack-api-key> on every request.
Scope: ?graph=<graph>&branch=<branch> query params (default main).
Idempotency: write endpoints accept an Idempotency-Key header so retries are safe.
Content type: application/json request and response bodies.
Errors: structured JSON — see the error model.

Core endpoints

Method & path	Purpose
`POST /v1/graph/commit`	Write triplets / facts
`POST /v1/graph/import`	Bulk NDJSON ingest
`POST /v1/graph/retract`	Retract facts
`POST /v1/index/run`	Build/refresh persisted index families (`?wait=true`)
`GET /v1/search`	Hybrid search (`?query=`, `?source=`, `?consistency=`)
`POST /v1/search/multi`	RRF multi-search
`POST /v1/search/embedding`	Vector search
`POST /v1/traverse`	Bounded neighborhood traversal
`POST /v1/graph/query`	Structured / SPARQL-text query
`POST /v1/shacl`	SHACL select / validate
`GET /v1/graph/summary`	Graph summary
`GET /v1/graph/entities`	List / filter entities
`GET /v1/ontology`	Ontology view
`GET /v1/status`	Snapshot + index status
`GET /v1/usage`	Usage counters
`GET /metrics`	Prometheus text; `/api/metrics` for JSON

This is a representative subset of the API surface.

Examples

Write facts:

curl -sS -X POST "https://db.eu.littlebigbrain.com/v1/graph/commit?graph=main" \
  -H "Authorization: Bearer $LBB_API_KEY" \
  -H "Idempotency-Key: import-2026-06-13" \
  -H "Content-Type: application/json" \
  -d '{
    "triplets": [{
      "source": {"type": "SERVICE", "name": "auth-service"},
      "relation": "WRITES_TO",
      "target": {"type": "DATABASE", "name": "user-db"},
      "confidence": 0.93,
      "evidence": "auth-service writes identity records to user-db"
    }]
  }'

Build indexes and search:

curl -sS -X POST "https://db.eu.littlebigbrain.com/v1/index/run?graph=main&wait=true" \
  -H "Authorization: Bearer $LBB_API_KEY"

curl -sS "https://db.eu.littlebigbrain.com/v1/search?graph=main&source=persisted&consistency=strong&query=which%20systems%20store%20customer%20identity%20data" \
  -H "Authorization: Bearer $LBB_API_KEY"

Add &explain=true to a search to get the snapshot commit, which index runs were used, unindexed-tail length, and per-signal scoring — useful for verifying, for example, that the vector leg used the expected embedding model (explain.vector_model_id).

Bulk ingest

For large loads use POST /v1/graph/import with newline-delimited JSON — it is tens of times faster than per-triplet commits and supports flat properties, external keys, and a written_properties echo.

Native SPARQL 1.1 Protocol

Your stack serves the native SPARQL 1.1 Protocol at /sparql, so off-the-shelf SPARQL clients (YASGUI, Protégé, RDFLib’s SPARQLWrapper) connect directly:

GET /sparql?query=<encoded>
POST /sparql with a form body, or an application/sparql-query raw body
Accept-negotiated results: SPARQL Results JSON/XML, or CSV/TSV

curl -sS "https://<stack-host>/sparql" \
  --data-urlencode 'query=SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5' \
  -H "Accept: application/sparql-results+json"

Relations/types/properties are addressed as <https://littlebigbrain.com/{r,class,p}/name> with lowercase local names. For in-process use, the TypeScript and Python SDKs return parsed rows so you never zip head.vars with bindings by hand.