L
Lemma
API Reference

Search

POST/v1/search

Search FDA drug labels using natural language queries with phase-based semantic understanding.

Overview

The Search API enables semantic search across verified FDA drug labels. Use natural language queries to find relevant drug information, warnings, side effects, interactions, and contraindications.

Unlike traditional vector embeddings that use probabilistic similarity, Lemma uses phase-coherent semantic relationships for deterministic, reproducible search results. The same query always returns the same results in the same order.

Every result includes a 128-bit binary fingerprint for cryptographic verification, ensuring complete traceability back to official FDA sources.

Request Body

questionstringrequired

Natural language search question. Can be a question, phrase, or keywords related to drug information. The system uses semantic understanding to find relevant FDA label segments.

Example Queries:

•"aspirin side effects"
•"warfarin drug interactions"
•"contraindications for metformin"
•"what are the warnings for ibuprofen?"
•"pregnancy category for lisinopril"
top_kintegeroptional

Number of results to return (1-100). Controls how many FDA label segments are returned in the response.

Default: 10

Response Structure

Success responses follow a standard structure with status: 1, msg, and data containing the actual response payload.

statusinteger

Response status. 1 indicates success.

msgstring

Status message, typically "operation successful".

dataobject

The actual response data containing search results.

querystring

Echo of the original search question (returned as "query" in response).

resultsarray

Array of search results matching the query, ordered by relevance.

textstring

FDA label text segment - exact text from the official FDA source

fingerprintstring

128-bit binary fingerprint for cryptographic verification. Use this with the Verify API to prove this text came from FDA sources.

drugobject

Drug information

namestring

Generic drug name (lowercase)

brand_namesarray

Brand/trade names for this drug

manufacturerstring

Drug manufacturer/company name

ndcarray

National Drug Code identifiers - unique product identifiers assigned by FDA

routearray

Administration routes (e.g., "ORAL", "TOPICAL", "INTRAVENOUS")

sectionstring

FDA label section where this text was found (e.g., "Warnings", "Adverse Reactions", "Drug Interactions", "Contraindications", "Clinical Pharmacology")

sourceobject

Source information

urlstring

Official DailyMed URL for independent verification

metadataobject

Search metadata including result count and timing information.

countinteger

Number of results returned

search_time_msfloat

Search execution time in milliseconds

Use Cases

Clinical Decision Support

Search for drug warnings, contraindications, and adverse reactions to support clinical decision-making with verified FDA data.

Patient Education

Find side effects and usage instructions to educate patients with official FDA information.

Drug Information Lookup

Quick searches for specific drug properties - dosage, administration, storage, or any information found in FDA labels.

Regulatory Compliance

Generate compliance reports with cryptographically verifiable citations to FDA sources.

Search Tips

Use Natural Language

The search understands questions and phrases. You can ask "What are the side effects of aspirin?" or use keywords like "aspirin side effects" - both work well.

Be Specific

More specific queries return more relevant results. "warfarin bleeding risk" is better than just "warfarin".

Adjust top_k for Breadth

Use a higher top_k value (e.g., 50-100) when you want comprehensive results across multiple drugs or need to see all relevant warnings.

Error Responses

All error responses follow a standard structure with status: 0, errorCode, and msg fields:

400

Bad Request

Invalid request parameters (e.g., missing question, top_k out of range 1-100)

{ "status": 0, "errorCode": "", "msg": "invalid data" }
401

Unauthorized

Invalid or missing API key

{ "status": 0, "errorCode": "NotAuthorizedException", "msg": "unauthorized request" }
429

Rate Limit Exceeded

Too many requests. Wait before making additional requests.

{ "status": 0, "errorCode": "LimitExceededError", "msg": "api limit exceeded" }
500

Internal Server Error

Server error or service temporarily unavailable

{ "status": 0, "errorCode": "", "msg": "internal server error" }

Example: Verifying Search Results

Every search result includes a fingerprint that can be verified using the Verify API:

Python
# 1. Search for information
search_response = requests.post(
    "https://api.lemma.la/v1/search",
    headers={"x-api-key": api_key},
    json={"question": "aspirin warnings"}
)

response_data = search_response.json()
results = response_data['data']['results']
first_result = results[0]

print(f"Text: {first_result['text']}")
print(f"Fingerprint: {first_result['fingerprint']}")

# 2. Verify the fingerprint later
verify_response = requests.get(
    f"https://api.lemma.la/v1/verify/{first_result['fingerprint']}"
)

verification_data = verify_response.json()
verification = verification_data.get('data', verification_data)

if verification.get('verified'):
    print("✓ Citation verified!")
    print(f"Source: {verification['source']['url']}")
else:
    print(f"✗ Verification failed: {verification['message']}")
curl
curl -X POST https://api.lemma.la/v1/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LEMMA_API_KEY" \
  -d '{
    "question": "aspirin side effects"
  }'

Response

200 OK
{
  "status": 1,
  "msg": "operation successful",
  "data": {
    "query": "aspirin side effects",
    "results": [
    {
      "text": "Stop use and ask a doctor if pain gets worse or lasts more than 10 days, fever gets worse or lasts more than 3 days, you have difficulty swallowing, if ringing in the ears or loss of hearing occurs, redness or swelling is present in the painful area, any new symptoms appear.",
      "fingerprint": "11110011110101100001010001100111010000100001110011100000011111000100011110100100100100000011010111110000110000111000100001010010",
      "drug": {
        "name": "aspirin",
        "brand_names": ["Low Dose Aspirin Enteric Safety-Coated"],
        "manufacturer": "P & L Development, LLC",
        "ndc": ["59726-867"],
        "route": ["ORAL"]
      },
      "section": "Warnings",
      "source": {
        "url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=a7a6d3d0-0ff1-4f1e-8b5f-6e0b8c8d0e0a"
      }
    },
    {
      "text": "Allergy alert: Aspirin may cause a severe allergic reaction which may include: hives, facial swelling, shock, asthma (wheezing).",
      "fingerprint": "01010111100101011101000110011100101101100001001100111101100110001011010011011010101100110001101100010111010110101001001101010011",
      "drug": {
        "name": "aspirin",
        "brand_names": ["Aspirin"],
        "manufacturer": "Major Pharmaceuticals",
        "ndc": ["00904-2009"],
        "route": ["ORAL"]
      },
      "section": "Warnings",
      "source": {
        "url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=b8c3f5a2-1c4d-4e8f-9a7b-3d2e1f0c5a6b"
      }
    }
  ],
  "metadata": {
    "count": 10,
    "search_time_ms": 234.5
  }
}