Rosetta Health Provider Search API

Authentication

API access requires an API key passed via the Authorization header. Keys are scoped per organization and environment (sandbox vs production).

Authorization: Bearer kvec_sk_live_your_api_key_here

Key Format

POST /api/search

The core endpoint. Accepts a plain-language symptom description and returns clinically-coded provider matches.

Request Body

Send a JSON body with the patient's symptom description.

{
  "query": "I get really bad headaches behind my eyes and feel nauseous",
  "limit": 5,
  "min_confidence": 0.3
}

Response

Returns clinical mappings and ranked providers. All responses include a success boolean.

Top-Level Fields

clinical_mapping Object

providers[] Object

Full Response Example

{
  "success": true,
  "results": {
    "query": "I get really bad headaches behind my eyes and feel nauseous",
    "method": "embedding",
    "latency_ms": 142,
    "clinical_mapping": {
      "primary_condition": {
        "id": "migraine-with-aura",
        "name": "Migraine with aura",
        "icd10": "G43.1",
        "snomed_ct": "37796009",
        "category": "neurological",
        "confidence": 0.97,
        "specialties": ["neurology", "headache-medicine"]
      },
      "detected_conditions": [
        { "id": "migraine-with-aura", "name": "Migraine with aura", "icd10": "G43.1", "confidence": 0.97 },
        { "id": "tension-headache", "name": "Tension-type headache", "icd10": "G44.2", "confidence": 0.72 }
      ]
    },
    "providers": [
      {
        "rank": 1,
        "confidence_score": 0.97,
        "reasoning": "Treats Migraine with aura · Neurology specialist · accepting new patients · 2.1mi away",
        "matched_conditions": [
          { "id": "migraine-with-aura", "name": "Migraine with aura", "icd10": "G43.1" }
        ],
        "matched_specialties": ["Neurology", "Headache Medicine"],
        "provider": {
          "id": "provider-001",
          "name": "Dr. Sarah Chen",
          "credentials": "MD, FAHS",
          "title": "Neurologist",
          "specialties": ["Headache & Migraine", "Epilepsy", "Neuropathic Pain"],
          "location": { "city": "Midtown", "state": "NY", "distance_miles": 2.1 },
          "accepting_patients": true,
          "languages": ["English", "Mandarin"],
          "insurance": ["Aetna", "BlueCross BlueShield", "UnitedHealthcare"],
          "rating": 4.9,
          "review_count": 284,
          "next_available": "2 days",
          "npi": "1234567890",
          "gender": "F"
        }
      }
    ],
    "metadata": {
      "total_providers_evaluated": 5,
      "total_conditions_evaluated": 25,
      "embedding_model": "text-embedding-3-small",
      "version": "1.0.0-demo"
    }
  }
}

Error Handling

All error responses include success: false and an error message.

{
  "success": false,
  "error": "Missing or invalid \"query\" field. Provide a symptom description string."
}

Clinical Mapping

Rosetta Health translates plain-language symptom descriptions into standardized clinical codes using embedding-based semantic matching.

How It Works

Each clinical condition in the Rosetta Health knowledge base includes:

• Clinical description — medical terminology used by practitioners
• Patient language model — how real patients describe the condition
• ICD-10-CM code — standard billing and diagnosis code
• SNOMED-CT code — international clinical terminology identifier
• Specialty mapping — which medical specialties treat this condition

Supported Clinical Categories

Keyword Fallback

If the embedding engine is temporarily unavailable, Rosetta Health falls back to keyword-based matching. The response method field indicates which engine was used: "embedding" or "keyword". Embedding-based matching is significantly more accurate for natural language queries.

Provider Matching

After clinical conditions are identified, Rosetta Health scores each provider based on two factors combined into a single confidence score.

Confidence Score Calculation

Each provider's confidence_score is a weighted composite:

Match Reasoning

Each provider result includes a reasoning string that explains the match in human-readable format. This can be displayed directly to end users:

"Treats Migraine with aura · Neurology specialist · accepting new patients · 2.1mi away"

Provider Data

Each provider record includes rich metadata for display in your UI:

