drug-discovery-prompts/upstream/K-Dense-AI-scientific-agent-skills/skills/database-lookup/references/opentargets.md

---
title: "Open Targets Platform API"
task: ""
lineage_type: import
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/opentargets.md
upstream_sha: 9c9bd2e9
imported_at: 2026-06-26
prompt_class: prompt
upstream_changes: accepted
author: upstream
validated: false
---

# Open Targets Platform API

## Base URLs

**GraphQL API (primary, recommended):**
```
https://api.platform.opentargets.org/api/v4/graphql
```

**Important:** The GraphQL endpoint requires HTTP POST with `Content-Type: application/json`. WebFetch (GET-only) will not work — use `curl` via shell instead:
```bash
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"query":"{ target(ensemblId: \"ENSG00000157764\") { approvedSymbol approvedName } }"}' \
  https://api.platform.opentargets.org/api/v4/graphql
```

**REST API (simpler queries):**
```
https://api.platform.opentargets.org/api/v4
```

## Authentication

No API key required. All endpoints are public.

## GraphQL API

All GraphQL queries are sent as POST requests to the GraphQL endpoint.

```
POST https://api.platform.opentargets.org/api/v4/graphql
Content-Type: application/json

{
  "query": "...",
  "variables": { ... }
}
```

### 1. Target information (by Ensembl Gene ID)

```graphql
query TargetInfo($ensemblId: String!) {
  target(ensemblId: $ensemblId) {
    id
    approvedSymbol
    approvedName
    biotype
    proteinIds {
      id
      source
    }
    tractability {
      label
      modality
      value
    }
    safetyLiabilities {
      event
      effects {
        direction
        dosing
      }
    }
    pathways {
      pathway
      pathwayId
    }
    functionDescriptions
    subcellularLocations {
      location
    }
  }
}
```

**Variables:** `{ "ensemblId": "ENSG00000141510" }`

**Example as URL (GET also supported for simple queries):**
```
https://api.platform.opentargets.org/api/v4/graphql?query={target(ensemblId:"ENSG00000141510"){id approvedSymbol approvedName biotype functionDescriptions}}
```

---

### 2. Disease information (by EFO ID)

```graphql
query DiseaseInfo($efoId: String!) {
  disease(efoId: $efoId) {
    id
    name
    description
    therapeuticAreas {
      id
      name
    }
    synonyms {
      terms
    }
  }
}
```

**Variables:** `{ "efoId": "EFO_0000311" }` (cancer)

**Example as URL:**
```
https://api.platform.opentargets.org/api/v4/graphql?query={disease(efoId:"EFO_0000311"){id name description therapeuticAreas{id name}}}
```

---

### 3. Target-Disease associations

```graphql
query Associations($ensemblId: String!, $page: Pagination!) {
  target(ensemblId: $ensemblId) {
    approvedSymbol
    associatedDiseases(page: $page) {
      count
      rows {
        disease {
          id
          name
        }
        score
        datasourceScores {
          id
          score
        }
      }
    }
  }
}
```

**Variables:**
```json
{
  "ensemblId": "ENSG00000141510",
  "page": { "index": 0, "size": 10 }
}
```

**Example as URL:**
```
https://api.platform.opentargets.org/api/v4/graphql?query={target(ensemblId:"ENSG00000141510"){approvedSymbol associatedDiseases(page:{index:0,size:5}){count rows{disease{id name}score}}}}
```

---

### 4. Disease-Target associations (from disease side)

```graphql
query DiseaseAssociations($efoId: String!, $page: Pagination!) {
  disease(efoId: $efoId) {
    name
    associatedTargets(page: $page) {
      count
      rows {
        target {
          id
          approvedSymbol
        }
        score
        datasourceScores {
          id
          score
        }
      }
    }
  }
}
```

**Variables:**
```json
{
  "efoId": "EFO_0000311",
  "page": { "index": 0, "size": 10 }
}
```

---

### 5. Evidence for a target-disease pair

```graphql
query Evidence($ensemblId: String!, $efoId: String!, $size: Int!) {
  disease(efoId: $efoId) {
    evidences(ensemblIds: [$ensemblId], size: $size) {
      count
      rows {
        id
        score
        datasourceId
        datatypeId
        literature
        diseaseFromSource
        targetFromSourceId
        resourceScore
        urls {
          niceName
          url
        }
      }
    }
  }
}
```

**Variables:**
```json
{
  "ensemblId": "ENSG00000141510",
  "efoId": "EFO_0000311",
  "size": 10
}
```

---

### 6. Drug/molecule information

```graphql
query DrugInfo($chemblId: String!) {
  drug(chemblId: $chemblId) {
    id
    name
    drugType
    maximumClinicalTrialPhase
    hasBeenWithdrawn
    mechanismsOfAction {
      rows {
        mechanismOfAction
        targets {
          id
          approvedSymbol
        }
      }
    }
    indications {
      rows {
        disease {
          id
          name
        }
        maxPhaseForIndication
      }
    }
    linkedDiseases {
      count
      rows {
        id
        name
      }
    }
    linkedTargets {
      count
      rows {
        id
        approvedSymbol
      }
    }
  }
}
```

