openapi: 3.0.1
info:
  title: ICD Foundation API
  description: "\n<p>\nICD-API is a REST API that allows programmatic access to the International Classification of Diseases (ICD).\n</p><p>\nFor most users that require accessing the ICD-11 statistical classification with codes, you need to use the <b>Linearization</b> endpoints with the linearizationId set to <b>mms</b>\n</p><p>\n<b>Foundation</b> endpoints provide information on the Foundation Component of ICD-11. \n</p><p>\n<b>ICD10</b> endpoints serves ICD-10 releases. Please note that functionality on the ICD-10 endpoints are limited. (i.e. the search is not provided)\n</p><p>\nFor more information on the API please see the <a href=\"https://icd.who.int/icdapi\">ICD-API home page </a>\n</p>\n"
  license:
    name: ' ICD-11 Terms of Use and License Agreement '
    url: https://icd.who.int/en/docs/icd11-license.pdf
  version: v2.6.0
security:
- oauth2:
  - icdapi_access
tags:
- name: Foundation
paths:
  /icd/entity:
    get:
      tags:
      - Foundation
      summary: This endpoint returns basic information on the latest release of the ICD-11 Foundation together with the top level Foundation entities.
      operationId: GetFoundation
      parameters:
      - name: releaseId
        in: query
        description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n            If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopLevelFoundation'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/TopLevelFoundation'
        '401':
          description: Unauthorized
  /icd/entity/{id}:
    get:
      tags:
      - Foundation
      summary: This endpoint provides you information on a specific ICD-11 foundation entity
      operationId: GetFoundationEntity
      parameters:
      - name: id
        in: path
        description: Numeric part at the end of the URI for an entity
        required: true
        schema:
          type: string
      - name: releaseId
        in: query
        description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n            If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
        schema:
          type: string
      - name: include
        in: query
        description: "Some property values such as ancestor and decendant lists are not provided in the response by default. However, it is possible\r\n            to request them. These properties are <i>ancestor, descendant and diagnosticCriteria.</i> For example, if you set include=ancestor the returned response will \r\n            include all ancestor entity URIs for the requested entity.\r\n            A comma separated list could be used to request multiple optional property values. e.g. include=ancestor,descendant"
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoundationEntity'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/FoundationEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/entity/autocode:
    get:
      tags:
      - Foundation
      summary: "Provides the best matching classification entity (its code and URI) for the provided diagnostic text. see AutoCodingSearchResult\r\nschema for information on the response."
      operationId: AutoCodeFoundation
      parameters:
      - name: searchText
        in: query
        description: Input text for which the matching entity to be provided
        schema:
          type: string
      - name: releaseId
        in: query
        description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        schema:
          type: string
      - name: subtreesFilter
        in: query
        description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
        schema:
          type: string
      - name: matchThreshold
        in: query
        description: score is a value between 0 and 1 that indicates the similarity between the input text and the matched term. matchThreshold the minimum score to be included in the output. The API will use default value if not provided
        schema:
          type: number
          format: double
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoCodingSearchResult'
        '401':
          description: Unauthorized
  /icd/entity/search:
    get:
      tags:
      - Foundation
      summary: "This endpoint is for searching the foundation component of the ICD-11. The search can be customized using the parameters as described. Search endpoint accepts both GET and POST requests. If the size of the request is too large, you may need to use POST\r\nas HTTP GET has a size limit of 2K"
      operationId: SearchFoundation
      parameters:
      - name: q
        in: query
        description: Text to be searched. Having the character % at the end will be regarded as a wild card for that word
        schema:
          type: string
      - name: subtreesFilter
        in: query
        description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
        schema:
          type: string
      - name: chapterFilter
        in: query
        description: Optional, comma or semicolon separated list of chapter codes eg:01;02;21 When provided, the search will be performed only on these chapters
        schema:
          type: string
      - name: useFlexisearch
        in: query
        description: "Changes the search mode to flexible search.\r\n            - In the regular search mode, the Coding Tool will only give you results that contain all of the words that you've used in your search. It accepts different variants or \r\n            synonyms of the words but essentially it searches for a result that contains all components of your search. Whereas in flexible search mode, the results do not have to \r\n            contain all of the words that are typed. It would still try to find the best matching phrase but there may be words in your search that are not matched at all\r\n            - It is recommended to use flexible search only when regular search does not provide a result"
        schema:
          type: boolean
          default: false
      - name: flatResults
        in: query
        description: "Optional parameter. Default value false. If set to true the search result entities are provided in a nested data structure\r\n            representing the ICD-11 hierarchy. Otherwise they are listed as flat list of matches"
        schema:
          type: boolean
          default: true
      - name: propertiesToBeSearched
        in: query
        description: "The properties to be searched. By default the system searches, Title, Synonyms and FullySpecifiedName.\r\n            The valid values that could be used are: \"Title\", \"Synonym\", \"NarrowerTerm\", \"FullySpecifiedName\", \"Definition\" and \"Exclusion\"\r\n            More than one property could be used with \",\" as the separator. In this case the results will include matches from any one of these properties"
        schema:
          type: string
      - name: releaseId
        in: query
        description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n            If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
        schema:
          type: string
      - name: highlightingEnabled
        in: query
        description: "Optional. Default is true, if set to false the search result highlighting is turned off\r\n            and the results don't contain special tags for highlighting where the results are found within the text"
        schema:
          type: boolean
          default: true
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ISearchResult'
        '401':
          description: Unauthorized
    post:
      tags:
      - Foundation
      summary: "This endpoint is for searching the foundation component of the ICD-11. The search can be customized using the parameters as described. Search endpoint accepts both GET and POST requests. If the size of the request is too large, you may need to use POST\r\nas HTTP GET has a size limit of 2K"
      operationId: SearchFoundation
      parameters:
      - name: q
        in: query
        description: Text to be searched. Having the character % at the end will be regarded as a wild card for that word
        schema:
          type: string
      - name: subtreesFilter
        in: query
        description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
        schema:
          type: string
      - name: chapterFilter
        in: query
        description: Optional, comma or semicolon separated list of chapter codes eg:01;02;21 When provided, the search will be performed only on these chapters
        schema:
          type: string
      - name: useFlexisearch
        in: query
        description: "Changes the search mode to flexible search.\r\n            - In the regular search mode, the Coding Tool will only give you results that contain all of the words that you've used in your search. It accepts different variants or \r\n            synonyms of the words but essentially it searches for a result that contains all components of your search. Whereas in flexible search mode, the results do not have to \r\n            contain all of the words that are typed. It would still try to find the best matching phrase but there may be words in your search that are not matched at all\r\n            - It is recommended to use flexible search only when regular search does not provide a result"
        schema:
          type: boolean
          default: false
      - name: flatResults
        in: query
        description: "Optional parameter. Default value false. If set to true the search result entities are provided in a nested data structure\r\n            representing the ICD-11 hierarchy. Otherwise they are listed as flat list of matches"
        schema:
          type: boolean
          default: true
      - name: propertiesToBeSearched
        in: query
        description: "The properties to be searched. By default the system searches, Title, Synonyms and FullySpecifiedName.\r\n            The valid values that could be used are: \"Title\", \"Synonym\", \"NarrowerTerm\", \"FullySpecifiedName\", \"Definition\" and \"Exclusion\"\r\n            More than one property could be used with \",\" as the separator. In this case the results will include matches from any one of these properties"
        schema:
          type: string
      - name: releaseId
        in: query
        description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n            If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
        schema:
          type: string
      - name: highlightingEnabled
        in: query
        description: "Optional. Default is true, if set to false the search result highlighting is turned off\r\n            and the results don't contain special tags for highlighting where the results are found within the text"
        schema:
          type: boolean
          default: true
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ISearchResult'
        '401':
          description: Unauthorized
