{"openapi":"3.1.0","info":{"title":"TestWell Agent API","version":"1.1.0","description":"Cash-pay lab tests without insurance: search TestWell's catalog, get all-in quotes by state (Quest, Labcorp, BioReference in NY/NJ), find draw sites by ZIP, look up physician-reviewed reference ranges, convert units, calculate free testosterone, compare providers and read guides. Read-only; purchases complete on test-well.com.\n\nPricing rule: sticker prices plus one flat $6.00 lab processing fee per order. All endpoints are public, read-only and rate limited (120 requests/minute/IP).","contact":{"name":"TestWell","url":"https://www.test-well.com/developers","email":"support@test-well.com"},"termsOfService":"https://www.test-well.com/terms"},"servers":[{"url":"https://www.test-well.com"}],"externalDocs":{"url":"https://www.test-well.com/developers","description":"Developer documentation"},"x-mcp":{"url":"https://www.test-well.com/mcp","serverCard":"https://www.test-well.com/.well-known/mcp/server-card.json"},"paths":{"/api/catalog.json":{"get":{"operationId":"listCatalog","summary":"List TestWell's public tests and panels with per-lab prices","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search keyword, biomarker or CPT code"},{"name":"type","in":"query","schema":{"type":"string","enum":["test","panel"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"orderable","in":"query","schema":{"type":"boolean"},"description":"true to exclude coming-soon items"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Catalog page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}}}}},"/api/catalog/{slug}":{"get":{"operationId":"getCatalogItem","summary":"One test or panel by slug or id","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogItem"}}}},"404":{"description":"Unknown or non-public item"}}}},"/api/agent/search_tests":{"post":{"operationId":"search_tests","summary":"Search the TestWell catalog","description":"Search TestWell's public catalog of cash-pay lab tests and panels by keyword, biomarker, CPT code, or category. Returns name, slug, per-lab prices, sample, fasting, turnaround and order URL. Prices are stickers; every order adds one $6 lab processing fee (see quote_order for all-in totals).","tags":["catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":120,"description":"Keyword, biomarker, CPT code or health goal, e.g. 'vitamin d', 'TSH', '80053', 'cholesterol'"},"type":{"description":"Restrict to individual tests or bundled panels","type":"string","enum":["test","panel"]},"category":{"description":"Catalog category, e.g. 'Thyroid', 'Heart Health'","type":"string","maxLength":60},"orderableOnly":{"description":"Exclude items listed as coming soon (default true)","type":"boolean"},"limit":{"description":"Max results (default 10)","type":"integer","minimum":1,"maximum":50},"lang":{"description":"Return Spanish names/descriptions where a translation exists (default en)","type":"string","enum":["en","es"]}},"required":["query"]},"examples":{"example1":{"summary":"Find the 25-hydroxy vitamin D test and panels that include it","value":{"query":"vitamin d"}},"example2":{"summary":"Thyroid panels only","value":{"query":"thyroid","type":"panel","limit":5}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/get_test":{"post":{"operationId":"get_test","summary":"Get a test or panel","description":"Full public detail for one TestWell test or panel by slug or id: description, biomarkers, CPT, per-lab prices, labs, fasting/prep, turnaround, included tests (panels), FAQ, related conditions, order URL and a Markdown page URL.","tags":["catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":120,"description":"Catalog slug (from search_tests) or id, e.g. 'tsh', 'general-wellness-panel'"},"lang":{"description":"Spanish prose where a translation exists (default en)","type":"string","enum":["en","es"]}},"required":["slug"]},"examples":{"example1":{"summary":"The annual-checkup panel with its four included tests","value":{"slug":"general-wellness-panel"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/list_panels":{"post":{"operationId":"list_panels","summary":"List panels","description":"List TestWell's bundled panels (multi-test packages priced below the sum of their tests), optionally filtered by category or maximum price. Sorted by price.","tags":["catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"description":"Catalog category, e.g. 'Hormones', 'General Health'","type":"string","maxLength":60},"maxPrice":{"description":"Only panels at or under this sticker price (USD)","type":"number","exclusiveMinimum":0},"limit":{"description":"Max results (default 25)","type":"integer","minimum":1,"maximum":100}}},"examples":{"example1":{"summary":"Panels under $100","value":{"maxPrice":100}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/recommend_tests":{"post":{"operationId":"recommend_tests","summary":"Recommend tests for goals or symptoms","description":"Suggest TestWell panels and tests for stated health goals (e.g. 'annual checkup', 'heart health', 'TRT monitoring') and/or symptoms (e.g. 'fatigue', 'hair loss'). Prefers a curated pre-built panel when one fits; otherwise assembles individual tests within a budget. Educational matching, not a diagnosis.","tags":["catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goals":{"description":"Health goals, e.g. ['energy', 'thyroid']","maxItems":8,"type":"array","items":{"type":"string","maxLength":60}},"symptoms":{"description":"Symptoms, e.g. ['always cold', 'weight gain']","maxItems":8,"type":"array","items":{"type":"string","maxLength":60}},"budget":{"description":"Budget band: low ≈ $80, medium ≈ $200, high ≈ $400","type":"string","enum":["low","medium","high","no_limit"]}}},"examples":{"example1":{"summary":"Returns the General Wellness Panel","value":{"goals":["annual checkup"],"budget":"low"}},"example2":{"summary":"Symptom mapping to ferritin, thyroid, vitamin D and matching panels","value":{"symptoms":["fatigue","hair loss"]}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/quote_order":{"post":{"operationId":"quote_order","summary":"All-in order quote","description":"Price a set of tests/panels exactly as TestWell's checkout would: per-lab prices for the user's state (New York and New Jersey route to BioReference; Rhode Island is not served), the single $6 lab processing fee, the total, items that can't be ordered and why, and a prefilled cart URL. Use this before quoting any total to a user.","tags":["quote"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"description":"Catalog slugs or ids, e.g. ['tsh', 'vitamin-d']"},"state":{"description":"US state code or name where the user will be drawn, e.g. 'FL' or 'Florida'","type":"string","minLength":2,"maxLength":40},"lab":{"description":"Preferred lab outside NY/NJ (default quest)","type":"string","enum":["quest","labcorp","bioreference"]}},"required":["items"]},"examples":{"example1":{"summary":"Two tests in Florida at Quest","value":{"items":["tsh","vitamin-d"],"state":"FL","lab":"quest"}},"example2":{"summary":"Routed to BioReference with its price","value":{"items":["general-wellness-panel"],"state":"NY"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/find_draw_sites":{"post":{"operationId":"find_draw_sites","summary":"Find draw sites near a ZIP","description":"Find Quest Diagnostics, Labcorp and BioReference patient service centers near a US ZIP code, with address, distance, phone and hours. Walk-ins are accepted at most sites; the requisition arrives by email after physician authorization.","tags":["locations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zip":{"type":"string","pattern":"^\\d{5}$","description":"5-digit US ZIP code"},"radiusMiles":{"description":"Search radius in miles (snapped to 10/20/25/50/100; default 25)","type":"integer","minimum":5,"maximum":100},"lab":{"description":"Limit to one lab","type":"string","enum":["quest","labcorp","bioreference"]},"limit":{"description":"Max sites (default 10)","type":"integer","minimum":1,"maximum":50}},"required":["zip"]},"examples":{"example1":{"summary":"Sites near Fort Lauderdale","value":{"zip":"33301","radiusMiles":10}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/lookup_reference_range":{"post":{"operationId":"lookup_reference_range","summary":"Reference range for a biomarker","description":"Physician-reviewed reference range for a blood test marker (130+ markers), filtered by sex and age when they matter, with what high and low values suggest, retest cadence, how to get tested, cited sources and the review date. Educational; the user's own report range takes precedence.","tags":["reference"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"marker":{"type":"string","minLength":1,"maxLength":80,"description":"Marker name or alias, e.g. 'TSH', 'ferritin', 'HbA1c', 'LDL'"},"sex":{"type":"string","enum":["male","female"]},"age":{"type":"integer","minimum":0,"maximum":120},"pregnancy":{"type":"boolean"},"postmenopausal":{"type":"boolean"}},"required":["marker"]},"examples":{"example1":{"summary":"Sex-specific ferritin band","value":{"marker":"ferritin","sex":"female","age":34}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/compare_prices":{"post":{"operationId":"compare_prices","summary":"Compare all-in prices across providers for a test","description":"For one blood test, the all-in single-test price (sticker + per-order fees) at TestWell and at every tracked direct-to-consumer provider with a verified equivalent — JustLabs, Quest, Labcorp OnDemand, Ulta Lab Tests, Walk-In Lab, HealthLabs and more — each with the date it was verified, plus typical hospital self-pay and Quest Direct reference prices. States the multi-test caveat (fees are paid once per order). Source: the TestWell Blood Test Price Index (CC BY 4.0).","tags":["compare"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"string","minLength":1,"maxLength":80,"description":"Test slug or name, e.g. 'tsh', 'lipid panel', 'vitamin-d'"}},"required":["test"]},"examples":{"example1":{"summary":"TSH all-in at TestWell vs JustLabs, Quest, Labcorp and others","value":{"test":"tsh"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/interpret_results":{"post":{"operationId":"interpret_results","summary":"Explain lab results against reviewed reference ranges","description":"Flag each pasted lab value as low / normal / high against TestWell's physician-reviewed reference catalog (130+ markers; sex- and age-specific bands where they exist), with the reviewed 'what high/low suggests' copy, retest guidance, cited sources and links to the marker's page and, where one exists, its high/low interpretation page. Stateless — values are not stored or logged. Educational, not a diagnosis; the user's own report range takes precedence.","tags":["reference"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"object","properties":{"marker":{"type":"string","minLength":1,"maxLength":80},"value":{"type":"number"},"unit":{"type":"string","maxLength":20}},"required":["marker","value"]},"description":"Results to explain, e.g. [{marker:'TSH', value:5.2, unit:'mIU/L'}, {marker:'ferritin', value:12}]"},"sex":{"type":"string","enum":["male","female"]},"age":{"type":"integer","minimum":0,"maximum":120},"pregnancy":{"type":"boolean"},"postmenopausal":{"type":"boolean"}},"required":["values"]},"examples":{"example1":{"summary":"Two results flagged against sex-specific bands","value":{"values":[{"marker":"TSH","value":5.2,"unit":"mIU/L"},{"marker":"ferritin","value":12,"unit":"ng/mL"}],"sex":"female","age":34}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/convert_units":{"post":{"operationId":"convert_units","summary":"Convert lab units","description":"Convert a lab value between US conventional and SI units for 30 common analytes (glucose, cholesterol, testosterone, vitamin D, …) using published factors; hemoglobin A1c uses the NGSP↔IFCC master equation and also returns estimated average glucose.","tags":["reference"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"analyte":{"type":"string","minLength":1,"maxLength":60,"description":"Analyte slug or name, e.g. 'glucose', 'total-cholesterol', 'testosterone', 'vitamin-d', 'a1c'"},"value":{"type":"number","description":"The numeric value to convert"},"direction":{"description":"Default toSI (US → SI)","type":"string","enum":["toSI","toConventional"]}},"required":["analyte","value"]},"examples":{"example1":{"summary":"100 mg/dL → 5.55 mmol/L","value":{"analyte":"glucose","value":100}},"example2":{"summary":"5.7% → 39 mmol/mol, eAG 117 mg/dL","value":{"analyte":"a1c","value":5.7}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/calculate_free_testosterone":{"post":{"operationId":"calculate_free_testosterone","summary":"Calculate free testosterone (Vermeulen)","description":"Calculate free and bioavailable testosterone from total testosterone, SHBG and albumin using the Vermeulen (1999) mass-action equation — the method behind lab-reported 'calculated free testosterone'. Educational; not a diagnosis.","tags":["reference"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"totalT":{"type":"number","exclusiveMinimum":0,"description":"Total testosterone"},"totalTUnit":{"description":"Default ng/dL","type":"string","enum":["ng/dL","nmol/L"]},"shbg":{"type":"number","exclusiveMinimum":0,"description":"SHBG in nmol/L"},"albuminGdL":{"description":"Albumin in g/dL (default 4.3)","type":"number","exclusiveMinimum":0,"maximum":6}},"required":["totalT","shbg"]},"examples":{"example1":{"summary":"Typical male values","value":{"totalT":450,"shbg":35}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/compare_provider":{"post":{"operationId":"compare_provider","summary":"Compare TestWell with another lab-testing service","description":"Honest side-by-side of TestWell and another direct-to-consumer lab service (Quest Direct, Labcorp OnDemand, Function Health, JustLabs, Ulta Lab Tests, …): pricing model, per-order fees, labs, turnaround, where each wins, spot prices on common tests as sticker AND all-in, with verification dates and sources. Call with no argument to list the providers covered.","tags":["compare"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"description":"Competitor slug or name, e.g. 'quest-direct', 'Function Health', 'justlabs'","type":"string","maxLength":60}}},"examples":{"example1":{"summary":"Sticker vs all-in with their per-order fees","value":{"provider":"justlabs"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}},"/api/agent/get_guide":{"post":{"operationId":"get_guide","summary":"Get a guide, condition or answer page as Markdown","description":"Return one of TestWell's educational pages as Markdown: guides (/guides/<slug>), condition workups (/conditions/<slug>), test decision guides (/answers/<slug>), biomarker pages (/biomarkers/<slug>), state pages (/lab-locations/<slug>) or comparisons (/compare/<slug>). Call with no path to list the available guides and conditions.","tags":["content"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"description":"Site path, e.g. '/guides/annual-blood-work' or 'conditions/anemia'","type":"string","maxLength":160},"lang":{"description":"Spanish version when one exists (default en)","type":"string","enum":["en","es"]}}},"examples":{"example1":{"summary":"Reviewed TB testing guide","value":{"path":"/guides/tb-blood-test-vs-skin-test"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"}}}}},"components":{"schemas":{"CatalogPrices":{"type":"object","properties":{"list":{"type":"number"},"quest":{"type":"number"},"labcorp":{"type":"number"},"bioreference":{"type":"number"}},"required":["list"]},"CatalogItem":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["test","panel"]},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"cpt":{"type":["string","null"]},"biomarkers":{"type":"array","items":{"type":"string"}},"biomarkerCount":{"type":"integer"},"includedTests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"url":{"type":"string"}}}},"sampleType":{"type":"string"},"fastingRequired":{"type":"boolean"},"resultsIn":{"type":"string"},"prepInstructions":{"type":["string","null"]},"labs":{"type":"array","items":{"type":"string","enum":["Quest","Labcorp","BioReference"]}},"prices":{"$ref":"#/components/schemas/CatalogPrices"},"labFee":{"type":"number"},"currency":{"type":"string"},"orderable":{"type":"boolean"},"url":{"type":"string"},"markdownUrl":{"type":"string"},"orderUrl":{"type":["string","null"]},"reviewedAt":{"type":["string","null"]},"popular":{"type":"boolean"}},"required":["id","slug","type","name","prices","labFee","orderable","url"]},"CatalogResponse":{"type":"object","properties":{"total":{"type":"integer"},"count":{"type":"integer"},"labFee":{"type":"number"},"currency":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}}}}}}