NCI EVS Thesaurus API

Free NCI EVS REST API with no key: NCI Thesaurus concepts with synonyms by source, definitions, hierarchies and mappings across cancer research terminologies.

No API key requiredHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the NCI EVS Thesaurus API?

The NCI EVS REST API is a free, key-free service exposing the NCI Thesaurus and other terminologies curated by the US National Cancer Institute. Concept lookups return the preferred name, synonyms attributed to their contributing source, definitions, hierarchy relationships and cross-terminology mappings.

NCI Thesaurus is the reference vocabulary for cancer research in the United States, and its distinguishing feature is that every synonym is attributed. The melanoma record does not simply list alternative names; it records that CDISC calls it `MELANOMA, MALIGNANT`, that CTEP uses `Melanoma` with MedDRA code 10053571, and that Cellosaurus, CPTAC, CTRP and GDC each contribute their own preferred term. For anyone harmonising clinical trial data across those systems, that attribution is the entire point.

The `version` field matters more than it usually does. NCI publishes monthly releases — `26.07d` in the example — and concepts are added, deprecated and re-parented between them, so pinning a version is the difference between a reproducible analysis and a quietly shifting one. Note also that EVS hosts several terminologies behind the same endpoint shape, some of which are licensed separately: NCI Thesaurus itself is open, but MedDRA and SNOMED content surfaced through EVS remains subject to those bodies' own licences. Check `terminology` before assuming you may redistribute what you retrieved.

Quick facts

Base URL: https://api-evsrest.nci.nih.gov/api/v1
Authentication: No API key or account. NCI Thesaurus is released for free use with attribution, but EVS also serves terminologies such as MedDRA and SNOMED that require their own licences — the `terminology` field tells you which you are holding.
Rate limit: No published limit. EVS publishes full terminology downloads for bulk work.
Pricing: Free. NCI Thesaurus is openly licensed; other hosted terminologies vary.
CORS: Not enabled — call it from your server
Official docs: Read the docs

How to use the NCI EVS Thesaurus API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch the NCI Thesaurus concept for Melanoma

GET https://api-evsrest.nci.nih.gov/api/v1/concept/ncit/C3224?include=summary

curl

curl 'https://api-evsrest.nci.nih.gov/api/v1/concept/ncit/C3224?include=summary' \
  -H 'Accept: application/json'

JavaScript (fetch)

const res = await fetch("https://api-evsrest.nci.nih.gov/api/v1/concept/ncit/C3224?include=summary", {
  headers: {
    "Accept": "application/json",
  },
});
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

headers = {
    "Accept": "application/json",
}

res = requests.get("https://api-evsrest.nci.nih.gov/api/v1/concept/ncit/C3224?include=summary", headers=headers, timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "code": "C3224",
  "name": "Melanoma",
  "terminology": "ncit",
  "version": "26.07d",
  "conceptStatus": "DEFAULT",
  "leaf": false,
  "active": true,
  "synonyms": [
    {
      "name": "Melanoma",
      "termType": "SY",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "caDSR"
    },
    {
      "name": "Malignant Melanoma",
      "termType": "SY",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "CDISC"
    },
    {
      "name": "MELANOMA, MALIGNANT",
      "termType": "PT",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "CDISC"
    },
    {
      "name": "Melanoma",
      "termType": "PT",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "Cellosaurus"
    },
    {
      "name": "Malignant Melanoma",
      "termType": "PT",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "CPTAC"
    },
    {
      "name": "Melanoma",
      "termType": "PT",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "CTEP",
      "code": "10053571",
      "subSource": "SDC"
    },
    {
      "name": "Melanoma",
      "termType": "DN",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "CTRP"
    },
    {
      "name": "Melanoma",
      "termType": "PT",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "CTRP"
    },
    {
      "name": "Melanoma",
      "termType": "PT",
      "type": "FULL_SYN",
      "typeCode": "P90",
      "source": "GDC"
    },
    {
      "name": "Melanoma, NOS",
      "termType": "SY",
      "type": "FULL_SYN",
      "typeCode

Parameters

Parameter	Type	Required	Description
`terminology`	path segment	Required	Which vocabulary to query — `ncit` for NCI Thesaurus, plus others EVS hosts. `ncit`
`code`	path segment	Required	Concept code within that terminology. `C3224`
`include`	query	Optional	How much detail to return: `minimal`, `summary`, `full`, or a comma-separated list of specific sections. `summary`
`(endpoint) /concept/{terminology}/search`	path	Optional	Search concepts by term rather than fetching by code. `/concept/ncit/search?term=melanoma`
`(endpoint) /concept/{terminology}/{code}/children`	path	Optional	Direct child concepts in the hierarchy. `/concept/ncit/C3224/children`
`(endpoint) /metadata/terminologies`	path	Optional	List every terminology EVS serves with its current version. `/metadata/terminologies`

Response fields

codestring: The concept code, echoed back.
namestring: Preferred name for the concept.
terminology / versionstring: Which vocabulary and which monthly release answered. Pin the version for reproducible work.
conceptStatusstring: `DEFAULT` for active concepts; retired concepts carry other statuses and should not be used for new annotation.
activeboolean: Whether the concept is current in this release.
leafboolean: False when the concept has children, which tells you whether it is a specific or a grouping term.
synonyms[]array: Alternative names, each with `source` (CDISC, CTEP, GDC, CPTAC, Cellosaurus and others), `termType` and sometimes the source's own `code`.
synonyms[].termTypestring: `PT` preferred term, `SY` synonym, `DN` display name. Determines which label a given system would use.

What you can build with the NCI EVS Thesaurus API

Harmonise cancer terminology across CDISC, CTEP and GDC datasets
Resolve an NCI Thesaurus code to its preferred name and definition
Find which term a specific standards body uses for a concept
Walk the concept hierarchy to roll data up to broader categories
Map trial data terms onto a common controlled vocabulary

Common errors and how to fix them

404

Unknown code, or the code belongs to a different terminology.

Fix: Codes are terminology-scoped. `C3224` is meaningful in `ncit` and not elsewhere; use the search endpoint when you only have a term.

Sparse response

`include` defaulted to minimal.

Fix: Request `include=summary` or `include=full`. The default projection omits synonyms and definitions entirely.

Results change between months

EVS ships monthly terminology releases.

Fix: Record the `version` from every response, and query a pinned version when an analysis must be reproducible.

Licensed content redistributed by mistake

EVS hosts more than NCI Thesaurus.

Fix: Check the `terminology` field. MedDRA and SNOMED content carry their own licences regardless of the fact that EVS served them without a key.

NCI EVS Thesaurus API — frequently asked questions

Is the NCI EVS API free?

Yes, free with no key or registration. NCI Thesaurus is openly licensed with attribution. Other terminologies served through the same API — MedDRA and SNOMED among them — remain subject to their own licence terms.

Why are synonyms attributed to different sources?

Because NCI Thesaurus is used to reconcile terminology across cancer research systems that each have their own preferred label. Knowing that CDISC writes `MELANOMA, MALIGNANT` while GDC writes `Melanoma` is exactly what lets you join their datasets correctly.

What does the version field mean?

It identifies the monthly NCI Thesaurus release that answered your request. Concepts are added, deprecated and re-parented between releases, so pinning a version keeps a downstream analysis stable.

Can I use this to look up cancer treatments?

It will give you the standard terminology for treatments, drugs and procedures, including their codes in various systems. It is a vocabulary service and carries no clinical recommendations — treatment decisions are not within its scope.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

Text Compare

Compare two texts online free and highlight every difference. A private text comparison tool that finds matches and changes right in your browser.

NCI EVS Thesaurus is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.