Medication Search

Medication Search

DELPHOS provides a hybrid medication search endpoint that combines multiple matching signals — text similarity, keyword search, and trigram matching — to find medications from the CMED regulatory database. Use this endpoint when building prescription item selection UIs or resolving drug names to their database records.

Search Endpoint

POST /v1/medications/search

Only the query field is required. All other parameters have defaults suited for most use cases.

Request body

Field	Type	Required	Default	Description
query	string	Yes	—	Free-text search query in Portuguese (1-500 characters)
limit	integer	No	20	Maximum results to return (1-100)
threshold	float	No	0.50	Minimum similarity score (0.0-1.0)
tipo_produto	string	No	null	Filter by product type, e.g. "Similar", "Generico", "Referencia"
classe_terapeutica	string	No	null	Filter by exact therapeutic class string
atc_prefix	string	No	null	ATC hierarchical prefix filter (1-7 characters)

Status codes

Code	Meaning
200	Search completed — results may be empty
400	Invalid ATC prefix format
422	Request body validation error
500	Internal server error

curl

curl -X POST "https://your-instance.delphos.app/v1/medications/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "dipirona 500mg comprimido",
    "limit": 10,
    "threshold": 0.50
  }'

Python

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/medications/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "query": "dipirona 500mg comprimido",
        "limit": 10,
        "threshold": 0.50,
    },
)
data = response.json()
for med in data["results"]:
    print(med["substancia"], med["apresentacao"], med["pmc_17"])

---

Response shape

{
  "query": { ... },
  "results": [
    {
      "medication_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "codigo_ggrem": "123456789012345",
      "substancia": "DIPIRONA SODICA",
      "laboratorio": "LABORATORIO EXEMPLO LTDA",
      "produto": "DIPIRONA 500MG",
      "apresentacao": "500MG COM CT BL AL PLAS TRANS X 20",
      "tipo_produto": "Similar",
      "classe_terapeutica": "N2B - ANALGESICOS NAO NARCOTICOS",
      "pf_17": 8.50,
      "pmc_17": 10.20,
      "vector_score": 0.0,
      "bm25_score": 0.0,
      "rrf_score": 0.021
    }
  ],
  "total_results": 1,
  "search_method": "hybrid+reranker",
  "latency_ms": 87.3,
  "cached_embedding": true,
  "reranked": true
}

Result fields (MedicationSearchResult)

Field	Type	Description
medication_id	UUID	Database UUID of the medication
codigo_ggrem	string	CMED registry code
substancia	string	Active substance (drug name)
laboratorio	string	Laboratory or manufacturer name
produto	string	Product or brand name
apresentacao	string	Presentation details — dosage form, concentration, packaging
tipo_produto	string	Product type, e.g. "Similar", "Generico", "Referencia"
classe_terapeutica	string	Therapeutic class
pf_17	float	Factory price (PF 17%) in BRL
pmc_17	float	Maximum consumer price (PMC 17%) in BRL
rrf_score	float	Relevance score from the fused ranking (use for ordering)

Response envelope fields

Field	Type	Description
total_results	integer	Number of results in this response
search_method	string	"hybrid+reranker", "hybrid", or "bm25_fallback"
latency_ms	float	Total server-side search latency in milliseconds
cached_embedding	boolean	Whether the query embedding was served from cache
reranked	boolean	Whether cross-encoder reranking was applied

---

Filtering by ATC Code

Use atc_prefix to restrict results to a specific ATC hierarchy level. Pass a 1–7 character prefix; the search will return only medications whose therapeutic class starts with that code.

curl

curl -X POST "https://your-instance.delphos.app/v1/medications/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "anti-inflamatorio",
    "limit": 20,
    "atc_prefix": "M01A"
  }'

Python

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/medications/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "query": "anti-inflamatorio",
        "limit": 20,
        "atc_prefix": "M01A",
    },
)

Note

Returns 400 if the ATC prefix format is invalid. Valid prefixes are 1–7 alphanumeric characters matching the ATC classification hierarchy.

---

Using Search Results in Prescriptions

Once you identify the right medication, pass its medication_id as the cmed_medication_id when adding a prescription item:

import httpx

# Step 1: Search for the medication
search_resp = httpx.post(
    "https://your-instance.delphos.app/v1/medications/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"query": "amoxicilina 500mg capsula", "limit": 5},
)
top_result = search_resp.json()["results"][0]

# Step 2: Add the item to the prescription with the database link
item_resp = httpx.post(
    f"https://your-instance.delphos.app/v1/prescriptions/{prescription_id}/items",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "medication_name": top_result["produto"],
        "active_ingredient": top_result["substancia"],
        "dosage": "500mg",
        "route": "oral",
        "frequency": "8/8h",
        "duration": "7 dias",
        "quantity": 21,
        "unit": "capsulas",
        "cmed_medication_id": top_result["medication_id"],
    },
)