Skip to main content
POST
/
med-link
/
nel
/
link
curl --request POST \
  --url https://api.eka.care/med-link/nel/link \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "chest pain",
  "ontology": "snomed",
  "version": "20250401_extended",
  "top_k": 3
}
'
{
  "request_id": "0e95448d-7e32-44c9-8586-c33315412330",
  "query": "chest pain",
  "query_breakdown": null,
  "ontology": "snomed",
  "version": "20250401_extended",
  "index_name": "snomed_20250401_extended_c88b15811956d4fcb54da9ae_1bfcc90540_pg",
  "model_version": "c88b15811956d4fcb54da9ae6d14a733ac90e7a7",
  "results": [
    {
      "term_id": "29857009",
      "term_name": "Chest pain",
      "score": 1,
      "is_linked": true,
      "metadata": {
        "semantic_tag": "finding",
        "is_core": true,
        "source": "snomed_ct_20250401_extended",
        "language": "en",
        "script": "latin"
      }
    },
    {
      "term_id": "29857009",
      "term_name": "Chest pain (finding)",
      "score": 0.9494552299218054,
      "is_linked": true,
      "metadata": {
        "semantic_tag": "finding",
        "is_core": true,
        "source": "snomed_ct_20250401_extended",
        "language": "en",
        "script": "latin"
      }
    }
  ]
}

​
About this endpoint

POST /med-link/nel/link links a single free-text medical entity to candidate codes from the requested ontology. Pick the ontology and version from List Registry. Use the example selector above to see a request and response for each ontology.

​
The metadata field by ontology

metadata carries ontology-specific hints. It changes results for LOINC and medication, and is ignored by SNOMED CT and ICD-10-CM Comprehend.

​
SNOMED CT — snomed

No metadata required. Send the symptom, finding or disorder as the query. Each result’s metadata includes a semantic_tag (e.g. finding, disorder).

​
LOINC — loinc

metadata is strongly recommended — the lab test name alone is often ambiguous, and a unit or specimen decides which LOINC code is correct.
KeyTypeDescription
unitstringTest unit, e.g. g/dl, mg/dl, %. Most important hint.
valuestringNumeric result value. Improves value-type matching.
rangestringReference range for the result.
specimenstringSpecimen type, e.g. blood, urine.
specimen_textstringFree-text specimen description (auto-detected if omitted).
panel_namestringPanel name for multi-test panels.
extended_test_namestringExtended/alternate test name.
Without metadata, a LOINC query such as hemoglobin can link to the wrong specimen (e.g. urine instead of blood). Supplying unit and specimen lets the pipeline return is_linked: true against the correct code.

​
Medication — medication

metadata is optional — it helps resolve ambiguous brand names. The score field is null; read metadata.matching_breakdown and metadata.linking_requirements on each result instead.
KeyTypeDescription
formstringMedication form, e.g. tablet, capsule, injection.
generic_namestringGeneric / salt name of the drug.
dose_unitstringDosage unit, e.g. mg, mcg, ml.
dose_customstringCustom dosage string.

​
ICD-10-CM Comprehend — icd-10-cm (comprehend)

No metadata required. This version uses AWS Comprehend Medical, so it works well on natural-language clinical text. The response includes a query_breakdown with the detected entity, traits and attributes.

​
Reading the response

FieldDescription
results[]Candidate codes, ranked by relevance.
results[].term_idThe ontology code.
results[].is_linkedtrue when the pipeline is confident of a single correct match.
results[].scoreRelevance/confidence (null for medication).
query_breakdownHow the query was parsed (LOINC, medication, ICD-10-CM Comprehend; null for SNOMED CT).

Authorizations

​
Authorization
string
header
required

Bearer access token issued by the Eka authorization flow. See Authorization.

Body

application/json
​
query
string
required

Free-text medical entity to link.

Minimum string length: 1
Example:

"chest pain"

​
ontology
string
required

Ontology name. One of: snomed, loinc, medication, icd-10-cm.

Example:

"snomed"

​
version
string
required

Ontology version. Fetch valid values from GET /med-link/registry/.

Example:

"20250401_extended"

​
top_k
integer
default:5

Number of candidate results to return.

Required range: 1 <= x <= 10
​
metadata
object

Ontology-specific hints. Recommended for LOINC (unit, value, specimen, …) and optional for medication (form, generic_name, dose_unit, …). Ignored by SNOMED CT and ICD-10-CM Comprehend.

​
request_id
string | null

Optional request ID. Generated automatically if omitted.

Response

Candidate codes for the query, ranked by relevance.

​
request_id
string
required
​
query
string
required
​
results
object[]
required
​
ontology
string
required
​
version
string
required
​
index_name
string
required

The index that served the request.

​
query_breakdown
object

How the query was parsed. Present for LOINC, medication and ICD-10-CM Comprehend; null for SNOMED CT.

​
model_version
string | null