SNOMED CT Terminology

Return a parsed FHIR CapabilityStatement summary for a terminology's backend. Set include_raw=true (default) to also include the raw CapabilityStatement payload. Optionally specify terminology and/or target; defaults to the server's default terminology.

fhir_metadata

List the SNOMED CT editions and branches available on the connected server. WHEN TO USE: before running edition-specific queries to confirm available terminology keys, checking which release version is loaded, or verifying server connectivity.

list_terminologies

Retrieve full concept details via FHIR CodeSystem/$lookup for a known SNOMED CT concept ID. Returns the FSN, synonyms, parent concepts, and all defining attributes with their values. WHEN TO USE: verifying a concept ID before using it in an ECL expression, inspecting the full attribute modelling of a specific concept, retrieving all synonyms and descriptions for a concept, checking whether a concept is active or inactive, or confirming the correct concept ID for a common attribute (e.g. finding site). If the code does not exist, returns found=false with a message (not an error). NOT FOR: searching by text (use snomed_expand with a {{ term = "..." }} filter) or retrieving a concept set (use snomed_expand with ECL). ACCEPTABILITY: FHIR designations do not say whether a term is preferred or acceptable. Set include_acceptability=true whenever the user asks about preferred terms, acceptable synonyms, translations or a national edition's terms; the response then adds 'descriptions', each with its language, per-refset 'acceptability' and 'edition_acceptability' (PREFERRED/ACCEPTABLE in the edition's own language refsets). Optionally specify terminology (e.g. 'snomedct-us') and/or target; defaults to the server's default terminology when omitted.

snomed_lookup

Expand a SNOMED CT value set using FHIR ValueSet/$expand. The primary tool for retrieving concept sets via ECL (Expression Constraint Language) queries. Works on Snowstorm and Lite when FHIR is available. WHEN TO USE: retrieving concepts matching an ECL expression (most common use case), getting members of a reference set, counting concepts in a subhierarchy (use summary_only=true), text-filtering within a concept set, or retrieving attribute values across a concept set (dotted notation). VALUE SET URL FORMAT: Subtype query: http://snomed.info/sct?fhir_vs=ecl/<<CONCEPTID Attribute query: http://snomed.info/sct?fhir_vs=ecl/<<CONCEPTID:ATTR=<<VALUE Refset members: http://snomed.info/sct?fhir_vs=ecl/^REFSETID Full ECL: http://snomed.info/sct?fhir_vs=ecl/<YOUR ECL EXPRESSION> PERFORMANCE RULES (follow on every query): These rules protect the server from overload. Violating them causes timeouts, degraded performance, and may affect other users on shared infrastructure. 1. SCOPE FIRST. Never root a constrained query at a top-level hierarchy concept without narrowing scope first. These roots are TOO BROAD on their own: <<404684003 Clinical finding (~350k concepts) <<71388002 Procedure (~100k concepts) <<105590001 Substance (~70k concepts) <<123037004 Body structure (~40k concepts) Always narrow to a subhierarchy (e.g. <<195967001 Asthma) before adding attribute constraints, filters, or MINUS operations. 2. COUNT BEFORE FETCHING. Always use summary_only=true as the first call to check the total size. If total > 1000, stop and confirm with the user before fetching pages. Never assume a result set is small. 3. DO NOT PAGINATE AUTONOMOUSLY. Fetch the first page, summarise the results, and ask the user whether they need more. Never loop through all pages of a large result set without explicit user instruction. 4. NO TOP-LEVEL MINUS ON LARGE SETS. X MINUS Y at the top level requires materialising both sets in full and will time out on large hierarchies. Always prefer MINUS inside an attribute value expression: GOOD: <<X:{attr=(<<A MINUS <<B)} BAD: (<<X:attr=<<A) MINUS (<<X:attr=<<B) 5. NO WILDCARD QUERIES ON LARGE SETS. Expressions like <<404684003:*=* or <<71388002:attr=* against top-level hierarchies are extremely expensive. Scope to a subhierarchy before using wildcards. 6. NO RECURSIVE CHILDREN CALLS. Never call snomed_get_children in a loop to traverse a hierarchy. Use <<CONCEPTID ECL for transitive closure in one call. 7. NO REPEATED snomed_lookup ACROSS A CONCEPT SET. Use dotted attribute notation (<<X.attrId) to retrieve attribute values across a set in one call instead of calling snomed_lookup for each concept individually. ECL QUICK REFERENCE: Hierarchy operators: <<X Subtype of X (including X) <X Strict subtype of X (excluding X) >>X Supertype of X (including X) >!X Direct parents of X only (ECL 1.4) <!X Direct children of X only (ECL 1.4) ^X Member of reference set X Set operators (use at top level between expressions): X OR Y Union X AND Y Intersection X MINUS Y Difference WARNING: Top-level MINUS between two large expansions will TIME OUT. Prefer MINUS inside an attribute value expression instead. Attribute constraints: <<X : attr=<<Y Ungrouped (attribute may be in any role group) <<X : {attr1=<<Y, attr2=<<Z} Grouped (BOTH attributes in the SAME role group) WARNING: Grouped vs ungrouped returns DIFFERENT results. Always choose deliberately. MINUS inside attribute value (PREFERRED for performance): <<X : {246075003=(<<105590001 MINUS <<410942007), 363698007=<<80891009} Wildcards: <<X : *=<<Y Any attribute with value Y <<X : attr=* Any value for a specific attribute CARDINALITY (constrain how many times an attribute appears): <<X : [0..0] attr=* Concepts with NO instances of attr (content QA) <<X : [1..1] {attr=<<Y} Exactly one instance of attr in the same role group <<X : [2..*] {attr=*} Two or more instances of attr NOTE: [0..0] does not require braces. [1..*] and above should use grouped syntax { }. DOTTED ATTRIBUTE NOTATION (returns attribute VALUES, not filtered concepts): <<X . attrId Returns the SET OF VALUES of attrId across all subtypes of X This is the INVERSE of filtering: it returns destination concepts, not source. Use for: exploring attribute value ranges, building value set pickers, content coverage analysis, verifying modelling scope. DESCRIPTION FILTERS (ECL 1.5/1.6): <<X {{ term = "mild" }} Concepts with "mild" in any description <<X {{ term = "mild", language = en }} English descriptions only <<X {{ typeId = 900000000000003001 }} FSN filter <<X {{ typeId = 900000000000013009 }} Synonym filter Multiple filters are ANDed together. CONCEPT FILTERS (ECL 1.6): <<X {{ active = false }} Inactive concepts only <<X {{ active = true }} Active concepts only (default) <<X {{ effectiveTime > "20200101" }} Modified after Jan 2020 (YYYYMMDD) <<X {{ effectiveTime = "20230901" }} Exact release date <<X {{ effectiveTime >= "20200101", effectiveTime <= "20231001" }} Date range NOTE: Concept filters on very large sets will TIME OUT. Scope first. HISTORY SUPPLEMENTS (ECL 2.0): NOT SUPPORTED on this server (returns HTTP 500). Use snomed_validate_code to check individual inactive codes instead. FUZZY MATCHING: Set fuzzy=true to enable approximate/fuzzy matching on the filter text for misspelled or partial terms (Snowstorm Lite only; silently ignored on full Snowstorm). PAGINATION: ALWAYS use summary_only=true first to check total before fetching. If total > 1000, confirm with user before paginating. Default count=20. Raise explicitly for larger pages. max_contains caps the internal buffer (default 100). Use offset for pagination. EXAMPLES: Count respiratory disorders first (always do this before fetching): value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<50043002', summary_only=true All subtypes of Asthma: value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<195967001' Disorders by finding site (heart), ungrouped: value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<404684003:363698007=<<80891009' Disorders caused by substance on heart, grouped (same role group): value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<404684003:{246075003=<<105590001,363698007=<<80891009}' Excluding drug-caused (MINUS in attribute value, no timeout): value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<404684003:{246075003=(<<105590001 MINUS <<410942007),363698007=<<80891009}' Concepts added to asthma hierarchy since Jan 2020: value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<195967001 {{ effectiveTime > "20200101" }}' Inactive asthma concepts (for EHR legacy code handling): value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<195967001 {{ active = false }}' Asthma concepts with "mild" in any description: value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<195967001 {{ term = "mild" }}' Finding sites across all asthma subtypes (dotted notation, one call not many lookups): value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<195967001.363698007' Clinical findings with exactly one cardiac finding site: value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<404684003:[1..1]{363698007=<<80891009}' Clinical findings with NO finding site modelled (content QA): value_set_url='http://snomed.info/sct?fhir_vs=ecl/<<404684003:[0..0]363698007=*' Reference set members: value_set_url='http://snomed.info/sct?fhir_vs=ecl/^723264001'

