REST API

The public HTTP service exposes datasource metadata, document browse, scoped search, and passage lookup over JSON. This page is the human-facing guide to the endpoints served by the qsl-reference deployment.

Current public datasources

ezratty, qsl-papers

Endpoints

Method	Path	Use
GET	/healthz	Basic liveness check. Returns {"ok": true}.
GET	/datasources	List the enabled public datasources and the current default-datasource state.
GET	/datasources/{name}	Return metadata for one datasource.
GET	/datasources/{name}/documents	List documents in one datasource with bounded metadata filters.
GET	/datasources/{name}/documents/{document_id}	Fetch one document by stable document_id.
GET	/datasources/{name}/documents/{document_id}/sections	List sections for one document.
POST	/search	Search passages by datasource, query string, mode, limit, and optional document/section scope.
POST	/passage	Fetch one passage by stable passage_id.

Search modes

• keyword: exact-term and token-based retrieval. Use this when you know the names, phrases, or technical terms you want.
• search: embedding-backed retrieval. Use this when you want semantically similar passages and the datasource has embeddings enabled.

If more than one datasource is enabled, include the datasource field explicitly in /search and /passage requests. Browse routes carry datasource identity in the path.

Example: list datasources

curl -fsS https://agents.quantumsoftwarelab.com/datasources

Example: list documents in one datasource

curl -fsS 'https://agents.quantumsoftwarelab.com/datasources/qsl-papers/documents?author=hopper&limit=5'

Example: scoped keyword search

curl -fsS   -H 'Content-Type: application/json'   -d '{"datasource":"qsl-papers","document_id":"paper-a","query":"surface code threshold","mode":"keyword","limit":3}'   https://agents.quantumsoftwarelab.com/search

Example: passage lookup

curl -fsS   -H 'Content-Type: application/json'   -d '{"datasource":"qsl-papers","passage_id":"paper-a-p1-000000-abcdef12"}'   https://agents.quantumsoftwarelab.com/passage

Response shape

Successful responses carry schema-versioned envelopes with ok: true. Browse and search results include stable datasource, document, and section identifiers so callers can preserve provenance when quoting or citing passages.