Query API

The query gateway exposes three transports against the same data plane: a REST surface for simple integrations, a GraphQL endpoint for typed clients, and a WebSocket channel for streamed result waves. All three are read-only and require no authentication.

Base URL

All three transports share the same underlying query engine — choose the interface that fits your client.

REST

OpenAPI 3.1 specification: docs/api/openapi.yaml. Primary endpoints:

• GET /api/search?q=...&top_k=20 — synchronous hybrid search.
• GET /api/document/{id} — single document by canonical id (e.g. pubmed:12345678).
• GET /api/facets — study-type and MeSH facet values with counts.
• GET /api/trials — trials filtered by condition, status, and phase.
• GET /api/recalls/recent?since_days=7 — recent FDA / EMA recall events.
• POST /api/tool/{name} — invoke a named tool (used by the MCP server).

GraphQL

Endpoint POST /graphql. Schema lives at gateway/src/schema.graphql and is part of the contracts freeze — schema changes require an rfc-interface PR.

WebSocket

Endpoint /ws with subprotocol evidencelens.v1. Streams three result waves per query (5 + 10 + 35) so the UI can render the first hits while the long tail finishes. Full message catalog: docs/api/websocket.md.

Rate limits

• REST / GraphQL: 60 req/min per IP.
• WebSocket: 10 simultaneous connections per IP.
• Tool calls (REST or MCP): 30 calls/min per session.