**Variables:** `{ "chemblId": "CHEMBL25" }` (aspirin)

**Example as URL:**
```
https://api.platform.opentargets.org/api/v4/graphql?query={drug(chemblId:"CHEMBL25"){id name drugType maximumClinicalTrialPhase mechanismsOfAction{rows{mechanismOfAction targets{id approvedSymbol}}}}}
```

---

### 7. Search across targets, diseases, and drugs

```graphql
query Search($queryString: String!, $entityNames: [String!], $page: Pagination!) {
  search(queryString: $queryString, entityNames: $entityNames, page: $page) {
    total
    hits {
      id
      entity
      name
      description
      score
    }
  }
}
```

**Variables:**
```json
{
  "queryString": "BRAF melanoma",
  "entityNames": ["target", "disease", "drug"],
  "page": { "index": 0, "size": 10 }
}
```

**Example as URL:**
```
https://api.platform.opentargets.org/api/v4/graphql?query={search(queryString:"BRAF",entityNames:["target"],page:{index:0,size:5}){total hits{id entity name description}}}
```

---

### 8. Known drugs for a target

```graphql
query KnownDrugs($ensemblId: String!, $size: Int!) {
  target(ensemblId: $ensemblId) {
    approvedSymbol
    knownDrugs(size: $size) {
      count
      rows {
        drug {
          id
          name
          drugType
          maximumClinicalTrialPhase
        }
        disease {
          id
          name
        }
        phase
        status
        mechanismOfAction
        urls {
          niceName
          url
        }
      }
    }
  }
}
```

**Variables:**
```json
{
  "ensemblId": "ENSG00000157764",
  "size": 10
}
```

(ENSG00000157764 = BRAF)

---

### 9. Tractability (druggability)

Included in the target query (see endpoint 1 above). Modalities include:
- `SM` (small molecule)
- `AB` (antibody)
- `PR` (PROTAC)
- `OC` (other clinical)

---

## REST API Endpoints

These are simpler alternatives for common operations.

### Search

```
GET /api/v4/search?q={query}&page=0&size=10
```

**Example:**
```
https://api.platform.opentargets.org/api/v4/search?q=TP53&size=5
```

**Response:**
```json
{
  "total": 15,
  "data": [
    {
      "id": "ENSG00000141510",
      "entity": "target",
      "name": "TP53",
      "description": "Cellular tumor antigen p53",
      "score": 142.5
    }
  ]
}
```

---

## Key Identifiers

| Entity  | ID Format | Example |
|---------|-----------|---------|
| Target  | Ensembl Gene ID | `ENSG00000141510` (TP53) |
| Disease | EFO/Mondo/HP/Orphanet | `EFO_0000311` (cancer), `MONDO_0007254` |
| Drug    | ChEMBL ID | `CHEMBL25` (aspirin) |

## Datasource IDs (for filtering evidence)

- `ot_genetics_portal` -- Open Targets Genetics
- `eva` -- ClinVar (via EVA)
- `cancer_gene_census` -- COSMIC Cancer Gene Census
- `chembl` -- ChEMBL (clinical trials)
- `europepmc` -- Literature mining
- `expression_atlas` -- Expression Atlas
- `gene2phenotype` -- Gene2Phenotype
- `genomics_england` -- Genomics England PanelApp
- `intogen` -- IntOGen (cancer drivers)
- `ot_crispr` -- Open Targets CRISPR screens
- `progeny` -- PROGENy (pathway activity)
- `reactome` -- Reactome pathways
- `slapenrich` -- SLAPenrich
- `sysbio` -- Systems biology
- `uniprot_literature` -- UniProt literature

## Pagination

GraphQL uses `page: { index: Int, size: Int }` (0-based index).
REST uses `page` and `size` query parameters.

## Rate Limits

- No API key required.
- Fair-use rate limiting applies. No hard published limit.
- For bulk data, use the Open Targets data downloads (Parquet files on GCS/FTP) rather than API.
- Respect HTTP 429 and `Retry-After` headers.

## Error Format

GraphQL errors:
```json
{
  "errors": [
    {
      "message": "Variable '$ensemblId' expected value of type 'String!' but got: null",
      "locations": [{"line": 1, "column": 7}]
    }
  ]
}
```

REST errors return appropriate HTTP status codes with JSON error bodies.

## Tips

- Use the GraphQL API for maximum flexibility -- request only the fields you need.
- The GET method for GraphQL works for simple queries but POST is required for complex ones with variables.
- Combine target + disease queries to get association scores with evidence breakdown.
- Use `datasourceScores` in association queries to see which evidence sources contribute most.
- The Open Targets Platform web UI at `https://platform.opentargets.org` has a GraphQL playground for testing queries.