# Salvio API

> OTC product-data infrastructure. A REST API for structured over-the-counter
> medication data: product search, brand-to-generic equivalence, ingredient
> label analysis, and NDC/UPC barcode resolution. Responses are informational
> product data sourced from FDA labeling and are not medical advice.

## Getting started

- Base URL: https://api.salvio.health/v1
- Machine-readable spec (OpenAPI 3.1): https://salvio.health/openapi.json
- Authentication: send your API key as a bearer token `Authorization: Bearer sk_...`
  (required in production; the health endpoint is open).
- All responses are JSON. Errors include an `error` message and often a `suggestion`.

## Endpoints

- GET https://api.salvio.health/v1/health — service health and product count.
- GET https://api.salvio.health/v1/products/search?q={query} — full-text product search;
  filters: dosage_form, labeler_type, exclude_homeopathic, page, per_page.
- GET https://api.salvio.health/v1/products/{identifier} — look up a product by NDC or UPC.
- GET https://api.salvio.health/v1/products/{identifier}/equivalents — products with the same
  active ingredients, strength, and dosage form (store brands first).
- POST https://api.salvio.health/v1/ingredients/analyze — analyze ingredient strings; returns
  parsed ingredients, matched products, and informational-only safety notes.
  Body: {"ingredients": ["ACETAMINOPHEN 500 MG", "IBUPROFEN 200 MG"]}
- GET https://api.salvio.health/v1/scan/{barcode} — resolve a UPC/EAN barcode to a product
  (with source + confidence). OpenFDA UPC coverage is partial (~34%). On a
  catalog miss the response may carry an attributed external_match (descriptive
  data from an external barcode database; product stays null — no FDA label data).
- GET https://api.salvio.health/v1/categories — therapeutic categories with product counts.
- GET https://api.salvio.health/v1/equivalence-groups?min_members={n} — browse equivalence
  groups (which OTC products have the most generic/store-brand alternatives).
- GET https://api.salvio.health/v1/stats — database counts, labeler breakdown, top groups.
- GET https://api.salvio.health/v1/ingredients?q= — search canonical active-ingredient names.
- GET https://api.salvio.health/v1/ingredients/{name}/products — products containing an active
  ingredient, with relationship filters: strength (specific dose, or omit for any),
  composition=single|combination|all, labeler_type, plus allergen filters
  free_of= and contains_allergen= (comma-separated codes). Also returns the distinct
  doses the ingredient appears at. The core cross-linking primitive.
- GET https://api.salvio.health/v1/allergens — tracked allergen/sensitivity codes (dye, gluten,
  lactose, gelatin, soy, sulfites, ...) with product counts; use the codes with the
  free_of / contains_allergen filters above. Products with no inactive-ingredient
  data are treated as unknown (never reported as "free of").
- GET https://api.salvio.health/v1/symptoms — symptom taxonomy: stable ids + labels, grouped, with
  the selectable age ranges (age_bands). Each symptom maps to the active
  ingredients that FDA OTC monographs or FDA-approved OTC labeling list for that
  indication (informational only — "labeled for", never a recommendation).
- GET https://api.salvio.health/v1/symptoms/{id} — the FDA-labeled ingredients for one symptom
  (primary + alternate lines, regulatory sources, informational flags, typical
  label age minimums, pediatric availability). Filters: age_band= (range id from
  /symptoms — recommended) or age= (exact years).
- GET https://api.salvio.health/v1/symptoms/{id}/products — convenience join: catalog products per
  qualifying ingredient. Filters: age_band/age, line=primary|all, labeler_type,
  free_of, per_page (per ingredient, max 25).

## Interactive

- https://salvio.health/#demo — a live, capped (5-result) demo of the ingredient graph on the
  home page: search an ingredient or product and traverse equivalents, doses, and
  combinations.
- https://salvio.health/docs — interactive API docs with per-endpoint "try it" panels showing
  the request and JSON response, plus the same capped explorer.

## MCP server (for AI agents)

A Model Context Protocol server is available at https://api.salvio.health/api/mcp (Streamable HTTP) — point
any MCP-compatible client at that URL. All twelve tools are read-only and
informational-only:
- salvio_search_products — full-text product search
- salvio_get_product — look up by NDC or UPC
- salvio_get_equivalents — equivalent products (same active ingredients)
- salvio_analyze_ingredients — analyze an ingredient list
- salvio_resolve_barcode — resolve a UPC/EAN barcode
- salvio_list_equivalence_groups — browse equivalence groups
- salvio_search_ingredients — search canonical active-ingredient names
- salvio_products_by_ingredient — products containing an ingredient (free_of / contains_allergen)
- salvio_list_allergens — list tracked allergen/sensitivity codes
- salvio_list_symptoms — symptom taxonomy + age bands
- salvio_get_symptom — FDA-labeled ingredients for a symptom (age filter)
- salvio_symptom_products — catalog products per labeled ingredient

## Notes

- Equivalence and barcode results carry confidence scores and source attribution.
- "Equivalent" means the same active ingredients, strength, and dosage form — not
  a clinical substitution recommendation.