• Demographics — name, credentials, title, gender, NPI
• Clinical — subspecialties, treated conditions, bio
• Access — location, distance, accepting status, next availability
• Patient experience — rating, review count, languages
• Insurance — accepted plans (filterable on your end)

Quick Start

Make your first API call in under a minute. The demo endpoint is live and requires no authentication.

curl -X POST https://kvecos.polsia.app/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "my knee hurts when I walk up stairs"}'

That's it. You'll get back clinical code mappings and ranked providers in a single JSON response.

Code Examples

Copy-paste examples in JavaScript, Python, and cURL.

// Rosetta Health Provider Search — JavaScript
const BASE_URL = 'https://kvecos.polsia.app';

async function searchProviders(symptoms, options = {}) {
  const response = await fetch(`${BASE_URL}/api/search`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // 'Authorization': 'Bearer kvec_sk_live_...'  // when using API key
    },
    body: JSON.stringify({
      query: symptoms,
      limit: options.limit || 5,
      min_confidence: options.min_confidence || 0.3
    })
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error(data.error || 'Search failed');
  }

  return data.results;
}

// Example usage
const results = await searchProviders(
  'I get really bad headaches behind my eyes and feel nauseous'
);

// Primary clinical mapping
console.log(results.clinical_mapping.primary_condition);
// → { name: "Migraine with aura", icd10: "G43.1", snomed_ct: "37796009", confidence: 0.97 }

// Top provider
console.log(results.providers[0]);
// → { rank: 1, confidence_score: 0.97, provider: { name: "Dr. Sarah Chen", ... } }

# Rosetta Health Provider Search — Python
import requests

BASE_URL = "https://kvecos.polsia.app"

def search_providers(symptoms, limit=5, min_confidence=0.3):
    response = requests.post(
        f"{BASE_URL}/api/search",
        json={
            "query": symptoms,
            "limit": limit,
            "min_confidence": min_confidence,
        },
        headers={
            "Content-Type": "application/json",
            # "Authorization": "Bearer kvec_sk_live_..."  # when using API key
        },
    )
    response.raise_for_status()
    data = response.json()

    if not data["success"]:
        raise Exception(data.get("error", "Search failed"))

    return data["results"]


# Example usage
results = search_providers(
    "I get really bad headaches behind my eyes and feel nauseous"
)

# Primary clinical mapping
primary = results["clinical_mapping"]["primary_condition"]
print(f"Condition: {primary['name']} (ICD-10: {primary['icd10']})")
# → Condition: Migraine with aura (ICD-10: G43.1)

# Top provider
top = results["providers"][0]
print(f"Best match: {top['provider']['name']} (score: {top['confidence_score']})")
# → Best match: Dr. Sarah Chen (score: 0.97)

# Basic search
curl -X POST https://kvecos.polsia.app/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I get really bad headaches behind my eyes and feel nauseous",
    "limit": 5
  }'

# With minimum confidence threshold
curl -X POST https://kvecos.polsia.app/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "my knee hurts when I walk up stairs and feels stiff",
    "limit": 3,
    "min_confidence": 0.5
  }'

# With API key (production)
curl -X POST https://kvecos.polsia.app/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kvec_sk_live_your_key_here" \
  -d '{
    "query": "heart feels like it is skipping beats",
    "limit": 5
  }'

# Pretty-print with jq
curl -s -X POST https://kvecos.polsia.app/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "always thirsty, peeing all the time"}' | jq '.'

Rate Limits & SLAs

Rate Limit Details

Latency

• Cold start — First request after deploy: ~2–3 seconds (embedding warmup)
• Warm requests — Subsequent requests: <500ms p95
• Embedding engine — Uses OpenAI text-embedding-3-small for vector matching

HIPAA Compliance

Rosetta Health is designed for HIPAA-compliant deployments. In production:

• No PHI is logged or stored by default
• All data in transit uses TLS 1.2+
• BAA (Business Associate Agreement) available for enterprise plans
• Search queries are not used for model training

Ready to integrate?

Get sandbox credentials and start building. We'll have you live in days, not months.