> ## 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 Resolve

> Resolve a gene symbol, an alias or an Ensembl gene ID to NCBI Gene IDs, with official symbol, name, aliases and organism.

Give `query`: an official gene symbol (TP53), an alias (P53, HER2) or an Ensembl gene ID (ENSG00000141510; a version suffix is dropped). Letters, digits, dots, dashes and `_` only. `taxon_id` picks the organism and is human (9606) unless set. Returns the matching live genes, up to `limit`: genes whose official symbol is the query first, then genes that carry it as an alias, each in the source's order, with the NCBI Gene ID (the input of Gene Summary), the symbol, the full name, the aliases, the nomenclature status, the organism, the chromosome, the cytogenetic band and the gene page link. `matched_on` says how each gene matched. A search hit that carries the query as neither its symbol nor an alias is dropped. `ambiguous` is true when more than one gene matched and none has the query as its official symbol. An unknown query returns an empty matches list. Replaced and discontinued Gene IDs are not returned. A query whose search finds more than 20 live records fails rather than returning a partial answer. Data from NCBI Gene at the US National Center for Biotechnology Information; official human symbols are assigned by the HUGO Gene Nomenclature Committee.

## Authentication

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

## Request Body

<ParamField body="query" type="string" required>
  An official gene symbol (TP53), an alias (P53, HER2) or an Ensembl gene ID (ENSG00000141510, a version suffix is dropped). 1 to 40 characters. Letters, digits, dots, dashes and `_` only, starting with a letter or digit.
</ParamField>

<ParamField body="taxon_id" type="integer">
  The organism as an NCBI Taxonomy ID; 9606 (human) unless set, 10090 is mouse. From 1 to 999999999. Defaults to `9606`.
</ParamField>

<ParamField body="limit" type="integer">
  The most matching genes to return. From 1 to 10. Defaults to `5`.
</ParamField>

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

## Response (200 OK)

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

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `gene_resolve`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US National Center for Biotechnology Information`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.matches" type="object[]">
  Matching live genes, official symbol matches first, then alias matches, up to limit.
</ResponseField>

<ResponseField name="data.result.matches[].gene_id" type="string">
  The NCBI Gene ID, the input of Gene Summary.
</ResponseField>

<ResponseField name="data.result.matches[].symbol" type="string">
  The gene symbol. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].name" type="string">
  The full name. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].matched_on" type="string">
  symbol, alias or ensembl: how the gene matched the query.
</ResponseField>

<ResponseField name="data.result.matches[].aliases" type="string[]">
  Other symbols the gene is known by.
</ResponseField>

<ResponseField name="data.result.matches[].nomenclature_status" type="string">
  Whether the symbol is official or interim; null when the source gives neither.
</ResponseField>

<ResponseField name="data.result.matches[].organism" type="object">
  The organism the gene belongs to.
</ResponseField>

<ResponseField name="data.result.matches[].organism.scientific_name" type="string">
  The organism's scientific name, for example Homo sapiens. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].organism.common_name" type="string">
  The organism's common name, for example human. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].organism.taxon_id" type="number">
  The organism's NCBI Taxonomy ID. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].chromosome" type="string">
  The chromosome, for example 17. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].map_location" type="string">
  The cytogenetic band, for example 17p13.1. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.matches[].page_url" type="string">
  The gene page URL.
</ResponseField>

<ResponseField name="data.result.ambiguous" type="boolean">
  True when more than one gene matched and none has the query as its official symbol, before applying limit.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/resolve/gene \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "query": "HER2"
    }'
  ```

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

  ```typescript SDK theme={null}
  const result = await agent.tool('resolve/gene', {
    query: 'HER2'
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "gene_resolve",
      "result": {
        "matches": [
          {
            "gene_id": "2064",
            "symbol": "ERBB2",
            "name": "erb-b2 receptor tyrosine kinase 2",
            "matched_on": "alias",
            "aliases": [
              "CD340",
              "HER-2",
              "HER-2/neu",
              "HER2",
              "MLN 19",
              "MLN-19",
              "NEU",
              "NGL",
              "TKR1",
              "VSCN2",
              "c-ERB-2",
              "c-ERB2",
              "p185(erbB2)"
            ],
            "nomenclature_status": "official",
            "organism": {
              "scientific_name": "Homo sapiens",
              "common_name": "human",
              "taxon_id": 9606
            },
            "chromosome": "17",
            "map_location": "17q12",
            "page_url": "https://www.ncbi.nlm.nih.gov/gene/2064"
          }
        ],
        "ambiguous": false
      },
      "evidence": {
        "source": "US National Center for Biotechnology Information",
        "source_kind": "public",
        "retrieved_at": "2026-10-17T12:00:00.000Z",
        "calls": [
          {
            "retrieved_at": "2026-10-17T12:00:00.000Z"
          },
          {
            "retrieved_at": "2026-10-17T12:00:00.000Z"
          }
        ],
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) 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`.</Info>

## 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.