openapi: 3.2.0
info:
  title: NCI EVS Rest Subset endpoints 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 Github evsrestapi-client-SDK project.
  termsOfService: https://evs.nci.nih.gov/ftp1/NCI_Thesaurus/ThesaurusTermsofUse.htm
  contact:
    name: NCI EVS
    email: NCIAppSupport@nih.gov
  version: 2.4.1.RELEASE
servers:
- url: /
tags:
- name: Subset endpoints
paths:
  /api/v1/subset/{terminology}:
    get:
      tags:
      - Subset endpoints
      summary: Get all subsets (or those specified by list parameter) for the specified…
      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.
      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'
components:
  schemas:
    Definition:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        definition:
          type: string
          description: Text definition value
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        code:
          type: string
          description: Definition code
        type:
          type: string
          description: Definition type
        source:
          type: string
          description: Definition source
        qualifiers:
          type: array
          description: Type/value qualifiers on the definition
          items:
            $ref: '#/components/schemas/Qualifier'
      description: Represents a text definition for a concept
    DisjointWith:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Relationship code
        type:
          type: string
          description: Relationship type
        relatedCode:
          type: string
          description: Related code (the code on the other side of the relationship)
        relatedName:
          type: string
          description: Preferred name of the related code
        source:
          type: string
          description: Relationship source
        group:
          type: string
          description: Role group number for grouping related roles
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        qualifiers:
          type: array
          description: Type/value qualifiers on the relationship
          items:
            $ref: '#/components/schemas/Qualifier'
      description: Represents an assertion of disjointness between two concepts
    Mapping:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        mapsetCode:
          type: string
        source:
          type: string
          description: Terminology of the source code, e.g. 'ncit'
        sourceName:
          type: string
          description: Preferred name of the source code
        sourceTermType:
          type: string
          description: Term type of the source code
        sourceCode:
          type: string
          description: Source code of the map (the thing being mapped 'from')
        sourceTerminology:
          type: string
          description: Human-readable label for the terminology of the source code, e.g. 'NCI Thesaurus'
        sourceTerminologyVersion:
          type: string
          description: Terminology version of the source code
        sourceLoaded:
          type: boolean
          description: Indicates whether the source code terminology/version is currently loaded
        type:
          type: string
        rank:
          type: string
        group:
          type: string
        rule:
          type: string
        target:
          type: string
          description: Terminology of the target code, e.g. 'ncit'
        targetName:
          type: string
        targetTermType:
          type: string
        targetCode:
          type: string
          description: Target code of the map (the thing being mapped 'to')
        targetTerminology:
          type: string
          description: Human-readable label for the terminology of the target code, e.g. 'NCI Thesaurus'
        targetTerminologyVersion:
          type: string
          description: Terminology version of the target code
        targetLoaded:
          type: boolean
          description: Indicates whether the target terminology/version is currently loaded
        sortKey:
          type: string
        targetTermGroup:
          type: string
          writeOnly: true
      description: Represents a map from a concept to concepts in other terminologies
    Role:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Relationship code
        type:
          type: string
          description: Relationship type
        relatedCode:
          type: string
          description: Related code (the code on the other side of the relationship)
        relatedName:
          type: string
          description: Preferred name of the related code
        source:
          type: string
          description: Relationship source
        group:
          type: string
          description: Role group number for grouping related roles
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        qualifiers:
          type: array
          description: Type/value qualifiers on the relationship
          items:
            $ref: '#/components/schemas/Qualifier'
      description: Represents a (logically) defining relationship between two concepts
    Synonym:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        name:
          type: string
          description: Name for a concept
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        termType:
          type: string
          description: Synonym term type
        type:
          type: string
          description: Synonym type
        typeCode:
          type: string
          description: Synonym Type code
        source:
          type: string
          description: Synonym source
        code:
          type: string
          description: Code of the synonym, used in particular for Metathesaurus data where the source of the synonym is not the terminology itself
        subSource:
          type: string
          description: Synonym sub-source
        qualifiers:
          type: array
          description: Type/value qualifiers on the synonym
          items:
            $ref: '#/components/schemas/Qualifier'
        active:
          type: boolean
          description: Indicates whether the synonym is active
      description: Represents one of the (potentially many) names for a concept
    ConceptMinimal:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Code (unique identifier) for this meaning
        name:
          type: string
          description: Preferred name for the code
        terminology:
          type: string
          description: Terminology abbreviation, e.g. 'nci'
        version:
          type: string
          description: Terminology version, e.g. '23.11d'
        level:
          type: integer
          description: Level of depth in a hierarchy (when this object is used to represent an element in a path)
          format: int32
      description: Represents minimal information about a concept in a terminology
    History:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Code for this history record
        name:
          type: string
          description: Last known preferred name for the code
        action:
          type: string
          description: Indicates the history action, e.g. 'merge', 'active', 'retire', 'SY', 'RB', etc.
        date:
          type: string
          description: Date of the history record
        replacementCode:
          type: string
          description: Code replacing this code
        replacementName:
          type: string
          description: Preferred name of the code replacing this code
      description: Represents a history record, generally for a retired concept
    Property:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
        type:
          type: string
          description: Property type
        value:
          type: string
          description: Property value
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        qualifiers:
          type: array
          description: Type/value qualifiers on the property
          items:
            $ref: '#/components/schemas/Qualifier'
        source:
          type: string
          description: Property source
      description: Represents a type/value property on a concept
    RestException:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          format: int32
        error:
          type: string
        message:
          type: string
        path:
          type: string
      description: Payload for JSON error responses
    Path:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        direction:
          type: integer
          description: Direction of the map (1 means node-to-root, -1 means root-to-node)
          format: int32
        concepts:
          type: array
          description: Concepts on the path
          items:
            $ref: '#/components/schemas/ConceptMinimal'
      description: Represents a path (or partial path) in a hierarchy
    Paths:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        paths:
          type: array
          description: List of paths
          items:
            $ref: '#/components/schemas/Path'
      description: Represents a list of paths
    Extensions:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        isDisease:
          type: boolean
        isDiseaseGrade:
          type: boolean
        isDiseaseStage:
          type: boolean
        isMainType:
          type: boolean
        isSubtype:
          type: boolean
        isBiomarker:
          type: boolean
        isReferenceGene:
          type: boolean
        mainMenuAncestors:
          type: array
          items:
            $ref: '#/components/schemas/Paths'
      description: Generally unset, this is used for certain special cases
    Qualifier:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Qualifier code
        type:
          type: string
          description: Qualifier type
        value:
          type: string
          description: Qualifier value
      description: Represents a type/value qualifier on a concept element
    Association:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Relationship code
        type:
          type: string
          description: Relationship type
        relatedCode:
          type: string
          description: Related code (the code on the other side of the relationship)
        relatedName:
          type: string
          description: Preferred name of the related code
        source:
          type: string
          description: Relationship source
        group:
          type: string
          description: Role group number for grouping related roles
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        qualifiers:
          type: array
          description: Type/value qualifiers on the relationship
          items:
            $ref: '#/components/schemas/Qualifier'
      description: Represents a non-defining (in a logical sense) relationship between two concepts
    Concept:
      type: object
      properties:
        uri:
          type: string
          description: URI for this element in an rdf-based source file
        ct:
          type: integer
          description: Used to indicate the total amount of data in cases where a limit is being applied
          format: int32
        code:
          type: string
          description: Code (unique identifier) for this meaning
        name:
          type: string
          description: Preferred name for the code
        terminology:
          type: string
          description: Terminology abbreviation, e.g. 'nci'
        version:
          type: string
          description: Terminology version, e.g. '23.11d'
        level:
          type: integer
          description: Level of depth in a hierarchy (when this object is used to represent an element in a path)
          format: int32
        highlight:
          type: string
          description: Used by search calls to provide information for highlighting a view of results
        subsetLink:
          type: string
          description: Link to download data for a subset, used when the concept represents subset metadata
        mapsetLink:
          type: string
          description: Metadata for downloading a mapset
        conceptStatus:
          type: string
          description: Status value for the concept, e.g. Retired_Concept
        source:
          type: string
          description: Associations from this concept to other ones
        leaf:
          type: boolean
          description: Indicates whether concept is a leaf node
        active:
          type: boolean
          description: Indicates whether the concept is active
        defining:
          type: boolean
          description: Indicates whether the concept is defining
        synonyms:
          type: array
          description: Synonyms, or all of the names for this concept, including the preferred name
          items:
            $ref: '#/components/schemas/Synonym'
        definitions:
          type: array
          description: Text definitions
          items:
            $ref: '#/components/schemas/Definition'
        properties:
          type: array
          description: Key/value properties
          items:
            $ref: '#/components/schemas/Property'
        children:
          type: array
          description: Child concepts in the hierarchy
          items:
            $ref: '#/components/schemas/Concept'
        parents:
          type: array
          description: Parent concepts in the hierarchy
          items:
            $ref: '#/components/schemas/Concept'
        descendants:
          type: array
          description: Descendant concepts in the hierarchy
          items:
            $ref: '#/components/schemas/Concept'
        qualifiers:
          type: array
          description: Qualifiers for use when a concept is used as a parent/child - to indicate RELA for NCIm-derived content
          items:
            $ref: '#/components/schemas/Qualifier'
        associations:
          type: array
          description: Associations from this concept to other ones
          items:
            $ref: '#/components/schemas/Association'
        inverseAssociations:
          type: array
          description: Associations to this concept from other ones
          items:
            $ref: '#/components/schemas/Association'
        roles:
          type: array
          description: Roles from this concept to other ones
          items:
            $ref: '#/components/schemas/Role'
        disjointWith:
          type: array
          description: Assertions of disjointness with respect to other concepts
          items:
            $ref: '#/components/schemas/DisjointWith'
        inverseRoles:
          type: array
          description: Roles to this concept from other ones
          items:
            $ref: '#/components/schemas/Role'
        history:
          type: array
          description: History records
          items:
            $ref: '#/components/schemas/History'
        maps:
          type: array
          description: Maps from this concept to concepts in other terminologies
          items:
            $ref: '#/components/schemas/Mapping'
        paths:
          $ref: '#/components/schemas/Paths'
        extensions:
          $ref: '#/components/schemas/Extensions'
      description: Represents a concept in a terminology