openapi: 3.0.0
servers:
  - url: //platform-api.opentargets.io/v3
info:
  contact:
    email: support@targetvalidation.org
    name: Open Targets Platform team
  description: |
    ### The Open Targets Platform REST API

    The Open Targets Platform API ('Application Programming Interface') allows programmatic retrieval of the Open Targets Platform data via a set of [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) services.

    You can make calls to the latest version of our API using the base URL `https://platform-api.opentargets.io/v3/platform`. Please make sure you use `https` instead of the unencrypted `http` calls, which we do not accept.

    We list below the methods available to query our data directly from the API, followed by an interactive interface that you can use to try out the parameters and execute the REST-API calls.

    For every request you create, the interactive interface will display both a [curl](https://curl.haxx.se/) command and a request URL that you can use to ensure you get the expected response before using your application or workflow. 

    Check our documentation for some [API tutorials](https://docs.targetvalidation.org/tutorials/api-tutorials) and [get in touch](mailto:support@targetvalidation.org) if you have any questions.

    ### Available Methods

    The available methods can be grouped in three types:

    * __public__ - Methods that serve the core set of our data. These are stable and we fully supported them.
    * __private__ - Methods used by the web app to serve additional data not specific to our platform. These methods
    may change without notice and should be used with caution.
    * __utils__ - Methods to get statistics and technical data about our API.

    ### Supported formats

    The methods above are all available via a `GET` request, and will serve outputs as `JSON`.

    Alternative output formats, such `xml`, `csv` and `tab`, are also available for some of the methods. However alternative output formats are not supported in interactive interface below where the response will be always in `JSON.

    If you have complex queries with large number of parameters, you should use a `POST` request instead of  `GET`. 
    `POST` methods require a body encoded as `json`. When querying for a specific disease using the latest version of the API, your call would look like the example below:

    ```sh
    curl -X POST -d '{"disease":["EFO_0000253"]}' --header 'Content-Type: application/json' https://platform-api.opentargets.io/v3/platform/public/evidence/filter
    ```
    ### How to interpret a response

    Each HTTPS response will serve data in headers and body. The headers will give you details about your query, such as how long it took to run.

    In the body of the response, you will find the data you have requested for in `JSON` format. The [jq](https://stedolan.github.io/jq/) program is a useful tool to parse the json response while on the command line.

    ```sh
    curl https://platform-api.opentargets.io/v3/platform/public/association/filter\?target\=ENSG00000157764 | jq
    ```

    We do not analyse the nature of any specific API queries except for the purposes of improving the performance of our API.
    Read more in our [privacy section](https://www.targetvalidation.org/terms_of_use#privacy).

    How can we make the Open Targets Platform API more useful to you? Would you like additional methods to be implemented?
    Please [get in touch](mailto:support@targetvalidation.org) and send your suggestions.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Open Targets Platform REST API
  version: 19.02.1
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://www.targetvalidation.org/imgs/logo/ot_logo_webheader.svg
  x-origin:
    - format: openapi
      url: http://api.opentargets.io/v3/platform/swagger
      version: "3.0"
  x-providerName: opentargets.io
tags:
  - description: Methods to filter the available evidence.
    name: filter
  - description: Methods to get specific evidence.
    name: retrieve
  - description: Methods to search for target or diseases.
    name: search
  - description: Publicly supported stable API.
    name: public
  - description: Unstable API methods. Subject to change without prior notice. Use at your own risk.
    name: private
  - description: Utility methods.
    name: utils
paths:
  /platform/docs:
    get:
      description: Access api docs as served by Redoc
      operationId: getApiDocs
      responses:
        "200":
          description: Redoc API documentation file
      summary: Browse API documentation
      tags:
        - private
  /platform/docs/swagger-ui:
    get:
      description: Interactive API docs using swagger-ui
      operationId: getApiSwaggerUI
      responses:
        "200":
          description: Swagger-UI API documentation file
      summary: Browse interactive API documentation
      tags:
        - private
  /platform/private/autocomplete:
    get:
      description: |
        Search for the closest term to autocomplete in the search box.
      operationId: getAutocomplete
      parameters:
        - description: A full text query.
          in: query
          name: q
          required: true
          schema:
            type: string
        - description: Maximum amount of results to return. Defaults to 5.
          in: query
          name: size
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Get `autocomplete` objects.
      tags:
        - private
  /platform/private/besthitsearch:
    post:
      description: |
        Fire the search method for multiple strings
      operationId: postBestHitSearch
      requestBody:
        content:
          application/json:
            schema:
              type: string
        description: list of strings to search for
        required: true
      responses:
        "200":
          description: Successful response
      summary: Find the best hit
      tags:
        - private
  /platform/private/disease:
    post:
      description: |
        Get `disease` objects.
      operationId: postDiseaseById
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"disease":["disease1", "disease2"],
                "facets" = "true"}
              type: string
        description: An EFO identifier.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Find information about a list of diseases
      tags:
        - private
  "/platform/private/disease/{disease}":
    get:
      description: |
        Get `disease` objects.
      operationId: getDiseaseById
      parameters:
        - description: An EFO identifier.
          in: path
          name: disease
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Find information about a disease
      tags:
        - private
  "/platform/private/drug/{DRUG_ID}":
    get:
      description: |
        Get `drug` objects.
      operationId: getDrugByID
      parameters:
        - description: An ID in the drug index.
          in: query
          name: drug_id
          required: true
          schema:
            type: string
        - description: Automatically added
          in: path
          name: DRUG_ID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Get drug by ID
      tags:
        - private
  "/platform/private/eco/{ECO_ID}":
    get:
      description: |
        Get `ECO` objects.
      operationId: getECObyID
      parameters:
        - description: An [evidence code ontology](http://www.ebi.ac.uk/ols/v2/browse.do?ontName=ECO) ID.
          in: path
          name: ECO_ID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Get evidence code by ID
      tags:
        - private
  /platform/private/enrichment/targets:
    post:
      description: |
        Returns an enrichment analysis for a list of targets passed in the body
      operationId: postEnrichmentTarget
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"target" : ["ENSG00000001", "ENSG00000002"],
                 "pvalue" : 0.001,
                 "size" : 20}
              type: string
        description: IDs of the targets to do the enrichment analysis for.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Enrichment analysis
      tags:
        - private
  /platform/private/quicksearch:
    get:
      description: |
        Get `search-result` objects. Enables search bar functionality.
      operationId: getQuickSearch
      parameters:
        - description: A full text query.
          in: query
          name: q
          required: true
          schema:
            type: string
        - description: Maximum amount of results to return. Defaults to 5.
          in: query
          name: size
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Search most relevant results
      tags:
        - private
  /platform/private/relation:
    post:
      description: |
        Get `relation` objects.
      operationId: postRelation
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"subject":["gene1", "gene2"]}
              type: string
        description: An Ensembl gene identifier.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Find related entities
      tags:
        - private
  "/platform/private/relation/disease/{disease}":
    get:
      description: |
        Get `relation` objects starting from diseases.
      operationId: getRelationByEFOID
      parameters:
        - description: An EFO gene identifier.
          in: path
          name: disease
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Find related entities by disease
      tags:
        - private
  "/platform/private/relation/target/{target}":
    get:
      description: |
        Get `relation` objects starting from diseases.
      operationId: getRelationByENSGID
      parameters:
        - description: An Ensembl gene identifier.
          in: path
          name: target
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Find related entities by target
      tags:
        - private
  /platform/private/target:
    post:
      description: |
        Get `target` objects. Used for the target profile page.
      operationId: postTargetByENSGID
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"target":["target1", "target2"],
                "facets" = "true"}
              type: string
        description: An Ensembl gene identifier.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Find information about a list of targets
      tags:
        - private
      x-code-samples:
        - lang: Python
          source: |
            import requests
            r = requests.get('http://api.opentargets.io/v3/platform/private/target/ENSG00000064687')
            for ph in r.json()['mouse_phenotypes'][0]['phenotypes']:
                    try:
                        for link in ph['genotype_phenotype']:
                            print(
                                link['mp_identifier'],
                                'https://europepmc.org/search?query=EXT_ID:'+link['pmid'],
                                link['mp_label'],
                                sep="\t")
                    except KeyError:
                        pass
  /platform/private/target/expression:
    get:
      description: |
        Get `gene-expression` objects.
      operationId: getTargetExpressionByENSGID
      parameters:
        - description: An Ensembl gene identifier.
          in: query
          name: gene
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Query expression levels
      tags:
        - private
    post:
      description: |
        Get `gene-expression` objects.
      operationId: postTargetExpressionByENSGID
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"gene":["gene1", "gene2"]}
              type: string
        description: An Ensembl gene identifier.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Batch query expression levels
      tags:
        - private
  "/platform/private/target/{target}":
    get:
      description: |
        Get `target` objects.
      operationId: getTargetByENSGID
      parameters:
        - description: An Ensembl gene ID for the target of interest.
          in: path
          name: target
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Find information about a target
      tags:
        - private
  /platform/public/association:
    get:
      description: |
        Once we integrate all evidence connecting a target to a specific disease, we
         compute an association score by the means of an harmonic sum. This *association score* provides
         an indication of how strong the evidence behind each connection is and can be
         used to rank genes in order of likelihood as drug targets.
         The association ID is constructed by using the Ensembl ID of the gene and the
         EFO ID for the disease (e.g. ENSG00000073756-EFO_0003767).
         The method returns an association object, which contains the data and summary
         on each evidence type included in the calculation of the score, as well as the score itself.
      operationId: getAssociationById
      parameters:
        - description: An association ID usually in the form of `TARGET_ID-DISEASE_ID`.
          in: query
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Get association by id
      tags:
        - public
        - retrieve
  /platform/public/association/filter:
    get:
      description: |
        More complex queries for associations scores and objects can be done using
        this method, which allows to sort in different order, restrict to a specific class
        of diseases or targets, as well as filtering results by score and associated pathways.
      operationId: getAssociationFilter
      parameters:
        - description: A target identifier listed as target.id.
          in: query
          name: target
          required: false
          schema:
            type: string
        - description: An EFO code listed as disease.id.
          in: query
          name: disease
          required: false
          schema:
            type: string
        - description: An EFO code of a therapeutic area.
          in: query
          name: therapeutic_area
          required: false
          schema:
            type: string
        - description: Data source to consider.
          in: query
          name: datasource
          required: false
          schema:
            type: string
        - description: Data type to consider.
          in: query
          name: datatype
          required: false
          schema:
            type: string
        - description: A Reactome pathway identifier (returning only those targets linked to the specified pathway).
          in: query
          name: pathway
          required: false
          schema:
            type: string
        - description: A ChEMBL target class identifier (returning only those targets belonging to the specified class).
          in: query
          name: target_class
          required: false
          schema:
            type: string
        - description: A UniProt keyword (meaning all the targets linked to that keyword).
          in: query
          name: uniprotkw
          required: false
          schema:
            type: string
        - description: If `true`, it returns associations that have at least one direct evidence connecting the target and the disease. If `false` it only returns associations for which there is no direct evidence connecting the target and the disease, but only evidence connecting the target to a children of the disease in the EFO ontology.
          in: query
          name: direct
          required: false
          schema:
            type: boolean
        - description: Type of data structure to return. Can be 'full', 'simple', 'ids', or 'count'.
          in: query
          name: datastructure
          required: false
          schema:
            type: string
        - description: Fields you want to retrieve. This will get priority over the data structure requested.
          in: query
          name: fields
          required: false
          schema:
            type: string
        - description: Returns facets
          in: query
          name: facets
          required: false
          schema:
            default: false
            type: boolean
        - description: Filter by minimum score value. The default is 0, but using 0.2 is a good trade-off to filter lower quality data points.
          in: query
          name: scorevalue_min
          required: false
          schema:
            default: 0
            format: float
            type: number
        - description: Filter by maximum score value.
          in: query
          name: scorevalue_max
          required: false
          schema:
            format: float
            type: number
        - description: Score types to apply the score value min and max filters. The default is `overall`.
          in: query
          name: scorevalue_types
          required: false
          schema:
            type: string
        - description: Maximum amount of results to return. Defaults to 10, max is 10000.
          in: query
          name: size
          required: false
          schema:
            format: integer
            type: number
        - description: How many initial results should be skipped. Defaults to 0.
          in: query
          name: from
          required: false
          schema:
            format: integer
            type: number
        - description: Format to get the data back. Can be 'json', 'xml', 'tab' or 'csv'. **Note** that this option can only be used when calling the API directly and will not work in this page. The response here will always be JSON.
          in: query
          name: format
          required: false
          schema:
            type: string
        - description: |
            Sort by the given score type. Defaults to 'overall' and descending order. Use '~' prefix to do ascending
            order e.g. '~overall'. You will call a data type score like: 'datatypes.literature', and a data source as
            'datasources.gwas'. Supports multiple entries.
          in: query
          name: sort
          required: false
          schema:
            type: string
        - description: |
            Restrict the filtered results to those matching the passed string. The matching is done with a
            phrase match prefix.
          in: query
          name: search
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Filter available associations
      tags:
        - public
        - filter
      x-code-samples:
        - lang: httpie
          source: |
            http https://www.targetvalidation.org/api/latest/public/association/filter target==ENSG00000167207 disease==EFO_0003767
    post:
      description: |
        Complex queries and filters for association objects can also be submitted using a JSON
        object and the equivalent POST method.
      operationId: postAssociationFilter
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"target":["target1", "target2"]}
              type: string
        description: Filters to apply when retrieving association objects.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Batch query available associations
      tags:
        - public
        - filter
  /platform/public/evidence:
    get:
      description: |
        We call **evidence** a unit of data that support a connection between a target and a disease.
        The Open Targets Platform integrates multiple types of evidence including genetic associations,
        somatic mutations, RNA expression and target-disease associations mined from the literature.
        This method allows you to retrieve a single evidence item or a list of pieces of evidence by using their
        targetvalidation.org ID.

        Evidence IDs are unique within each data release (e.g. `8ed3d7568a8c6cac9c95cfb869bac762` for release 1.2).
        You can obtain a list of evidence and their IDs from other API calls such as [/public/evidence/filter](#!/public/get_public_evidence_filter).

        **Please note** that a specific evidence ID may change between data releases. We can not guarantee that a specific evidence ID will refer to the same piece of evidence connecting a target and its diseases.
      operationId: getEvidenceById
      parameters:
        - description: Internal unique ID of the evidence string to retrieve.
          in: query
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Get evidence by ID
      tags:
        - public
        - retrieve
    post:
      description: |
        This is the POST version of [/public/evidence](#!/public/get_public_evidence).
        It allows to query for a list of evidence strings encoded in a `json` object to be passed in the body.
      operationId: postEvidenceById
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"id":["id1", "id2"]}
              type: string
        description: IDs of the evidence string to retrieve.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Get evidence for a list of IDs
      tags:
        - public
        - retrieve
  /platform/public/evidence/filter:
    get:
      description: |
        The filter method allows to retrieve the specific data that supports a connection between targets and diseases.
        Filters can be used to restrict the results by source and type of data,
        or limit results to targets which are part of a particular pathway.
        Minimum and maximum scores can be specified as well as the type of evidence linking target and disease.
        **Note** that multiple genes and diseases can be specified in the same request.
      operationId: getEvidenceFilter
      parameters:
        - description: A target identifier listed as target.id.
          in: query
          name: target
          required: false
          schema:
            type: string
        - description: An EFO code listed as disease.id.
          in: query
          name: disease
          required: false
          schema:
            type: string
        - description: Data source to consider.
          in: query
          name: data source
          required: false
          schema:
            type: string
        - description: Data type to consider.
          in: query
          name: datatype
          required: false
          schema:
            type: string
        - description: A pathway identifier (meaning all the targets linked to that pathway).
          in: query
          name: pathway
          required: false
          schema:
            type: string
        - description: A UniProt keyword (meaning all the targets linked to that keyword).
          in: query
          name: uniprotkw
          required: false
          schema:
            type: string
        - description: Type of data structure to return. Can be 'full', 'simple', 'ids', or 'count'.
          in: query
          name: datastructure
          required: false
          schema:
            type: string
        - description: The fields you want to retrieve. This will get priority over the data structure requested.
          in: query
          name: fields
          required: false
          schema:
            type: string
        - description: Filter by minimum score value. The default is 0, but using 0.2 is a good trade-off to filter lower quality data points.
          in: query
          name: scorevalue_min
          required: false
          schema:
            default: 0
            format: float
            type: number
        - description: Filter by maximum score value.
          in: query
          name: scorevalue_max
          required: false
          schema:
            format: float
            type: number
        - description: |
            Sort by the given field. The default is 'scores.association_score' in descending order. Use '~' prefix to do ascending
            order e.g. '~scores.association_score'. It supports multiple entries.
          in: query
          name: sort
          required: false
          schema:
            type: string
        - description: Maximum amount of results to return. Defaults to 10, max is 10000.
          in: query
          name: size
          required: false
          schema:
            format: integer
            type: number
        - description: How many initial results should be skipped. Defaults to 0.
          in: query
          name: from
          required: false
          schema:
            format: integer
            type: number
        - description: Format to get the data back. Can be 'json', 'xml', 'tab' or 'csv'. **Note** that this option can only be used when calling the API directly and will not work in this page. The response here will always be JSON.
          in: query
          name: format
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Filter available evidence
      tags:
        - public
        - filter
      x-code-samples:
        - lang: httpie
          source: |
            http https://www.targetvalidation.org/api/latest/public/evidence/filter target==ENSG00000167207 disease==EFO_0003767 datastructure==simple
    post:
      description: |
        POST version of [/public/evidence/filter](#!/public/get_public_evidence_filter).
        Filters can be specified as part of a `json` object in the body, simplifying the submission of queries.
      operationId: postEvidenceFilter
      requestBody:
        content:
          application/json:
            schema:
              example: |
                {"target":["ENSG00000094755", "ENSG00000167207"], "disease":["EFO_0003767"]}
              type: string
        description: Filters to apply when retrieving evidence string objects.
        required: true
      responses:
        "200":
          description: Successful response
      summary: Batch filter available evidence
      tags:
        - public
        - filter
  /platform/public/search:
    get:
      description: |
        This method allows you to look for gene or diseases of interest using a free text search,
        replicating the functionality of the search box on our homepage. It should be used to identify
        the best match for a disease or target of interest, rather than gathering a specific set of evidence.
      operationId: getSearch
      parameters:
        - description: A full text query.
          in: query
          name: q
          required: true
          schema:
            type: string
        - description: Maximum amount of results to return. Defaults to 10, max is 10000.
          in: query
          name: size
          required: false
          schema:
            type: string
        - description: How many initial results should be skipped. Defaults to 0.
          in: query
          name: from
          required: false
          schema:
            type: string
        - description: Restrict the search to the type requested. Eg. `target` or `disease`.
          in: query
          name: filter
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
      summary: Search for a disease or a target
      tags:
        - public
        - search
      x-code-samples:
        - lang: httpie
          source: |
            http https://api.opentargets.io/api/latest/public/search q==NOD2 size==1 filter==target
        - lang: Python
          source: |
            import requests
            from pprint import pprint
            r = requests.get('https://www.targetvalidation.org/api/latest/public/search',
                            params={"q":"NOD2","size":1})
            pprint(r.json())
  /platform/public/utils/metrics:
    get:
      description: |
        Returns the metrics about associations and evidences, divided by datasource, genes and so on.
      operationId: getDataMetrics
      responses:
        "200":
          description: Successful response
      summary: Get metrics about the current data release
      tags:
        - public
        - utils
      x-code-samples:
        - lang: Python
          source: |
            import requests
            r = requests.get('https://www.targetvalidation.com/api/latest/public/metrics')
            assert r.status_code == 200
            assert r.headers['content-type'] == 'application/json'
            print(r.json())
  /platform/public/utils/ping:
    get:
      description: |
        Check if the API is up
      operationId: getPing
      responses:
        "200":
          description: Successful response
      summary: Ping service
      tags:
        - public
        - utils
  /platform/public/utils/stats:
    get:
      description: |
        Returns the number of associations and evidences, divided by datasource.
      operationId: getDataStats
      responses:
        "200":
          description: Successful response
      summary: Get statistics about the current data release
      tags:
        - public
        - utils
      x-code-samples:
        - lang: Python
          source: |
            import requests
            r = requests.get('https://www.targetvalidation.com/api/latest/public/stats')
            assert r.status_code == 200
            assert r.headers['content-type'] == 'application/json'
            print(r.json())
  /platform/public/utils/therapeuticareas:
    get:
      description: |
        Returns the list of therapeutic areas for the current data release
      operationId: getTherapeuticAreas
      responses:
        "200":
          description: Successful response
      summary: Get the list of therapeutic areas about the current data release
      tags:
        - public
        - utils
      x-code-samples:
        - lang: Python
          source: |-
            import requests
            r = requests.get('https://www.targetvalidation.com/api/latest/public/therapeuticareas')
            assert r.status_code == 200
            assert r.headers['content-type'] == 'application/json'
            print(r.json())
  /platform/public/utils/version:
    get:
      description: |
        Returns current API version.
      operationId: getVersion
      responses:
        "200":
          description: Successful response
      summary: Get API version
      tags:
        - public
        - utils
      x-code-samples:
        - lang: Shell
          source: |
            curl -X GET https://www.targetvalidation.org/api/latest/public/utils/version
  /platform/swagger:
    get:
      description: Get swagger.yaml specs for the API
      operationId: getSwagger
      responses:
        "200":
          description: Swagger.yaml file
      summary: Get OpenAPI schema
      tags:
        - private
x-tagGroups:
  - name: Stable
    tags:
      - filter
      - retrieve
      - search
  - name: Utilities
    tags:
      - utils
      - private
  - name: All
    tags:
      - public
      - private
