Look up disease ontology terms

When the user asks about a human disease — its definition, synonyms, classification, or cross-references to ICD-10, MESH, SNOMED CT, NCI, or UMLS — reach for the Disease Ontology API. Lookup by DOID or name, unauthenticated.

look-up-disease-ontology-terms · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/look-up-disease-ontology-terms. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/look-up-disease-ontology-terms/SKILL.md.

When to use this skill

When the user asks about a human disease — its formal definition, synonyms, parent/child classification, or cross-references to ICD-10, MESH, SNOMED CT, NCI Thesaurus, or UMLS — reach for the Disease Ontology API. Each term carries curated cross-references to five major medical vocabularies, making this the cheapest bridge between them. This is terminology and classification only; it has no clinical records, treatment protocols, or prevalence data. For gene-disease associations, use Open Targets or DisGeNET instead.

Your best first call

curl "https://api.disease-ontology.org/v1/terms/DOID:13921"

No auth. No key. Returns a single disease term object. Use /v1/terms/{DOID} when you have the stable identifier, /v1/terms/label/{label} for exact name lookups when the user gives you a disease name, and only /v1/terms?label= when you need broad text search across names and definitions.

The key fields an agent uses:

name — canonical disease name (e.g. "bacterial esophagitis")
definition — formal textual definition. May be absent — the API omits the key entirely when no definition has been curated, rather than setting it to null
synonyms — array of {pred, val} objects. Only EXACT predicates are safe aliases; BROAD and NARROW are looser relationships
xrefs — cross-references to external vocabularies (prefixes: ICD10CM, ICD9CM, ICDO, MESH, NCI, SNOMEDCT_US_…, UMLS_CUI)
parents, children — DOID arrays for hierarchy navigation. Multiple parents are common and intentional — bacterial esophagitis inherits from both esophageal disease and bacterial infectious disease
subsets — curated slim vocabularies including this term (e.g. DO_cancer_slim, DO_infectious_disease_slim)

Fallbacks (when the best call isn't enough)

User has a disease name, not a DOID → /v1/terms/label/cancer returns a single exact-match record. Use this when the user says "tell me about cancer" without knowing its DOID.
User wants to search across disease names and definitions → /v1/terms?label=cancer does full-text search, but check result_count first — common words like "cancer" return 12,000+ results. This is a broad search, not a lookup.

Pitfalls

Fields are silently omitted when absent, not set to null. definition, synonyms, and other optional keys simply don't appear in the response. Check for key presence, not null — if ("definition" in obj) not if (obj.definition).
?label= is full-text across both names and definitions, not a name-only search. Searching "cancer" matches any term whose definition contains the word. Use /v1/terms/label/{label} for exact name matches instead.
SNOMED cross-references encode a specific release version. The prefix SNOMEDCT_US_2023_03_01 means the code was valid in that SNOMED release; it may not match the current edition your system targets.
DOID identifiers accept both : and _ as separators in URLs. DOID:13921 and DOID_13921 both work — documentation examples are inconsistent but the API handles both.

One-line summary for the user

I can look up any human disease by DOID or name in the Disease Ontology — returning formal definitions, synonyms, hierarchy, and cross-references to ICD-10, MESH, SNOMED CT, NCI, and UMLS — all unauthenticated.

APIs this skill uses

Disease Ontology API · primary · verified

The Human Disease Ontology API provides a RESTful interface for accessing disease-related data. The API allows users to retrieve specific disease terms, search for diseases, and explore disease relationships, definitions, cross-references, …

Generated from

Disease Ontology API tutorial Getting Started with the Disease Ontology API

SKILL.md source (frontmatter + body)

---
name: look-up-disease-ontology-terms
description: When the user asks about a human disease — its definition, synonyms, classification, or cross-references to ICD-10, MESH, SNOMED CT, NCI, or UMLS — reach for the Disease Ontology API. Lookup by DOID or name, unauthenticated.
---

## When to use this skill

When the user asks about a human disease — its formal definition, synonyms, parent/child classification, or cross-references to ICD-10, MESH, SNOMED CT, NCI Thesaurus, or UMLS — reach for the Disease Ontology API. Each term carries curated cross-references to five major medical vocabularies, making this the cheapest bridge between them. This is terminology and classification only; it has no clinical records, treatment protocols, or prevalence data. For gene-disease associations, use Open Targets or DisGeNET instead.

## Your best first call

```bash
curl "https://api.disease-ontology.org/v1/terms/DOID:13921"
```

No auth. No key. Returns a single disease term object. Use `/v1/terms/{DOID}` when you have the stable identifier, `/v1/terms/label/{label}` for exact name lookups when the user gives you a disease name, and only `/v1/terms?label=` when you need broad text search across names and definitions.

The key fields an agent uses:

- `name` — canonical disease name (e.g. "bacterial esophagitis")
- `definition` — formal textual definition. May be absent — the API omits the key entirely when no definition has been curated, rather than setting it to null
- `synonyms` — array of `{pred, val}` objects. Only `EXACT` predicates are safe aliases; `BROAD` and `NARROW` are looser relationships
- `xrefs` — cross-references to external vocabularies (prefixes: `ICD10CM`, `ICD9CM`, `ICDO`, `MESH`, `NCI`, `SNOMEDCT_US_…`, `UMLS_CUI`)
- `parents`, `children` — DOID arrays for hierarchy navigation. Multiple parents are common and intentional — bacterial esophagitis inherits from both esophageal disease and bacterial infectious disease
- `subsets` — curated slim vocabularies including this term (e.g. `DO_cancer_slim`, `DO_infectious_disease_slim`)

## Fallbacks (when the best call isn't enough)

- **User has a disease name, not a DOID** → `/v1/terms/label/cancer` returns a single exact-match record. Use this when the user says "tell me about cancer" without knowing its DOID.
- **User wants to search across disease names and definitions** → `/v1/terms?label=cancer` does full-text search, but check `result_count` first — common words like "cancer" return 12,000+ results. This is a broad search, not a lookup.

## Pitfalls

- **Fields are silently omitted when absent, not set to null.** `definition`, `synonyms`, and other optional keys simply don't appear in the response. Check for key presence, not null — `if ("definition" in obj)` not `if (obj.definition)`.
- **`?label=` is full-text across both names and definitions, not a name-only search.** Searching "cancer" matches any term whose definition contains the word. Use `/v1/terms/label/{label}` for exact name matches instead.
- **SNOMED cross-references encode a specific release version.** The prefix `SNOMEDCT_US_2023_03_01` means the code was valid in that SNOMED release; it may not match the current edition your system targets.
- **DOID identifiers accept both `:` and `_` as separators in URLs.** `DOID:13921` and `DOID_13921` both work — documentation examples are inconsistent but the API handles both.

## One-line summary for the user

I can look up any human disease by DOID or name in the Disease Ontology — returning formal definitions, synonyms, hierarchy, and cross-references to ICD-10, MESH, SNOMED CT, NCI, and UMLS — all unauthenticated.

« Back to all skills