# qsl-agents public retrieval skill

Use this endpoint when you need public QSL retrieval without local repo access.

- Base URL: `https://agents.quantumsoftwarelab.com`
- MCP endpoint: `https://agents.quantumsoftwarelab.com/mcp`
- Also served at: `https://qsl-agents.is.ed.ac.uk`

- REST endpoints: `https://agents.quantumsoftwarelab.com/datasources`, `https://agents.quantumsoftwarelab.com/datasources/{name}/documents`, `https://agents.quantumsoftwarelab.com/search`, `https://agents.quantumsoftwarelab.com/passage`, `https://agents.quantumsoftwarelab.com/healthz`

## Public datasources

- `ezratty` - Understanding Quantum Technologies 2025: Olivier Ezratty's public reference text on vendors, hardware modalities, and quantum-computing engineering.
- `qsl-papers` - QSL Public Papers: Public QSL papers staged as searchable passages with bibliographic metadata for citation and provenance.

## When to use which surface

- Use MCP when your client already speaks JSON-RPC MCP.
- Use REST when a plain HTTP call is simpler.
- Use `documents` or `/datasources/{name}/documents` to browse a datasource before searching it.
- Use `sections` or `/datasources/{name}/documents/{document_id}/sections` when you want to inspect one document's structure first.
- Use `keyword` mode for named terms, vendor names, paper titles, and exact phrases.
- Use `search` mode for embedding-backed semantic lookup when you want conceptually similar passages.
- If more than one datasource is enabled, include `datasource` explicitly in MCP calls and in REST `search` or `passage` requests.

## MCP document browse example

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"documents","arguments":{"datasource":"qsl-papers","author":"hopper","limit":5}}}
```

POST that JSON to `/mcp` with `Content-Type: application/json`.

## REST scoped search example

```json
{"datasource":"qsl-papers","document_id":"paper-a","query":"surface code threshold","mode":"keyword","limit":3}
```

POST that JSON to `/search` with `Content-Type: application/json`.

## Browse workflow

1. Call `/datasources` or MCP `sources`.
2. Browse documents with `/datasources/{name}/documents` or MCP `documents`.
3. If needed, inspect `/datasources/{name}/documents/{document_id}/sections` or MCP `sections`.
4. Run unscoped or scoped `search`.

## Provenance

Search results carry datasource, document, section, and passage identifiers. Keep those identifiers when quoting or citing returned passages.

Human-facing docs live at `/docs/rest/`, `/docs/mcp/`, and `/docs/reference/`.