components:
  schemas:
    AutoCodingSearchResult:
      type: object
      properties:
        searchText:
          type: string
          description: Text that is searched
          nullable: true
        matchingText:
          type: string
          description: The best matching phrase found in the classification
          nullable: true
        theCode:
          type: string
          description: Code of the best matching entity found in the classification
          nullable: true
        foundationURI:
          type: string
          description: Foundation URI of the best matching entity found in the classification
          nullable: true
        linearizationURI:
          type: string
          description: Linearization URI of the best matching entity found in the classification
          nullable: true
        matchLevel:
          $ref: '#/components/schemas/MatchLevelEnum'
        matchScore:
          type: number
          description: Shows the score of the match. The score is a value between 0 and 1. The higher the score the better the match.
          format: double
        matchType:
          $ref: '#/components/schemas/PropertyValueTypeEnum'
        isTitle:
          type: boolean
      additionalProperties: false
      description: Response object for autocode endpoint
    ISimpleEntity:
      type: object
      properties:
        id:
          type: string
          description: URI of the Entity
          nullable: true
        title:
          type: string
          description: "Title of the Entity. The matched part of the title has a special markup for highlighting. \r\nFor example when searched for the cholera the title Vibrio cholera will be like Vibrio <em class=\"found\">cholera</em>"
          nullable: true
        stemId:
          type: string
          description: "If the search result is composed of multiple URIs (i.e. postcoordinated result), Stem Id contains the URI of the stem code\r\nThis field contains the same information as Id in foundation search results"
          nullable: true
        isLeaf:
          type: boolean
          description: Shows whether the entity is a leaf node (i.e. does not have any children)
        postcoordinationAvailability:
          $ref: '#/components/schemas/PostcoordinationAvailabilityEnum'
        hasCodingNote:
          type: boolean
          description: Shows whether there is a coding note attached to the item
        hasMaternalChapterLink:
          type: boolean
          description: Shows whether the entity has maternal chapter link
        hasPerinatalChapterLink:
          type: boolean
        matchingPVs:
          type: array
          items:
            $ref: '#/components/schemas/ISimplePropertyValue'
          description: List of property values that match the search string
          nullable: true
          readOnly: true
        propertiesTruncated:
          type: boolean
          description: Shows if the list of matching property values is truncated as a result of too many maching property values
          readOnly: true
        isResidualOther:
          type: boolean
          description: Shows if this entity is an other specified residual category. (Not applicable for foundation search )
          readOnly: true
        isResidualUnspecified:
          type: boolean
          description: Shows if this entity is an unspecified residual category. (Not applicable for foundation search )
          readOnly: true
        chapter:
          type: string
          description: The chapter code for the entity
          nullable: true
          readOnly: true
        theCode:
          type: string
          description: The code for the entity (Not applicable for foundation )
          nullable: true
          readOnly: true
        score:
          type: number
          description: Shows how good is the search result. Higher numbers are better matches. There is no other meaning to this value than its relative value
          format: double
          readOnly: true
        titleIsASearchResult:
          type: boolean
          description: Shows whether the title of the entity is among the search results
          readOnly: true
        titleIsTopScore:
          type: boolean
          description: Shows whether the title is the top scored search result
          readOnly: true
        entityType:
          $ref: '#/components/schemas/EntityTypeEnum'
        important:
          type: boolean
          description: Identifies a very good match. The result matches all words from the search query.
          readOnly: true
        descendants:
          type: array
          items:
            $ref: '#/components/schemas/ISimpleEntity'
          description: Used when the search result is not represented as flat list but rather organized according to ICD hierarchy
          nullable: true
          readOnly: true
      additionalProperties: false
      description: SimpleEntity class represents a single ICD Entity in a search result
    ISimplePropertyValue:
      type: object
      properties:
        propertyId:
          type: string
          description: Id of the property
          nullable: true
          readOnly: true
        label:
          type: string
          description: "Label that matches the search query. The matched part of the label has a special markup for highlighting. \r\nFor example when searched for the cholera the Vibrio cholera will be like Vibrio <em class=\"found\">cholera</em>"
          nullable: true
          readOnly: true
        score:
          type: number
          description: Score of the match for this particular property value
          format: double
          readOnly: true
        important:
          type: boolean
          description: Identifies a very good match. The result matches all words from the search query.
          readOnly: true
        foundationUri:
          type: string
          description: "Only used when searching a linearization\r\nThe foundation URI in which the property value is located.\r\nThis is filled in only during a linearization search when this property value is coming from an under shoreline entity."
          nullable: true
        propertyValueType:
          $ref: '#/components/schemas/PropertyValueTypeEnum'
      additionalProperties: false
      description: Represents PropertyValues returned in the search result
    EntityTypeEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      description: "(0) Real: real entity in the linearization / foundation <br />\r\n(1) UnderShoreLineLogicallyDefined: Entity in the foundation that can be represented as a post-coordination combination in the linearization <br />\r\n(2) PostCoordinationCombination: does not exist in the foundation but can be represented as post-coordination combination"
      format: int32
    TopLevelFoundation:
      type: object
      properties:
        '@context':
          type: string
          description: JSON-LD Context for the endpoint
          nullable: true
        '@id':
          type: string
          description: unique id for the classification
          nullable: true
        title:
          $ref: '#/components/schemas/LanguageSpecificText'
        definition:
          $ref: '#/components/schemas/LanguageSpecificText'
        child:
          type: array
          items:
            type: string
          description: List of top level entities
          nullable: true
        releaseDate:
          type: string
          description: Release date
          nullable: true
        releaseId:
          type: string
          description: Release identifier for this particular release of the classification
          nullable: true
        browserUrl:
          type: string
          description: "ICD Browser is a web site that allows users see the ICD in its hierarchical structure at the same time providing search and post-coordination features.\r\nBrowser URL property provides a direct link to the classification in the WHO's on-line ICD Browser."
          nullable: true
        availableLanguages:
          type: array
          items:
            type: string
          description: All languages provided by the API including the one in pre-release state. All languages available in any of the linearizations are included in the list. For example, a language is listed in here even if it is only availabe in one of the linearizations (e.g. ICF)
          nullable: true
        supportedLinearizations:
          type: array
          items:
            type: string
          description: The linearizations from this foundation.
          nullable: true
        allReleases:
          type: array
          items:
            type: string
          description: Top level URIs for all releases available for the foundation. http://id.who.int/icd/entity is the current version and the others are earlier versions
          nullable: true
      additionalProperties: false
      description: Class representing top level for the foundation
    ISearchResult:
      type: object
      properties:
        destinationEntities:
          type: array
          items:
            $ref: '#/components/schemas/ISimpleEntity'
          description: List of entities that match the search query
          nullable: true
          readOnly: true
        error:
          type: boolean
          description: Returns true if an error is occurred during the search
          readOnly: true
        errorMessage:
          type: string
          description: Error message if there was an error
          nullable: true
          readOnly: true
        resultChopped:
          type: boolean
          description: If the search matches too many results, then the result is chopped
          readOnly: true
        wordSuggestionsChopped:
          type: boolean
          description: Shows if the word suggestion list is chopped as a result of too many matching words.
          readOnly: true
        guessType:
          $ref: '#/components/schemas/GuessTypeEnum'
        uniqueSearchId:
          type: string
          format: uuid
        words:
          type: array
          items:
            $ref: '#/components/schemas/GuessWord'
          description: List of word suggestions if the search had includeKeywordResult parameter set to true
          nullable: true
          readOnly: true
      additionalProperties: false
      description: Represents the search result. The search result is organized by ICD entities and in each entity we provide matching property values
    PropertyValueTypeEnum:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: "(0) Real:                                An index info from a linearization entity <br />\r\n(1) UnderShoreLine:                      An index entity from an entity under the shoreline<br />\r\n(2) UnderShoreLineLogicallyDefined:      An index entity from an entity under the shoreline \r\n                                                       and has a logical definition<br />\r\n(3) PostCoordinationCombination:         Virtual index entity created by following post-coordination\r\n                                                       combinations"
      format: int32
    FoundationEntity:
      type: object
      properties:
        title:
          $ref: '#/components/schemas/LanguageSpecificText'
        definition:
          $ref: '#/components/schemas/LanguageSpecificText'
        longDefinition:
          $ref: '#/components/schemas/LanguageSpecificText'
        fullySpecifiedName:
          $ref: '#/components/schemas/LanguageSpecificText'
        diagnosticCriteria:
          $ref: '#/components/schemas/LanguageSpecificText'
        child:
          type: array
          items:
            type: string
          description: List of URIs for the child entities
          nullable: true
        parent:
          type: array
          items:
            type: string
          description: List of URIs for the parent entities
          nullable: true
        ancestor:
          type: array
          items:
            type: string
          description: List of ancestors. Provided only with include=ancestor
          nullable: true
        descendant:
          type: array
          items:
            type: string
          description: List of descendants. Provided only with include=descendant
          nullable: true
        synonym:
          type: array
          items:
            $ref: '#/components/schemas/Term'
          description: List of synonyms for this entity
          nullable: true
        narrowerTerm:
          type: array
          items:
            $ref: '#/components/schemas/Term'
          description: List of narrower terms for this entity
          nullable: true
        inclusion:
          type: array
          items:
            $ref: '#/components/schemas/Term'
          description: List of inclusions for this entity
          nullable: true
        exclusion:
          type: array
          items:
            $ref: '#/components/schemas/Term'
          description: List of exclusions for this entity
          nullable: true
        browserUrl:
          type: string
          description: "ICD Browser is a web site that allows users see the ICD in its hierarchical structure at the same time providing search and post-coordination features.\r\nBrowser URL property provides a direct link to the classification in the WHO's on-line ICD Browser."
          nullable: true
      additionalProperties: false
      description: Class representing a foundation entity
    GuessTypeEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
    Term:
      type: object
      properties:
        label:
          $ref: '#/components/schemas/LanguageSpecificText'
        foundationReference:
          type: string
          description: "In some cases such as in exclusions or index terms, the term itself could be coming from another entity in the classification\r\nIn these cases foundationReference holds the foundation URI for that entity\r\nIndex terms generated from foundation entities that are not located in the linearization have this reference"
          nullable: true
        linearizationReference:
          type: string
          description: "In some cases such as in exclusions or index terms, the term itself could be coming from another entity in the classification\r\nIn these cases linearizationReference holds the linearization (or release) URI for that entity"
          nullable: true
        deprecated:
          type: boolean
          description: If the term has been deprecated, this flag is set to true
      additionalProperties: false
      description: Class representing a term with language specific label and optional cross references
    MatchLevelEnum:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      format: int32
    GuessWord:
      type: object
      properties:
        label:
          type: string
          nullable: true
        dontChangeResult:
          type: boolean
      additionalProperties: false
      description: Represents a keyword returned as a as a word completion suggestion or as a next word suggestion
    LanguageSpecificText:
      type: object
      properties:
        '@language':
          type: string
          description: Language code for the string
          nullable: true
        '@value':
          type: string
          description: Label in the given language
          nullable: true
      additionalProperties: false
      description: Language specific text as used in JSON-LD
    PostcoordinationAvailabilityEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://icdaccessmanagement.who.int/connect/token
          scopes:
            icdapi_access: ''