Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.0.1
info:
title: NCI EVS Rest API
description: Endpoints to support searching, metadata, and content retrieval for EVS terminologies. To learn more
about how to interact with this api, see the <a href="https://github.com/NCIEVS/evsrestapi-client-SDK">Github
evsrestapi-client-SDK project.</a>
termsOfService: https://evs.nci.nih.gov/ftp1/NCI_Thesaurus/ThesaurusTermsofUse.htm
contact:
name: NCI EVS
email: NCIAppSupport@nih.gov
version: 2.4.1.RELEASE
x-apis-io-source: https://api-evsrest.nci.nih.gov/v3/api-docs
x-apis-io-harvested: '2026-09-05'
x-apis-io-method: searched
servers:
- url: https://api-evsrest.nci.nih.gov
description: Production host (resolved from the URL this specification was served from; the published document
carries '/')
paths:
/api/v1/sparql/{terminology}:
post:
tags:
- Search endpoint
summary: Get SPARQL query results
description: Perform a SPARQL query for a specified terminology.
operationId: getSparqlBindings
parameters:
- name: terminology
in: path
description: Single terminology to search, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
- name: fromRecord
in: query
description: Start index of the search results
required: false
schema:
type: integer
format: int32
example: 0
- name: pageSize
in: query
description: Max number of results to return
required: false
schema:
type: integer
format: int32
example: 10
- name: prefixes
in: query
description: Use 'true' to use queries with declared prefixes
required: false
schema:
type: boolean
example: true
- name: X-EVSRESTAPI-License-Key
in: header
description: Required license information for restricted terminologies. <a href='https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/LICENSE.md'
target='_blank'>See here for detailed information</a>.
required: false
schema:
type: string
requestBody:
description: SPARQL query to execute on the graph for the specified terminology. <a href='https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/SPARQL.md'
target='_blank'>See here for more information and examples of using SPARQL with EVSRESTAPI</a>.
content:
text/plain:
schema:
type: string
required: true
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
$ref: '#/components/schemas/MapResultList'
/api/v1/concept/{terminology}/search:
get:
tags:
- Search endpoint
summary: Get concept search results for a specified terminology
description: Use cases for search range from very simple term searches, use of paging parameters, additional
filters, searches properties, roles, and associations, and so on. To further explore the range of search
options, take a look at the <a href='https://github.com/NCIEVS/evsrestapi-client-SDK' target='_blank'>Github
client SDK library created for the NCI EVS Rest API</a>.
operationId: searchSingleTerminology
parameters:
- name: terminology
in: path
description: Single terminology to search, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
- name: X-EVSRESTAPI-License-Key
in: header
description: Required license information for restricted terminologies. <a href='https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/LICENSE.md'
target='_blank'>See here for detailed information</a>.
required: false
schema:
type: string
- name: term
in: query
description: The term, phrase, or code to be searched, e.g. 'melanoma'
schema:
type: string
- name: type
in: query
description: 'The match type, one of: contains, match, startsWith, phrase, AND, OR, fuzzy.'
schema:
type: string
example: contains
- name: sort
in: query
description: The search parameter to sort results by
schema:
type: string
- name: ascending
in: query
description: Sort ascending (if true) or descending (if false)
schema:
type: boolean
- name: include
in: query
description: 'Indicator of how much data to return. Comma-separated list of any of the following values:
minimal, summary, full, associations, children, definitions, disjointWith, history, inverseAssociations,
inverseRoles, maps, parents, properties, roles, synonyms. <a href=''https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/INCLUDE.md''
target=''_blank''>See here for detailed information</a>.'
schema:
type: string
example: minimal
- name: fromRecord
in: query
description: Start index of the search results
schema:
type: integer
format: int32
example: 0
- name: pageSize
in: query
description: Max number of results to return
schema:
type: integer
format: int32
example: 10
- name: conceptStatus
in: query
description: Comma-separated list of concept status values to restrict search results by. <p><a href='/api/v1/metadata/ncit/conceptStatuses'
target='_blank'>Click here for a list of NCI Thesaurus values</a>. This parameter is only meaningful for
<i>terminology=ncit</i>.</p>
schema:
type: string
- name: property
in: query
description: 'Comma-separated list of properties to restrict search results by (see also <i>value</i>).
e.g.<ul><li>''P106,P322'' for <i>terminology=ncit</i></li><li>''COLOR,SHAPE'' for <i>terminology=ncim</i></li></ul><p><a
href=''/api/v1/metadata/ncit/properties'' target=''_blank''>Click here for a list of NCI Thesaurus properties</a>.</p><p><a
href=''/api/v1/metadata/ncim/properties'' target=''_blank''>Click here for a list of NCI Metathesaurus
properties</a>.</p> The properties can be specified as code or name. NOTE: This feature works with <i>value</i>
to find concepts having one of the specified properties with an exact value matching the <i>value</i>
parameter. Using a <i>term</i> will further restrict results to those also matching the term.'
schema:
type: string
- name: value
in: query
description: 'A property value to restrict search results by. NOTE: This feature works with <i>property</i>
to find concepts having one of the specified properties with an exact value matching this parameter. Using
a <i>term</i> will further restrict results to those also matching the term.'
schema:
type: string
- name: definitionSource
in: query
description: Comma-separated list of definition sources to restrict search results by. <p><a href='/api/v1/metadata/ncit/definitionSources'
target='_blank'>Click here for a list of NCI Thesaurus values</a>.</p><p><a href='/api/v1/metadata/ncim/definitionSources'
target='_blank'>Click here for a list of NCI Metathesaurus values</a>.</p>
schema:
type: string
- name: definitionType
in: query
description: Comma-separated list of definition types to restrict search results by, e.g. 'DEFINITION,ALT_DEFINITION'
for <i>terminology=ncit</i>. <p><a href='/api/v1/metadata/ncit/definitionTypes' target='_blank'>Click
here for a list of NCI Thesaurus values</a>. This parameter is only meaningful for <i>terminology=ncit</i>.</p>
schema:
type: string
- name: synonymSource
in: query
description: Comma-separated list of synonym sources to restrict search results by. <p><a href='/api/v1/metadata/ncit/synonymSources'
target='_blank'>Click here for a list of NCI Thesaurus values</a>.</p> <p><a href='/api/v1/metadata/ncim/synonymSources'
target='_blank'>Click here for a list of NCI Metathesaurus values</a>.</p>
schema:
type: string
- name: synonymType
in: query
description: Comma-separated list of synonym types to restrict search results by, e.g. 'FULL_SYN'. <p><a
href='/api/v1/metadata/ncit/synonymTypes' target='_blank'>Click here for a list of NCI Thesaurus values</a>.
This parameter is only meaningful for <i>terminology=ncit</i>.</p>
schema:
type: string
- name: synonymTermType
in: query
description: Comma-separated list of synonym term type values to restrict search results by. <p><a href='/api/v1/metadata/ncit/termTypes'
target='_blank'>Click here for a list of NCI Thesaurus values</a>.</p> <p><a href='/api/v1/metadata/ncim/termTypes'
target='_blank'>Click here for a list of NCI Metathesaurus values</a>.</p>
schema:
type: string
- name: subset
in: query
description: Comma-separated list of subsets to restrict search results by, e.g. 'C157225'. The value '*'
can also be used to return results that participate in at least one subset. This parameter is only meaningful
for <i>terminology=ncit</i>
schema:
type: string
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
$ref: '#/components/schemas/ConceptResultList'
post:
tags:
- Search endpoint
summary: Get concept search results for a specified terminology
description: Use cases for search range from very simple term searches, use of paging parameters, additional
filters, searches properties, roles, and associations, and so on. To further explore the range of search
options, take a look at the <a href='https://github.com/NCIEVS/evsrestapi-client-SDK' target='_blank'>Github
client SDK library created for the NCI EVS Rest API</a>.
operationId: searchSingleTerminologySparql
parameters:
- name: terminology
in: path
description: Single terminology to search, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
- name: prefixes
in: query
description: Use 'true' to use queries with declared prefixes
required: false
schema:
type: boolean
example: true
- name: X-EVSRESTAPI-License-Key
in: header
description: Required license information for restricted terminologies. <a href='https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/LICENSE.md'
target='_blank'>See here for detailed information</a>.
required: false
schema:
type: string
- name: term
in: query
description: The term, phrase, or code to be searched, e.g. 'melanoma'
schema:
type: string
- name: type
in: query
description: 'The match type, one of: contains, match, startsWith, phrase, AND, OR, fuzzy.'
schema:
type: string
example: contains
- name: sort
in: query
description: The search parameter to sort results by
schema:
type: string
- name: ascending
in: query
description: Sort ascending (if true) or descending (if false)
schema:
type: boolean
- name: include
in: query
description: 'Indicator of how much data to return. Comma-separated list of any of the following values:
minimal, summary, full, associations, children, definitions, disjointWith, history, inverseAssociations,
inverseRoles, maps, parents, properties, roles, synonyms. <a href=''https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/INCLUDE.md''
target=''_blank''>See here for detailed information</a>.'
schema:
type: string
example: minimal
- name: fromRecord
in: query
description: Start index of the search results
schema:
type: integer
format: int32
example: 0
- name: pageSize
in: query
description: Max number of results to return
schema:
type: integer
format: int32
example: 10
- name: conceptStatus
in: query
description: Comma-separated list of concept status values to restrict search results by. <p><a href='/api/v1/metadata/ncit/conceptStatuses'
target='_blank'>Click here for a list of NCI Thesaurus values</a>. This parameter is only meaningful for
<i>terminology=ncit</i>.</p>
schema:
type: string
- name: property
in: query
description: 'Comma-separated list of properties to restrict search results by (see also <i>value</i>).
e.g.<ul><li>''P106,P322'' for <i>terminology=ncit</i></li><li>''COLOR,SHAPE'' for <i>terminology=ncim</i></li></ul><p><a
href=''/api/v1/metadata/ncit/properties'' target=''_blank''>Click here for a list of NCI Thesaurus properties</a>.</p><p><a
href=''/api/v1/metadata/ncim/properties'' target=''_blank''>Click here for a list of NCI Metathesaurus
properties</a>.</p> The properties can be specified as code or name. NOTE: This feature works with <i>value</i>
to find concepts having one of the specified properties with an exact value matching the <i>value</i>
parameter. Using a <i>term</i> will further restrict results to those also matching the term.'
schema:
type: string
- name: value
in: query
description: 'A property value to restrict search results by. NOTE: This feature works with <i>property</i>
to find concepts having one of the specified properties with an exact value matching this parameter. Using
a <i>term</i> will further restrict results to those also matching the term.'
schema:
type: string
- name: definitionSource
in: query
description: Comma-separated list of definition sources to restrict search results by. <p><a href='/api/v1/metadata/ncit/definitionSources'
target='_blank'>Click here for a list of NCI Thesaurus values</a>.</p><p><a href='/api/v1/metadata/ncim/definitionSources'
target='_blank'>Click here for a list of NCI Metathesaurus values</a>.</p>
schema:
type: string
- name: definitionType
in: query
description: Comma-separated list of definition types to restrict search results by, e.g. 'DEFINITION,ALT_DEFINITION'
for <i>terminology=ncit</i>. <p><a href='/api/v1/metadata/ncit/definitionTypes' target='_blank'>Click
here for a list of NCI Thesaurus values</a>. This parameter is only meaningful for <i>terminology=ncit</i>.</p>
schema:
type: string
- name: synonymSource
in: query
description: Comma-separated list of synonym sources to restrict search results by. <p><a href='/api/v1/metadata/ncit/synonymSources'
target='_blank'>Click here for a list of NCI Thesaurus values</a>.</p> <p><a href='/api/v1/metadata/ncim/synonymSources'
target='_blank'>Click here for a list of NCI Metathesaurus values</a>.</p>
schema:
type: string
- name: synonymType
in: query
description: Comma-separated list of synonym types to restrict search results by, e.g. 'FULL_SYN'. <p><a
href='/api/v1/metadata/ncit/synonymTypes' target='_blank'>Click here for a list of NCI Thesaurus values</a>.
This parameter is only meaningful for <i>terminology=ncit</i>.</p>
schema:
type: string
- name: synonymTermType
in: query
description: Comma-separated list of synonym term type values to restrict search results by. <p><a href='/api/v1/metadata/ncit/termTypes'
target='_blank'>Click here for a list of NCI Thesaurus values</a>.</p> <p><a href='/api/v1/metadata/ncim/termTypes'
target='_blank'>Click here for a list of NCI Metathesaurus values</a>.</p>
schema:
type: string
- name: subset
in: query
description: Comma-separated list of subsets to restrict search results by, e.g. 'C157225'. The value '*'
can also be used to return results that participate in at least one subset. This parameter is only meaningful
for <i>terminology=ncit</i>
schema:
type: string
requestBody:
description: SPARQL query that returns ?code identifying a valid code in the specified terminology. <a href='https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/SPARQL.md'
target='_blank'>See here for more information and examples of using SPARQL with EVSRESTAPI</a>.
content:
text/plain:
schema:
type: string
required: true
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
$ref: '#/components/schemas/ConceptResultList'
/api/v1/version:
get:
tags:
- Application version endpoint
summary: Get the application version information
operationId: getApplicationVersion
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationVersion'
/api/v1/subset/{terminology}:
get:
tags:
- Subset endpoints
summary: Get all subsets (or those specified by list parameter) for the specified terminology
operationId: getSubsets
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit'. This call is only meaningful for <i>ncit</i>.
required: true
schema:
type: string
example: ncit
- name: include
in: query
description: 'Indicator of how much data to return. Comma-separated list of any of the following values:
minimal, summary, full, associations, children, definitions, disjointWith, inverseAssociations, inverseRoles,
maps, parents, properties, roles, synonyms. <a href=''https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/INCLUDE.md''
target=''_blank''>See here for detailed information</a>.'
required: false
schema:
type: string
example: minimal
- name: list
in: query
description: List of codes or labels to return subsets for (or leave blank for all). If invalid values
are passed, the result will simply include no entries for those invalid values.
required: false
schema:
type: string
responses:
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Concept'
/api/v1/subset/{terminology}/{code}:
get:
tags:
- Subset endpoints
summary: Get the subset for the specified terminology and code.
operationId: getSubset
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit'.
required: true
schema:
type: string
example: ncit
- name: code
in: path
description: Subset code, e.g. 'C116978' for <i>ncit</i>. This call is only meaningful for <i>ncit</i>.
required: true
schema:
type: string
- name: include
in: query
description: 'Indicator of how much data tc return. Comma-separated list of any of the following values:
minimal, summary, full, associations, children, definitions, disjointWith, inverseAssociations, inverseRoles,
maps, parents, properties, roles, synonyms. <a href=''https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/INCLUDE.md''
target=''_blank''>See here for detailed information</a>.'
required: false
schema:
type: string
example: summary
responses:
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
$ref: '#/components/schemas/Concept'
/api/v1/subset/{terminology}/{code}/members:
get:
tags:
- Subset endpoints
summary: Get subset members for the specified terminology and code. Concept subset endpoints will be deprecated
in v2 in favor of top level subset endpoints.
operationId: getSubsetMembers
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit'
required: true
schema:
type: string
example: ncit
- name: fromRecord
in: query
description: Start index of the search results
required: false
schema:
type: integer
format: int32
example: 0
- name: pageSize
in: query
description: Max number of results to return
required: false
schema:
type: integer
format: int32
example: 10000
- name: code
in: path
description: Code for a subset concept in the specified terminology, e.g. 'C157225' for <i>ncit</i>. This
call is only meaningful for <i>ncit</i>.
required: true
schema:
type: string
- name: include
in: query
description: 'Indicator of how much data to return. Comma-separated list of any of the following values:
minimal, summary, full, associations, children, definitions, disjointWith, history, inverseAssociations,
inverseRoles, maps, parents, properties, roles, synonyms. <a href=''https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/INCLUDE.md''
target=''_blank''>See here for detailed information</a>.'
required: false
schema:
type: string
example: minimal
responses:
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Concept'
/api/v1/sparql/{terminology}/prefixes:
get:
tags:
- Search endpoint
summary: Get default prefixes used by SPARQL queries
operationId: getSparqlPrefixes
parameters:
- name: terminology
in: path
description: Single terminology to find prefixes for, e.g. 'ncit' or 'hgnc' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
type: string
/api/v1/metadata/{terminology}:
get:
tags:
- Metadata endpoints
summary: Get some metadata (associations, properties, qualifiers, roles, term types, sources, definition types,
synonym types) for the terminology overview tab in EVS-Explore
operationId: getOverviewMetadata
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
responses:
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/Concept'
/api/v1/metadata/{terminology}/welcomeText:
get:
tags:
- Metadata endpoints
summary: Get welcome text for the specified terminology
operationId: getWelcomeText
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
responses:
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
text/html:
schema:
type: string
/api/v1/metadata/{terminology}/termTypes:
get:
tags:
- Metadata endpoints
summary: Get all term types for the specified terminology
operationId: getTermTypes
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
responses:
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConceptMinimal'
/api/v1/metadata/{terminology}/synonymTypes:
get:
tags:
- Metadata endpoints
summary: Get all synonym types (or those specified by list parameter) for the specified terminology
operationId: getSynonymTypes
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here for complete list</a>)
required: true
schema:
type: string
example: ncit
- name: include
in: query
description: 'Indicator of how much data to return. Comma-separated list of any of the following values:
minimal, summary, full, associations, children, definitions, disjointWith, inverseAssociations, inverseRoles,
maps, parents, properties, roles, synonyms. <a href=''https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/INCLUDE.md''
target=''_blank''>See here for detailed information</a>.'
required: false
schema:
type: string
example: minimal
- name: list
in: query
description: List of codes or labels to return synonym types for (or leave blank for all). If invalid values
are passed, the result will simply include no entries for those invalid values.
required: false
schema:
type: string
responses:
'417':
description: Expectation failed
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestException'
'200':
description: Successfully retrieved the requested information
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Concept'
/api/v1/metadata/{terminology}/synonymType/{codeOrName}:
get:
tags:
- Metadata endpoints
summary: Get the synonym type for the specified terminology and code/name
operationId: getSynonymType
parameters:
- name: terminology
in: path
description: Terminology, e.g. 'ncit' or 'ncim' (<a href="https://github.com/NCIEVS/evsrestapi-client-SDK/blob/main/doc/TERMINOLOGIES.md">See
here fo
# --- truncated at 32 KB (156 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cancer-gov/refs/heads/main/openapi/cancer-gov-evs-openapi.yml