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

# Organism Identity

> Resolve an organism name or NCBI Taxonomy ID to the organism, with its rank, common name and lineage.

Resolves a scientific name, common name, recorded misspelling or NCBI Taxonomy ID to matching organisms in the Taxonomy database of the US National Center for Biotechnology Information: taxonomy ID, scientific name, common name, rank, division, lineage from the root down and whether the ID sent is current.

NCBI's Disclaimer ([https://www.ncbi.nlm.nih.gov/home/about/policies/#disclaimer](https://www.ncbi.nlm.nih.gov/home/about/policies/#disclaimer)) and Copyright notice ([https://www.ncbi.nlm.nih.gov/home/about/policies/#copyright](https://www.ncbi.nlm.nih.gov/home/about/policies/#copyright)) apply to these records:

* the US Government does not warrant or assume any legal liability or responsibility for their accuracy, completeness or usefulness, and
* NCBI does not endorse or recommend any commercial products, processes or services.

## Authentication

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

## Request Body

**name** `string`

A scientific name (Homo sapiens), common name (human) or misspelling the source records; give exactly one of name or taxonomy\_id. 2 to 200 characters. No double quotes, brackets or control characters.

**taxonomy\_id** `integer`

An NCBI Taxonomy ID, for example 9606; give exactly one of name or taxonomy\_id. From 1 to 999999999.

<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 `organism_resolve`

**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 `US National Center for Biotechnology Information`.

**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 | null`

The date the source last changed the record, when the answer names one organism; null otherwise.

## Result

Nested under `data.result`.

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

Matching organisms in the source's order, up to 10.

**data.result.matches\[].taxonomy\_id** `integer`

The NCBI Taxonomy ID of the record, the one the source uses now.

**data.result.matches\[].scientific\_name** `string`

The scientific name, for example Homo sapiens.

**data.result.matches\[].common\_name** `string | null`

The common name, for example human; null when the source records none.

**data.result.matches\[].rank** `string | null`

The rank as the source writes it: species, genus, family, no rank and so on. `null` when the source gives no value.

**data.result.matches\[].division** `string | null`

The source's division, for example Primates or Bacteria. `null` when the source gives no value.

**data.result.matches\[].lineage** `object[]`

The ancestors in order, from the root of the tree down to the parent of this record.

**data.result.matches\[].lineage\[].rank** `string | null`

The rank of this ancestor as the source writes it. `null` when the source gives no value.

**data.result.matches\[].lineage\[].name** `string`

The ancestor's scientific name.

**data.result.matches\[].lineage\[].taxonomy\_id** `integer`

The ancestor's NCBI Taxonomy ID.

**data.result.matches\[].active** `boolean`

False when the taxonomy\_id sent is a retired id the source merged into this record.

**data.result.ambiguous** `boolean`

True when the name matched more than one organism.

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

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

```typescript SDK theme={null}
const result = await agent.tool('resolve/organism', {
  name: 'Escherichia coli'
});
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": "organism_resolve",
    "result": {
      "matches": [
        {
          "taxonomy_id": 562,
          "scientific_name": "Escherichia coli",
          "common_name": "E. coli",
          "rank": "species",
          "division": "Bacteria",
          "lineage": [
            {
              "rank": "cellular root",
              "name": "cellular organisms",
              "taxonomy_id": 131567
            },
            {
              "rank": "domain",
              "name": "Bacteria",
              "taxonomy_id": 2
            },
            {
              "rank": "kingdom",
              "name": "Pseudomonadati",
              "taxonomy_id": 3379134
            },
            {
              "rank": "phylum",
              "name": "Pseudomonadota",
              "taxonomy_id": 1224
            },
            {
              "rank": "class",
              "name": "Gammaproteobacteria",
              "taxonomy_id": 1236
            },
            {
              "rank": "order",
              "name": "Enterobacterales",
              "taxonomy_id": 91347
            },
            {
              "rank": "family",
              "name": "Enterobacteriaceae",
              "taxonomy_id": 543
            },
            {
              "rank": "genus",
              "name": "Escherichia",
              "taxonomy_id": 561
            }
          ],
          "active": true
        }
      ],
      "ambiguous": false
    },
    "evidence": {
      "source": "US National Center for Biotechnology Information",
      "source_kind": "public",
      "retrieved_at": "2026-11-02T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-11-02T12:00:00.000Z"
        },
        {
          "retrieved_at": "2026-11-02T12:00:00.000Z"
        }
      ],
      "as_of": "2024-03-22"
    }
  }
}
```

> [!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

* Give exactly one of `name` or `taxonomy_id`.
* `name` matches every name the source keeps for an organism, including common names and the misspellings it records, so `Home sapiens` resolves to Homo sapiens. The whole name must match; it is not a word search.
* A name shared by more than one organism (mouse is both the species Mus musculus and the genus Mus) returns each, up to 10, in the source's order, with `ambiguous` true.
* A retired taxonomy ID returns the record it was merged into, with `active` false.
* An unknown name or taxonomy ID returns an empty matches list.
* The NCBI Taxonomy ID is the `taxon_id` input of Gene Resolve.
* 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.