> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gene Diseases

> Rank the diseases linked to a human gene by association evidence, with per-datatype scores.

Reports the diseases the Open Targets Platform (CC0) associates with a human gene, strongest overall score first, with the evidence score of each datatype (genetic association, somatic mutation, known drug, affected pathway, literature, RNA expression, animal model, genetic literature). Human genes only. Pass an official gene symbol or an Ensembl gene ID; a version suffix is dropped. A symbol matches only a search hit with exactly that name, ignoring case: otherwise matched is false and the near hits are listed as candidates so you can retry by Ensembl ID. An unknown Ensembl ID returns matched: false. A score between 0 and 1 summarises the strength of the evidence that the gene and disease are associated; it is not a measure of causation or clinical risk. The data is for research and is not medical advice.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**gene** `string` *required*

An official human gene symbol (BRCA1) or an Ensembl gene ID (ENSG00000012048); a version suffix is dropped. 1 to 30 characters. Letters, digits, ".", "\_" and "-" only.

**limit** `integer`

Diseases returned, highest overall score first. From 1 to 25. Defaults to `10`.

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `gene_diseases`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `Open Targets Platform (EMBL-EBI and partners)`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.matched** `boolean`

Whether the input named one gene in the source.

**data.result.candidates** `object[]`

Search hits with a near name, only when matched is false after a symbol search.

**data.result.candidates\[].ensembl\_id** `string`

Ensembl gene ID of the search hit.

**data.result.candidates\[].symbol** `string`

Approved symbol of the search hit.

**data.result.candidates\[].name** `string`

Approved name of the search hit. `null` when the source gives no value.

**data.result.gene** `object`

The matched gene, or null.

**data.result.gene.ensembl\_id** `string`

Ensembl gene ID.

**data.result.gene.symbol** `string`

Approved gene symbol.

**data.result.gene.name** `string`

Approved gene name. `null` when the source gives no value.

**data.result.total\_associations** `integer`

Number of diseases associated with the gene before limit.

**data.result.diseases** `object[]`

Associated diseases, highest overall score first.

**data.result.diseases\[].disease\_id** `string`

EFO or MONDO disease identifier.

**data.result.diseases\[].name** `string`

Disease name.

**data.result.diseases\[].score** `number`

Overall association score, 0 to 1: strength of evidence, not causation or clinical risk.

**data.result.diseases\[].evidence** `object[]`

Evidence scores by datatype, in source order.

**data.result.diseases\[].evidence\[].datatype** `string`

Evidence datatype: genetic\_association, somatic\_mutation, known\_drug, affected\_pathway, literature, rna\_expression, animal\_model or genetic\_literature.

**data.result.diseases\[].evidence\[].score** `number`

Association score from this datatype alone, 0 to 1.

**data.result.diseases\[].page\_url** `string`

Open Targets evidence page for the gene and disease.

**data.result.release** `string`

Open Targets Platform release as year.month (26.09); null when no association query ran.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/gene-diseases \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "gene": "BRCA1",
    "limit": 2
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/gene-diseases", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "gene": "BRCA1",
    "limit": 2
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/gene-diseases', {
  gene: 'BRCA1',
  limit: 2
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "gene_diseases",
    "result": {
      "matched": true,
      "gene": {
        "ensembl_id": "ENSG00000012048",
        "symbol": "BRCA1",
        "name": "BRCA1 DNA repair associated"
      },
      "total_associations": 1324,
      "diseases": [
        {
          "disease_id": "MONDO_0007254",
          "name": "breast cancer",
          "score": 0.8436508158150241,
          "evidence": [
            {
              "datatype": "literature",
              "score": 0.9984727309333157
            },
            {
              "datatype": "genetic_association",
              "score": 0.9857814423386521
            },
            {
              "datatype": "genetic_literature",
              "score": 0.607930797611621
            }
          ],
          "page_url": "https://platform.opentargets.org/evidence/ENSG00000012048/MONDO_0007254"
        },
        {
          "disease_id": "MONDO_0003582",
          "name": "hereditary breast ovarian cancer syndrome",
          "score": 0.8278837838347972,
          "evidence": [
            {
              "datatype": "literature",
              "score": 0.40300598598830056
            },
            {
              "datatype": "animal_model",
              "score": 0.40179666241146067
            },
            {
              "datatype": "genetic_association",
              "score": 0.9179786150922271
            },
            {
              "datatype": "genetic_literature",
              "score": 0.8855819352769478
            }
          ],
          "page_url": "https://platform.opentargets.org/evidence/ENSG00000012048/MONDO_0003582"
        }
      ],
      "release": "26.09"
    },
    "evidence": {
      "source": "Open Targets Platform (EMBL-EBI and partners)",
      "source_kind": "public",
      "retrieved_at": "2026-10-22T17:37:55.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-22T17:37:55.000Z"
        },
        {
          "retrieved_at": "2026-10-22T17:37:55.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.