API

Programmatic access to the Preclinical Database

Getting access

The API is available to academic researchers on request. Send us a short note about your institution and intended use — we'll issue you a personal API key.

Request API access →

Authentication

Every request must include your key as a bearer token in theAuthorization header. Requests without a valid key return 401 Unauthorized.

Authorization: Bearer YOUR_API_KEY

Keep your key private. If it is lost or exposed, contact us to rotate it.

Base URL

https://preclinicaldb.org/api/v1

The /v1 prefix is reserved for the stable public API. Breaking changes will move to /v2.

Endpoints

Five resources: records (one entry per extracted study row), publications (aggregated to one entry per PMCID), and the three entity catalogs — diseases, drugs, and animals. All endpoints follow the same { data, meta } shape with pagination.

GET /v1/records

Search and filter row-level extracted records (186,627 rows). Returns a summary payload per record; use the detail endpoint for entity identifiers, synonyms, and full metadata.

Query parameters

qstringFree-text search across titles and entity names.
year_minintEarliest publication year (inclusive).
year_maxintLatest publication year (inclusive).
animalsstring[]Repeatable. Filter by animal name (exact match). E.g. animals=mouse&animals=rat.
diseasesstring[]Repeatable. Filter by disease name (exact match).
drugsstring[]Repeatable. Filter by drug name (exact match).
subject_size_minintMinimum total subject size.
subject_size_maxintMaximum total subject size.
include_partialboolDefault false. When true, includes records missing one or more entity types.
sort_bystringOne of: date, confidence_score, total_subject_size, title.
sort_orderstringasc or desc. Defaults to desc.
pageint1-indexed page number. Default 1.
page_sizeintRecords per page. Default 50, max 200.

Example

curl "https://preclinicaldb.org/api/v1/records?q=cancer&diseases=melanoma&page_size=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "PMC12345-0",
      "pmcid": "PMC12345",
      "title": "Study title",
      "date": "2023-06-01",
      "link": "https://pmc.ncbi.nlm.nih.gov/articles/PMC12345/",
      "confidence_score": 0.97,
      "total_subject_size": 24,
      "diseases": ["melanoma"],
      "drugs": ["pembrolizumab"],
      "animals": ["mouse"]
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 25,
    "total": 812,
    "has_more": true
  }
}

GET /v1/records/{id}

Full record with entity identifiers (MeSH, PubChem, DrugBank, Disease Ontology, UMLS), synonyms, and strain details.

Example

curl "https://preclinicaldb.org/api/v1/records/PMC12345-0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "PMC12345-0",
    "pmcid": "PMC12345",
    "title": "Study title",
    "date": "2023-06-01",
    "link": "https://pmc.ncbi.nlm.nih.gov/articles/PMC12345/",
    "confidence_score": 0.97,
    "total_subject_size": 24,
    "diseases": {
      "names": ["melanoma"],
      "synonyms": ["malignant melanoma"],
      "details": [
        {
          "name": "melanoma",
          "external_ids": {
            "mesh": ["D008545"],
            "diseaseontology": ["DOID:1909"]
          }
        }
      ]
    },
    "drugs": { "names": [...], "synonyms": [...], "details": [...] },
    "animals": { "names": [...], "synonyms": [...], "details": [...] }
  }
}

GET /v1/publications

One entry per PMCID (134,565 publications), aggregated from the row-level records. Use this instead of /records when you want deduplicated publication-level counts.

Query parameters

qstringFree-text search across titles and entity names.
year_minintEarliest publication year (inclusive).
year_maxintLatest publication year (inclusive).
diseasesstring[]Repeatable. Filter by disease name (exact match).
drugsstring[]Repeatable. Filter by drug name (exact match).
animalsstring[]Repeatable. Filter by animal name (exact match).
entity_idstring[]Repeatable. Filter by PCDB entity ID (e.g. entity_id=PCDB_DI1).
sort_bystringOne of: date, confidence_score_max, row_count, title.
sort_orderstringasc or desc. Defaults to desc.
pageint1-indexed page number. Default 1.
page_sizeintRecords per page. Default 50, max 200.

Example

curl "https://preclinicaldb.org/api/v1/publications?entity_id=PCDB_DI1&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [{
    "pmcid": "PMC12345",
    "title": "Study title",
    "date": "2023-06-01",
    "link": "https://pmc.ncbi.nlm.nih.gov/articles/PMC12345/",
    "confidence_score_max": 0.98,
    "row_count": 3,
    "total_subject_size_sum": 72,
    "diseases": ["melanoma"],
    "drugs": ["pembrolizumab", "nivolumab"],
    "animals": ["mouse"],
    "entity_pcdb_ids": ["PCDB_DI42", "PCDB_DR9", "PCDB_AN1"]
  }],
  "meta": { "page": 1, "page_size": 5, "total": 812, "has_more": true }
}

GET /v1/publications/{pmcid}

One publication with all extracted rows in a rows array. Each row has its own confidence, subject size, and full entity details.

Example

curl "https://preclinicaldb.org/api/v1/publications/PMC12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/diseases · GET /v1/drugs · GET /v1/animals

Paginated catalogs of the three entity types (2,602 diseases, 11,753 drugs, 99 animals). Each entry carries its PCDB ID, canonical name, all synonyms, and external identifiers (MeSH, Disease Ontology, DrugBank, UMLS).

Query parameters

qstringCase-insensitive substring match against name and synonyms.
pageint1-indexed page number. Default 1.
page_sizeintEntries per page. Default 50, max 200.

Example

curl "https://preclinicaldb.org/api/v1/diseases?q=melanoma&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [{
    "id": "PCDB_DI1",
    "name": "Colorectal Neoplasms",
    "synonyms": ["Colorectal Cancer", "..."],
    "external_ids": {
      "mesh": ["D015179"],
      "diseaseontology": ["DOID:9256", "DOID:0080199"]
    },
    "mesh_tree_ids": ["C04.588.274.476.411.307"],
    "categories": ["C04", "C06"]
  }],
  "meta": { "page": 1, "page_size": 5, "total": 2602, "has_more": true }
}

GET /v1/{kind}/{id}

One entity plus a paginated list of publications that mention it. {kind} is diseases, drugs, or animals; {id} is a PCDB ID like PCDB_DI1.

Query parameters

records_pageintPage of nested publications. Default 1.
records_page_sizeintPublications per page. Default 25, max 200.

Example

curl "https://preclinicaldb.org/api/v1/diseases/PCDB_DI1?records_page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

400Bad RequestMalformed parameters.
401UnauthorizedMissing or invalid Bearer token.
404Not FoundRecord ID does not exist.
500Server ErrorSearch backend unavailable.

Citation

If the API supports your work, please acknowledge the Preclinical Database. A formal citation will appear here once our paper is published.