TB Research Public API v1

Machine-readable access to the TB Research tuberculosis research corpus. Anonymous access is intentionally generous — researchers should not need to pay or authenticate for read access. API keys exist to raise limits for high-volume use and to gate bulk export.

Get a free API key →

Base URL

https://tbresearch.org/v1

Authentication

All endpoints accept an optional API key via the Authorization: Bearer <key> header. Get a free key in seconds at /api-keys.

If the header is present but invalid, the request is rejected with a 401. If omitted, the request proceeds anonymously at lower rate limits.

Key format: tbr_<8-char-id>_<32-char-secret> (legacy tbk_-prefixed keys issued via CLI remain valid).

Rate Limits

Endpoint	Anonymous	With API Key
`GET /v1/search`	30 / min	300 / min
`GET /v1/documents/:id`	60 / min	600 / min
`GET /v1/citations/:id`	30 / min	300 / min
`GET /v1/bulk`	Requires key	1 / min, max 10K docs

Rate limits use a 60-second sliding window. Exceeded requests return 429 Too Many Requests with a Retry-After header. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

License Headers

Every single-document response includes a X-TBRsch-License: <license> header (e.g. CC BY 4.0, CC BY-NC 4.0, unknown). This tells downstream tools how they may use the retrieved content.

List and search responses include a licenses object in the response body summarising the count of each license across returned results.

Endpoints

GET/v1/search

Hybrid keyword + semantic search over the corpus.

Param	Type	Required	Description
q	string	required	Search query
limit	integer	optional	Max results (1–50, default 25)
document_type	string	optional	Comma-separated document types to filter
tb_subtype	string	optional	Comma-separated TB subtypes to filter
year_from	integer	optional	Earliest publication year
year_to	integer	optional	Latest publication year

curl "https://tbresearch.org/v1/search?q=MDR-TB+regimen&limit=5"

GET/v1/documents/:id

Retrieve a single document record by TB Research ID.

Param	Type	Required	Description
:id	string	required	TB Research document ID (e.g. tbrsch-00001)

curl "https://tbresearch.org/v1/documents/tbrsch-00001"

GET/v1/citations/:id

Get inbound and outbound citations for a document within the corpus.

Param	Type	Required	Description
:id	string	required	TB Research document ID

curl "https://tbresearch.org/v1/citations/tbrsch-00001"

GET/v1/bulk

Authenticated bulk export of the corpus as NDJSON or JSON. Requires API key.

Param	Type	Required	Description
since	ISO date	optional	Only docs with publication_date >= since
until	ISO date	optional	Only docs with publication_date <= until (default now)
source	string	optional	Filter by source (pubmed, europe_pmc, openalex, ...)
format	string	optional	ndjson (default) or json

curl -H "Authorization: Bearer $KEY" \
  "https://tbresearch.org/v1/bulk?since=2020-01-01" | wc -l

Support

Questions, bugs, and feature requests: GitHub Issues