Semantic search (embedding-based)

GET/construe/codes/{codesystem}/search/semantic

Performs semantic similarity search using vector embeddings.

Availability: This endpoint works for both built-in and custom code systems.

When to use: Best for natural language queries where you want to find conceptually related codes, even when different terminology is used. The search understands meaning, not just keywords.

Examples:

Query "trouble breathing at night" finds codes like "Sleep apnea", "Orthopnea", "Nocturnal dyspnea" — semantically related but no exact keyword matches
Query "heart problems" finds "Myocardial infarction", "Cardiac arrest", "Arrhythmia"

Trade-offs: Slower than text search (requires embedding generation), but finds conceptually similar results that keyword search would miss.

See also: /search/text for faster keyword-based lookup with typo tolerance.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

RequiresBearerauthentication

Path parameters

codesystemstringrequired

Code system name

Query parameters

textstringrequired

Natural language text to find semantically similar codes for

versionstringoptional

Specific version of the code system, such as umls-2026aa.

limitintegeroptionaldefault 10

Maximum number of results (default 10, max 50)

Returns

Semantic search results ordered by similarity

Response fields

systemobjectrequired

namestringrequired

Code system name

versionstringrequired

Code system version

resultsobject[]required

Codes ordered by semantic similarity (most similar first)

codestringrequired

descriptionstringrequired

GETRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X GET "https://experiment.app.pheno.ml/construe/codes/ICD-10-CM/search/semantic?text=patient%20has%20trouble%20breathing%20at%20night%20and%20wakes%20up%20gasping&limit=5" \
  -H "Authorization: Bearer $PHENOML_TOKEN"

200 OKExample Response

{
  "system": {
    "name": "ICD-10-CM",
    "version": "2025"
  },
  "results": [
    {
      "code": "R06.00",
      "description": "Dyspnea, unspecified"
    },
    {
      "code": "R06.01",
      "description": "Orthopnea"
    },
    {
      "code": "G47.33",
      "description": "Obstructive sleep apnea"
    },
    {
      "code": "R06.83",
      "description": "Snoring"
    },
    {
      "code": "J45.20",
      "description": "Mild intermittent asthma, uncomplicated"
    }
  ]
}