World Health Organization (WHO) Foundation API

openapi: 3.2.0
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
servers:
- url: https://ghoapi.azureedge.net/api
  description: Base URL declared by the provider in apis.yml (roadmap#122).
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.\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.\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\n            to request them. These properties are <i>ancestor, descendant and diagnosticCriteria.</i> For example, if you set include=ancestor the returned response will \n            include all ancestor entity URIs for the requested entity.\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

        schema 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

        as 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.\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 \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 \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\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\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.\n            The valid values that could be used are: \"Title\", \"Synonym\", \"NarrowerTerm\", \"FullySpecifiedName\", \"Definition\" and \"Exclusion\"\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.\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\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

        as 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.\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 \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 \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\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\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.\n            The valid values that could be used are: \"Title\", \"Synonym\", \"NarrowerTerm\", \"FullySpecifiedName\", \"Definition\" and \"Exclusion\"\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.\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\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:
    GuessWord:
      type: object
      properties:
        label:
          type:
          - string
          - 'null'
        dontChangeResult:
          type: boolean
      additionalProperties: false
      description: Represents a keyword returned as a as a word completion suggestion or as a next word suggestion
    MatchLevelEnum:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      format: int32
    PostcoordinationAvailabilityEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
    ISearchResult:
      type: object
      properties:
        destinationEntities:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ISimpleEntity'
          description: List of entities that match the search query
          readOnly: true
        error:
          type: boolean
          description: Returns true if an error is occurred during the search
          readOnly: true
        errorMessage:
          type:
          - string
          - 'null'
          description: Error message if there was an error
          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
          - 'null'
          items:
            $ref: '#/components/schemas/GuessWord'
          description: List of word suggestions if the search had includeKeywordResult parameter set to 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
    Term:
      type: object
      properties:
        label:
          $ref: '#/components/schemas/LanguageSpecificText'
        foundationReference:
          type:
          - string
          - 'null'
          description: 'In some cases such as in exclusions or index terms, the term itself could be coming from another entity in the classification

            In these cases foundationReference holds the foundation URI for that entity

            Index terms generated from foundation entities that are not located in the linearization have this reference'
        linearizationReference:
          type:
          - string
          - 'null'
          description: 'In some cases such as in exclusions or index terms, the term itself could be coming from another entity in the classification

            In these cases linearizationReference holds the linearization (or release) URI for that entity'
        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
    TopLevelFoundation:
      type: object
      properties:
        '@context':
          type:
          - string
          - 'null'
          description: JSON-LD Context for the endpoint
        '@id':
          type:
          - string
          - 'null'
          description: unique id for the classification
        title:
          $ref: '#/components/schemas/LanguageSpecificText'
        definition:
          $ref: '#/components/schemas/LanguageSpecificText'
        child:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of top level entities
        releaseDate:
          type:
          - string
          - 'null'
          description: Release date
        releaseId:
          type:
          - string
          - 'null'
          description: Release identifier for this particular release of the classification
        browserUrl:
          type:
          - string
          - 'null'
          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.

            Browser URL property provides a direct link to the classification in the WHO''s on-line ICD Browser.'
        availableLanguages:
          type:
          - array
          - 'null'
          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)
        supportedLinearizations:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The linearizations from this foundation.
        allReleases:
          type:
          - array
          - 'null'
          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
      additionalProperties: false
      description: Class representing top level for the foundation
    GuessTypeEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
    LanguageSpecificText:
      type: object
      properties:
        '@language':
          type:
          - string
          - 'null'
          description: Language code for the string
        '@value':
          type:
          - string
          - 'null'
          description: Label in the given language
      additionalProperties: false
      description: Language specific text as used in JSON-LD
    EntityTypeEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      description: '(0) Real: real entity in the linearization / foundation <br />

        (1) UnderShoreLineLogicallyDefined: Entity in the foundation that can be represented as a post-coordination combination in the linearization <br />

        (2) PostCoordinationCombination: does not exist in the foundation but can be represented as post-coordination combination'
      format: int32
    AutoCodingSearchResult:
      type: object
      properties:
        searchText:
          type:
          - string
          - 'null'
          description: Text that is searched
        matchingText:
          type:
          - string
          - 'null'
          description: The best matching phrase found in the classification
        theCode:
          type:
          - string
          - 'null'
          description: Code of the best matching entity found in the classification
        foundationURI:
          type:
          - string
          - 'null'
          description: Foundation URI of the best matching entity found in the classification
        linearizationURI:
          type:
          - string
          - 'null'
          description: Linearization URI of the best matching entity found in the classification
        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
    ISimplePropertyValue:
      type: object
      properties:
        propertyId:
          type:
          - string
          - 'null'
          description: Id of the property
          readOnly: true
        label:
          type:
          - string
          - 'null'
          description: "Label that matches the search query. The matched part of the label has a special markup for highlighting. \nFor example when searched for the cholera the Vibrio cholera will be like Vibrio <em class=\"found\">cholera</em>"
          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
          - 'null'
          description: 'Only used when searching a linearization

            The foundation URI in which the property value is located.

            This is filled in only during a linearization search when this property value is coming from an under shoreline entity.'
        propertyValueType:
          $ref: '#/components/schemas/PropertyValueTypeEnum'
      additionalProperties: false
      description: Represents PropertyValues returned in the search result
    PropertyValueTypeEnum:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: "(0) Real:                                An index info from a linearization entity <br />\n(1) UnderShoreLine:                      An index entity from an entity under the shoreline<br />\n(2) UnderShoreLineLogicallyDefined:      An index entity from an entity under the shoreline \n                                                       and has a logical definition<br />\n(3) PostCoordinationCombination:         Virtual index entity created by following post-coordination\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
          - 'null'
          items:
            type: string
          description: List of URIs for the child entities
        parent:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of URIs for the parent entities
        ancestor:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of ancestors. Provided only with include=ancestor
        descendant:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of descendants. Provided only with include=descendant
        synonym:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Term'
          description: List of synonyms for this entity
        narrowerTerm:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Term'
          description: List of narrower terms for this entity
        inclusion:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Term'
          description: List of inclusions for this entity
        exclusion:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Term'
          description: List of exclusions for this entity
        browserUrl:
          type:
          - string
          - 'null'
          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.

            Browser URL property provides a direct link to the classification in the WHO''s on-line ICD Browser.'
      additionalProperties: false
      description: Class representing a foundation entity
    ISimpleEntity:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: URI of the Entity
        title:
          type:
          - string
          - 'null'
          description: "Title of the Entity. The matched part of the title has a special markup for highlighting. \nFor example when searched for the cholera the title Vibrio cholera will be like Vibrio <em class=\"found\">cholera</em>"
        stemId:
          type:
          - string
          - 'null'
          description: 'If the search result is composed of multiple URIs (i.e. postcoordinated result), Stem Id contains the URI of the stem code

            This field contains the same information as Id in foundation search results'
        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
          - 'null'
          items:
            $ref: '#/components/schemas/ISimplePropertyValue'
          description: List of property values that match the search string
          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
          - 'null'
          description: The chapter code for the entity
          readOnly: true
        theCode:
          type:
          - string
          - 'null'
          description: The code for the entity (Not applicable for foundation )
          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
          - 'null'
          items:
            $ref: '#/components/schemas/ISimpleEntity'
          description: Used when the search result is not represented as flat list but rather organized according to ICD hierarchy
          readOnly: true
      additionalProperties: false
      description: SimpleEntity class represents a single ICD Entity in a search result
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://icdaccessmanagement.who.int/connect/token
          scopes:
            ic

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/who/refs/heads/main/openapi/who-foundation-api-openapi.yml