swagger: '2.0'
info:
  title: Phenotype Library API
  version: v1
host: conceptlibrary.saildatabank.com
schemes:
- https
basePath: /HDRUK/api/v1/swagger.yaml/
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Basic:
    type: basic
security:
- Basic: []
paths:
  /collections/:
    get:
      operationId: collections_list
      summary: Get all Collections
      description: |-
        Available parameters:

        | Param         | Type            | Default | Desc                                                          |
        |---------------|-----------------|---------|---------------------------------------------------------------|
        | search        | `str`           | `NULL`  | Full-text search across _name_ field                   |
        | id            | `int/list[int]` | `NULL`  | Match by a single `int` _id_ field, or match by array overlap |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - collections
    parameters: []
  /collections/{collection_id}/detail/:
    get:
      operationId: collections_detail_list
      description: |-
        Get detail of specified collection by collection_id, including associated
          published entities
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - collections
    parameters:
    - name: collection_id
      in: path
      required: true
      type: string
  /concepts/:
    get:
      operationId: concepts_list
      summary: Get all Concepts accessible to the user, optionally provide parameters
        to filter the resultset.
      description: |-
        Available API parameters can be derived from the [Reference Data](/reference-data/) page, _e.g._ in the case of `tag` or `collection` ID identifiers.

        Endpoint query parameters:

        | Param           | Type                        | Default            | Desc                                                                                                                          |
        |-----------------|-----------------------------|--------------------|-------------------------------------------------------------------------------------------------------------------------------|
        | search          | `str`                       | `NULL`             | Full-text search across Concept `name` and `description` fields (trigram, fuzzy)                                              |
        | page            | `number`                    | `1`                | Page cursor                                                                                                                   |
        | page_size       | `enum`/`int`                | `1` (_20_ results) | Page size enum, where `1` = 20, `2` = 50 & `3` = 100 rows                                                                     |
        | no_pagination   | `[empty]`                   | `NULL`             | You can append this parameter to your query to disable pagination                                                             |
        | phenotype_id    | `str`/`str[]`               | `NULL`             | Either (a) a Phenotype ID or (b) a list of comma-delimited Phenotype IDs                                                      |
        | phenotype_owner | `str`/`str[]`               | `NULL`             | An alias of the `phenotype_id` parameter; see `phenotype_id` above                                                            |
        | tags            | `int`/`int[]`               | `NULL`             | Either (a) a Tag ID or (b) a list of comma-delimited Tag IDs                                                                  |
        | collections     | `int`/`int[]`               | `NULL`             | Either (a) a Collection ID or (b) a list of comma-delimited Collection IDs                                                    |
        | coding_system   | `int`/`int[]`               | `NULL`             | Either (a) a Coding System ID or (b) a list of comma-delimited Coding System IDs                                              |
        | owner           | `int`/`str`/`str[]`/`int[]` | `NULL`             | A reference to the Owner ID/Name, either (a) a Name `str` / ID `int` or (b) a comma-delimited list of either type             |
        | organisation    | `int`/`str`/`str[]`/`int[]` | `NULL`             | A reference to the Organisation ID/Name, either (a) a Slug/Name `str` / ID `int` or (b) a comma-delimited list of either type |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters: []
  /concepts/C{concept_id}/detail/:
    get:
      operationId: concepts_detail_list
      description: Get the detail of specified Concept by `concept_id`, optionally
        target a specific version using the `version_id` endpoints, and/or export
        the Concept codelist/components.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
  /concepts/C{concept_id}/export/codes/:
    get:
      operationId: concepts_export_codes_list
      description: Get the detail of specified Concept by `concept_id`, optionally
        target a specific version using the `version_id` endpoints, and/or export
        the Concept codelist/components.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
  /concepts/C{concept_id}/export/component-data/:
    get:
      operationId: concepts_export_component-data_list
      description: Get the detail of specified Concept by `concept_id`, optionally
        target a specific version using the `version_id` endpoints, and/or export
        the Concept codelist/components.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
  /concepts/C{concept_id}/get-versions/:
    get:
      operationId: concepts_get-versions_list
      description: Get version history of a specific Concept, using `concept_id`
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
  /concepts/C{concept_id}/version/{version_id}/detail/:
    get:
      operationId: concepts_version_detail_list
      description: Get the detail of specified Concept by `concept_id`, optionally
        target a specific version using the `version_id` endpoints, and/or export
        the Concept codelist/components.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
    - name: version_id
      in: path
      required: true
      type: string
  /concepts/C{concept_id}/version/{version_id}/export/codes/:
    get:
      operationId: concepts_version_export_codes_list
      description: Get the detail of specified Concept by `concept_id`, optionally
        target a specific version using the `version_id` endpoints, and/or export
        the Concept codelist/components.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
    - name: version_id
      in: path
      required: true
      type: string
  /concepts/C{concept_id}/version/{version_id}/export/component-data/:
    get:
      operationId: concepts_version_export_component-data_list
      description: Get the detail of specified Concept by `concept_id`, optionally
        target a specific version using the `version_id` endpoints, and/or export
        the Concept codelist/components.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - concepts
    parameters:
    - name: concept_id
      in: path
      required: true
      type: string
    - name: version_id
      in: path
      required: true
      type: string
  /data-sources/:
    get:
      operationId: data-sources_list
      summary: Get all DataSources
      description: |-
        Available parameters:

        | Param         | Type            | Default | Desc                                                          |
        |---------------|-----------------|---------|---------------------------------------------------------------|
        | search        | `str`           | `NULL`  | Full-text search across _name_ and _description_ fields       |
        | id            | `int/list[int]` | `NULL`  | Match by a single `int` _id_ field, or match by array overlap |
        | name          | `str`           | `NULL`  | Case insensitive direct match of _name_ field                 |
        | uid           | `str/uuid`      | `NULL`  | Case insensitive direct match of _uid_ field                  |
        | datasource_id | `int`           | `NULL`  | Match by exact _datasource_id_ (HDRUK ID)                     |
        | url           | `str`           | `NULL`  | Case insensitive direct match of _url_ field                  |
        | source        | `str`           | `NULL`  | Case insensitive direct match of _source_ field               |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - data-sources
    parameters: []
  /data-sources/{datasource_id}/detail/:
    get:
      operationId: data-sources_detail_list
      description: Get detail of specified datasource by its internal `id` or its
        `UUID` for linkage between applications (see HDRUK HealthDataGateway), including
        associated published entities.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - data-sources
    parameters:
    - name: datasource_id
      in: path
      required: true
      type: string
  /data-sources/{datasource_id}/export/:
    get:
      operationId: data-sources_export_list
      description: Get detail of specified datasource by by its internal `id`
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - data-sources
    parameters:
    - name: datasource_id
      in: path
      required: true
      type: string
  /ontology/:
    get:
      operationId: ontology_list
      description: Get all ontology groups and their root nodes, _incl._ associated
        data such as the rood nodes, children _etc_
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - ontology
    parameters: []
  /ontology/node/:
    get:
      operationId: ontology_node_list
      summary: Queries Ontology nodes by the given request parameters, returning a
        `QuerySet` of all matched node(s).
      description: |-
        Available API parameters can be derived from the [Reference Data](/reference-data/) page, _e.g._ in the case of `codes` Code identifiers (Code ID).

        Endpoint query parameters:

        | Param         | Type     | Default            | Desc                                                                    |
        |:--------------|:---------|:-------------------|:------------------------------------------------------------------------|
        | search        | `string` | `NULL`             | Full-text search                                                        |
        | codes         | `list`   | `NULL`             | e.g. `MONDO:0004995`, `MESH:D002309`, or xrefs like `ICD10CM:I21`       |
        | exact_codes   | `empty`  | `NULL`             | Apply this parameter if you would like to search for exact codes instead of fuzzy matching the given `codes` across all related mappings (ICD-9/10, MeSH, OPSC4, ReadCodes etc) |
        | type_ids      | `list`   | `NULL`             | Filter ontology type by ID                                              |
        | reference_ids | `list`   | `NULL`             | Filter ontology by its vocabulary reference ID, e.g. `MONDO:0005068,MONDO:0004781`    |
        | page          | `number` | `1`                | Page cursor                                                             |
        | page_size     | `enum`   | `1` (_20_ results) | Page size enum, where: `1` = 20, `2` = 50 & `3` = 100 rows              |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - ontology
    parameters: []
  /ontology/node/{node_id}/:
    get:
      operationId: ontology_node_read
      description: Gets an Ontology node by the specified `node_id`
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - ontology
    parameters:
    - name: node_id
      in: path
      required: true
      type: string
  /ontology/node/{term}/:
    get:
      operationId: ontology_node_read
      summary: Gets an Ontology node by the specified `term`, _i.e._ its `reference_id`.
      description: |-
        The `reference_id` field of terms found within MONDO, MeSH and Clinical Specialty vocabularies are defined
        such that they are prefixed with the ontological name, thus, one can query by `term` in the following manner:

        | Ontology           | Concept                     | Term              | Request                         |
        |:-------------------|:----------------------------|:------------------|:--------------------------------|
        | MONDO              | "_Cardiovascular disorder_" | `MONDO:0004995`   | `ontology/node/MONDO:0004995`   |
        | MeSH               | "_Cardiology_"              | `MESH:D002309`    | `ontology/node/MESH:D002309`    |
        | Clinical Specialty | "_Cardiology_"              | `SCTID:394579002` | `ontology/node/SCTID:394579002` |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - ontology
    parameters:
    - name: term
      in: path
      required: true
      type: string
  /ontology/type/{ontology_id}/:
    get:
      operationId: ontology_type_read
      description: Get specified ontology group type detail by the given `ontology_id`
        type, including associated data _e.g._ root nodes, children _etc_
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - ontology
    parameters:
    - name: ontology_id
      in: path
      required: true
      type: string
  /phenotypes/:
    get:
      operationId: phenotypes_list
      description: "Get all generic entities accessible to the API user; see [Reference
        Data](/reference-data/) page\nfor available API parameters for individual
        templates.\n\n- **Base Parameters** → _i.e._ Base search-related parameters\n\n
        \   | Param               | Type           | Default            | Desc                                                                   |\n
        \   |---------------------|----------------|--------------------|------------------------------------------------------------------------|\n
        \   | search              | `string`       | `NULL`             | Full-text
        search                                                       |\n    | template_id
        \        | `number`       | `NULL`             | Filter results by Template
        ID                                          |\n    | template_version_id |
        `number`       | `NULL`             | Filter results by Template Version (if
        `ID` applied)                   |\n    | page                | `number`       |
        `1`                | Page cursor                                                            |\n
        \   | page_size           | `enum/number`  | `1` (_20_ results) | Page size
        enum, where `1` = 20, `2` = 50 & `3` = 100 rows              |\n    | no_pagination
        \      | `empty`        | `NULL`             | you can append this parameter
        to your query to disable pagination      |\n\n- **Metadata Parameters** →
        _i.e._ Top-level fields associated with all `Phenotypes`\n\n    | Param       |
        Type               | Default | Desc                                                 |\n
        \   |-------------|--------------------|---------|------------------------------------------------------|\n
        \   | tags        | `list<int or str>` | `NULL`  | Filter results by one or
        more tag IDs / names        |\n    | collections | `list<int or str>` | `NULL`
        \ | Filter results by one or more collection IDs / names |\n    | created
        \    | `list<date>`       | `NULL`  | Date range filter on `created` field
        \                |\n\n- **Template Parameters** → _i.e._ Fields relating to
        a specific `Template`\n\n    - Parameters are variadic due to the nature of
        templates - please see the reference data and the associated Phenotype template
        documentation for querying field(s) relating to a specific template\n    -
        See reference data & associated parameters on the [Reference Data](/reference-data/)
        page\n\n- **Subquery parameters**\n    - Hierarchical fields, such as the
        `OntologyTag` field, now include modifiers - these can be applied by appending
        them to the subquery parameter\n    - Available modifiers for 'ontology' related
        parameter(s) include:\n\n        > **NOTE:**  \n        > You can append the
        `_descendants` parameter to any of the following subquery params to select
        across that particular\n        > node and its descendants, _e.g._ `/api/v1/phenotypes/ontology_code_descendants=48176007`\n
        \       >  \n\n        | Details                         | Parameter                     |
        Values                                                                             |\n
        \       |---------------------------------|-------------------------------|------------------------------------------------------------------------------------|\n
        \       | Search across ID, Name and Code | `?ontology=([^&]+)`           |
        Search string or List of deliminated strings                                       |\n
        \       | Search across ID                | `?ontology_id=([^&]+)`        |
        Single `ID` (`int`) or List of deliminated `ID`s                                   |\n
        \       | Search across Code              | `?ontology_code=([^&]+)`      |
        Single `Code` string (_e.g._ ICD-10, SNOMED _etc_) or List of deliminated
        `Codes`s |\n        | Search acrros Name              | `?ontology_name=([^&]+)`
        \     | Single `Name` string or List of deliminated `Name`s                                |\n
        \       | Search across Type              | `?ontology_type=([^&]+)`      |
        Single `Type` (`int` or `str`) or List of deliminated `Type` IDs/Names             |\n
        \       | Search across Reference         | `?ontology_reference=([^&]+)`
        | Single `ReferenceID` (`int`) or List of deliminated `ReferenceID`s                 |"
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - phenotypes
    parameters: []
  /phenotypes/{phenotype_id}/detail/:
    get:
      operationId: phenotypes_detail_list
      description: |-
        Get detail of specified entity by phenotype_id, optionally target a specific
          version using version_id and/or target a specific entity field using
          field parameters
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - phenotypes
    parameters:
    - name: phenotype_id
      in: path
      required: true
      type: string
  /phenotypes/{phenotype_id}/export/{field}/:
    get:
      operationId: phenotypes_export_read
      description: |-
        Get detail of specified entity by phenotype_id, optionally target a specific
          version using version_id and/or target a specific entity field using
          field parameters
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - phenotypes
    parameters:
    - name: phenotype_id
      in: path
      required: true
      type: string
    - name: field
      in: path
      required: true
      type: string
  /phenotypes/{phenotype_id}/get-versions/:
    get:
      operationId: phenotypes_get-versions_list
      description: Get version history of specific entity, using phenotype_id
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - phenotypes
    parameters:
    - name: phenotype_id
      in: path
      required: true
      type: string
  /phenotypes/{phenotype_id}/version/{version_id}/detail/:
    get:
      operationId: phenotypes_version_detail_list
      description: |-
        Get detail of specified entity by phenotype_id, optionally target a specific
          version using version_id and/or target a specific entity field using
          field parameters
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - phenotypes
    parameters:
    - name: phenotype_id
      in: path
      required: true
      type: string
    - name: version_id
      in: path
      required: true
      type: string
  /phenotypes/{phenotype_id}/version/{version_id}/export/{field}/:
    get:
      operationId: phenotypes_version_export_read
      description: |-
        Get detail of specified entity by phenotype_id, optionally target a specific
          version using version_id and/or target a specific entity field using
          field parameters
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - phenotypes
    parameters:
    - name: phenotype_id
      in: path
      required: true
      type: string
    - name: version_id
      in: path
      required: true
      type: string
    - name: field
      in: path
      required: true
      type: string
  /tags/:
    get:
      operationId: tags_list
      summary: Get all Tags
      description: |-
        Available parameters:

        | Param         | Type            | Default | Desc                                                          |
        |---------------|-----------------|---------|---------------------------------------------------------------|
        | search        | `str`           | `NULL`  | Full-text search across _name_ field                   |
        | id            | `int/list[int]` | `NULL`  | Match by a single `int` _id_ field, or match by array overlap |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - tags
    parameters: []
  /tags/{tag_id}/detail/:
    get:
      operationId: tags_detail_list
      description: |-
        Get detail of specified tag by tag_id, including associated
          published entities
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - tags
    parameters:
    - name: tag_id
      in: path
      required: true
      type: string
  /templates/:
    get:
      operationId: templates_list
      summary: Get all Collections
      description: |-
        Available parameters:

        | Param         | Type            | Default | Desc                                                                       |
        |---------------|-----------------|---------|----------------------------------------------------------------------------|
        | search        | `str`           | `NULL`  | Full-text search across _name_ and _description_ field                     |
        | id            | `int/list[int]` | `NULL`  | Match by a single `int` _id_ field, or match by array overlap              |
        | name          | `str`           | `NULL`  | Case insensitive direct match of _name_ field                              |
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - templates
    parameters: []
  /templates/{template_id}/detail/:
    get:
      operationId: templates_detail_list
      description: Get detail of a template, optionally target a specific version
        using version_id
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - templates
    parameters:
    - name: template_id
      in: path
      required: true
      type: string
  /templates/{template_id}/get-versions/:
    get:
      operationId: templates_get-versions_list
      description: Get version history of a specific entity, using phenotype_id
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - templates
    parameters:
    - name: template_id
      in: path
      required: true
      type: string
  /templates/{template_id}/version/{version_id}/detail/:
    get:
      operationId: templates_version_detail_list
      description: Get detail of a template, optionally target a specific version
        using version_id
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - templates
    parameters:
    - name: template_id
      in: path
      required: true
      type: string
    - name: version_id
      in: path
      required: true
      type: string
definitions: {}