snomed_expand

Get ancestor concepts of a SNOMED concept (parents, grandparents, etc. via IS-A hierarchy). Traverses upward through IS-A to find the classification position of a concept. Set direct_only=true to return only immediate parents. Optionally specify terminology and/or target; defaults to the server's default terminology.

snomed_get_ancestors

Get direct IS-A children of a SNOMED concept (one level down in the hierarchy). More efficient than ECL for simple hierarchy browsing when you only need immediate children. WHEN TO USE: exploring the shape of a subhierarchy before writing an ECL query, understanding how a concept is subdivided at the next level, or lightweight hierarchy browsing without full ECL overhead. NOT FOR: transitive closure (all descendants) — use snomed_expand with <<CONCEPTID. Not for attribute-based queries — use snomed_expand with ECL. Not for filtering by description or metadata — use snomed_expand with filters. Optionally specify terminology and/or target; defaults to the server's default terminology.

snomed_get_children

Get all descendant concepts of a SNOMED concept (children, grandchildren, etc. via IS-A hierarchy). Transitive closure downward, equivalent to <<X in ECL but returned as a hierarchy structure. Use snomed_expand with ECL if you need a flat concept list with attribute constraints instead. Use count and offset to paginate large result sets. Optionally specify terminology and/or target; defaults to the server's default terminology.

snomed_get_descendants

FHIR CodeSystem/$subsumes for two SNOMED codes. Optionally specify terminology and/or target; defaults to the server's default terminology.

snomed_subsumes

Validate whether a SNOMED CT concept ID exists and is currently active via FHIR CodeSystem/$validate-code. Returns true/false with the display name if valid and active. WHEN TO USE: confirming a concept ID is valid and active before storing or querying, checking whether a concept has been inactivated (retired/replaced), handling legacy codes from EHR data (check status before using in ECL), or verifying a code belongs to a specific edition or version. Preferred approach when history supplements are unavailable (they are NOT supported on this server). Use this to check individual inactive codes instead. Optionally specify terminology and/or target; defaults to the server's default terminology.

snomed_validate_code

Return backend classification and capabilities for a terminology. Optionally specify terminology and/or target; defaults to the server's default terminology.

server_capabilities