Integration guides · snapshots, APIs, warehouses, agents

These patterns follow the dataset contract: snapshot formats, REST paths, MCP tools, field catalog, sample availability, and API examples.

Choose a surface

Snapshot

Best for warehouses, offline analysis, BI tools, and repeatable audit work.

REST API

Best for app backends and services that need current records from /v1/trials.

MCP

Best for AI agents that need read-only, source-attributed tools.

Snapshot files

Snapshot files are the lowest-friction path for warehouse loading and durable audit trails. The release page describes the current version, sample manifest, and buyer download contract.

JSON snapshot
application/json
CSV snapshot
text/csv
SQLite snapshot
application/x-sqlite3

snapshot workflowbash

# authenticated buyer flow
open /portal/download

# inspect the bundle locally after download
ls -lh *.{json,csv,sqlite,parquet} 2>/dev/null || true

Warehouse loading

Use file formats for bulk analytics. Keep provenance and source fields loaded alongside entity records so downstream users can verify each value.

duckdb / parquetsql

-- Replace dataset.parquet with the shipped file name.
SELECT *
FROM 'dataset.parquet'
LIMIT 20;

pandas / pyarrowpython

import pyarrow.parquet as pq

table = pq.read_table("dataset.parquet")
df = table.to_pandas()
print(df.shape)

REST clients

REST access runs at https://api.trialbase-db.org/v1.

curlbash

curl "https://api.trialbase-db.org/v1/trials?limit=5" \
  -H "Authorization: Bearer trialbase_live_····"

fetch.tsts

const res = await fetch("https://api.trialbase-db.org/v1/trials?limit=5", {
  headers: { Authorization: "Bearer trialbase_live_····" },
});
if (!res.ok) throw new Error(String(res.status));
const body = await res.json();

Search by registry identifier

Search authenticated production access for a registry identifier and source link.

manifest examplebash

curl "https://api.trialbase-db.org/v1/trials?q=ISRCTN17465883&limit=5" \
  -H "Authorization: Bearer trialbase_live_····"

Fetch one canonical trial

Inspect one included trial record with registry provenance.

manifest examplebash

curl "https://api.trialbase-db.org/v1/trials/679751" \
  -H "Authorization: Bearer trialbase_live_····"

List data sources

Inspect commercial source terms and registries represented in the delivered dataset.

manifest examplebash

curl "https://api.trialbase-db.org/v1/sources" \
  -H "Authorization: Bearer trialbase_live_····"

MCP agents

MCP exposes read-only tools over https://api.trialbase-db.org/mcp. The protocol is harness agnostic, while each client wraps the HTTP URL and bearer token differently. See the MCP client configuration guide for Claude, OpenAI Codex, Google Gemini CLI, and Cursor examples.

trials_searchSearch trials by condition, intervention, sponsor, phase, status, country, or free text.
trials_getFetch one canonical trial by id, with every registry's provenance + cross-registry IDs.
trials_lookup_by_idsBulk registry-id (NCT / EudraCT / ISRCTN) -> canonical trial resolution.
trials_coveragePer-registry / per-phase / per-status counts, date ranges, field-fill stats.

Field selection

Start integrations with stable, high-value fields from the generated schema catalog. For the complete table, use the data dictionary.

TrialBase DB canonical trial identifier. Multiple registry records can resolve to the same canonical id.

primary_registry

Source registry selected as the canonical record, using a sources.code value such as clinicaltrials-gov, eu-ctis, eudract, isrctn, or drks.

registry_id

Identifier for the canonical source registry record, for example an NCT, EudraCT, CTIS, or ISRCTN id.

registry_ids

Cross-registry identifiers attached to the canonical trial, shaped as objects with registry, id, and hard or soft match method.

source_record_url

Canonical public registry page for the source record used in the exported row.

sponsor_name

Lead sponsor name drawn from the public trial registry record.

conditions

Condition terms associated with the trial.

countries

Countries associated with trial recruitment or study locations, used by country filters.

Evaluation path

The sample bundle is published with 152 rows. Use it to validate schema, source provenance, and integration ergonomics before buying the production snapshot.

A good first production smoke test is /v1/trials?q=ISRCTN17465883&limit=5: Search authenticated production access for a registry identifier and source link.

Integration caveats

TrialBase DB is reference data, not medical advice, trial recruitment advice or regulatory advice.
Buyers remain responsible for validating suitability for regulated clinical, commercial or publication workflows.
Array fields preserve registry-reported terms after trimming and exact-repeat deduplication; completeness and selected provenance are release-level measurements, not schema guarantees.

Need a stack-specific example? Email data@apex-db.org.