{"openapi":"3.1.0","info":{"title":"MyNursingSchools Agent API","version":"1.0.0","summary":"Nursing education decision endpoints for AI agents.","description":"Read-only JSON endpoints for AI agents answering nursing-school questions: education ROI, entry-pathway planning, and admission readiness, computed from the same logic that powers the MyNursingSchools website.\n\nNo authentication or API key is required. Every response carries its assumptions, its primary sources, and links back to the human page for the same calculation.\n\nCompanion resources: agent instructions at https://mynursingschools.com/agents.md, retrieval hints at https://mynursingschools.com/llms.txt, the MCP server at https://mynursingschools.com/api/mcp, and the CC BY 4.0 NCLEX dataset at https://mynursingschools.com/data.","contact":{"name":"MyNursingSchools","email":"info@mynursingschools.com","url":"https://mynursingschools.com/contact"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://mynursingschools.com","description":"Production"}],"tags":[{"name":"discovery","description":"Capability discovery for agents."},{"name":"calculators","description":"Deterministic nursing education calculations."}],"paths":{"/api/agent/v1":{"get":{"operationId":"getAgentApiIndex","summary":"Agent API index","description":"Capability index: what this site is for, which endpoints exist, and where the machine-readable companions live.","tags":["discovery"],"parameters":[{"name":"format","in":"query","required":false,"description":"Set to `openapi` to receive this OpenAPI document instead of the index.","schema":{"type":"string","enum":["json","openapi"],"default":"json"}}],"responses":{"200":{"description":"Capability index, or the OpenAPI document when `format=openapi`.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/v1/calculators":{"get":{"operationId":"listCalculators","summary":"List calculators","description":"Every calculator with its parameters, example request, sources, and the human page that runs the same logic.","tags":["calculators"],"parameters":[{"name":"format","in":"query","required":false,"description":"Set to `openapi` to receive the OpenAPI document for the calculators.","schema":{"type":"string","enum":["json","openapi"],"default":"json"}}],"responses":{"200":{"description":"Calculator directory, or the OpenAPI document when `format=openapi`.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/v1/calculators/nursing-roi":{"get":{"operationId":"getNursingRoi","summary":"Nursing education ROI","description":"Break-even months, expected salary, and 5/10/20-year net earnings for a nursing credential in one state, from BLS OES state wages and IPEDS tuition estimates.\n\nWhen to use:\n- Someone asks whether a nursing degree pays for itself in a given state.\n- Comparing two credentials (for example ADN vs BSN) on payback time rather than sticker price.\n- You need an expected post-graduation salary figure with its source, not a guess.\n\nSources:\n- U.S. Bureau of Labor Statistics, Occupational Employment and Wage Statistics (state RN means)\n- NCES IPEDS 2023 nursing program tuition\n- AACN salary surveys (credential multipliers)","tags":["calculators"],"parameters":[{"name":"state","in":"query","required":true,"description":"State slug (lowercase, hyphenated) — for example `california`, `new-york`, `district-of-columbia`.","example":"california","schema":{"type":"string","enum":["alabama","alaska","arizona","arkansas","california","colorado","connecticut","delaware","florida","georgia","hawaii","idaho","illinois","indiana","iowa","kansas","kentucky","louisiana","maine","maryland","massachusetts","michigan","minnesota","mississippi","missouri","montana","nebraska","nevada","new-hampshire","new-jersey","new-mexico","new-york","north-carolina","north-dakota","ohio","oklahoma","oregon","pennsylvania","rhode-island","south-carolina","south-dakota","tennessee","texas","utah","vermont","virginia","washington","west-virginia","wisconsin","wyoming","district-of-columbia"]}},{"name":"degree","in":"query","required":true,"description":"Target nursing credential.","example":"BSN","schema":{"type":"string","enum":["LPN","ADN","RN_TO_BSN","BSN","RN_TO_MSN","MSN","DNP","PHD","CERTIFICATE"]}},{"name":"current_income","in":"query","required":false,"description":"Current annual income in USD. Drives the salary-increase and break-even figures. Defaults to 0 (not currently employed).","example":45000,"schema":{"type":"number","default":0}}],"responses":{"200":{"description":"Calculation result with inputs, assumptions, sources, and links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatorResult"}}}},"400":{"description":"A parameter was missing or outside its allowed values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/calculators/lpn-pathway":{"get":{"operationId":"getLpnPathway","summary":"LPN vs RN pathway planner","description":"Recommends an entry route into nursing (LPN first, LPN then bridge to RN, straight to RN, or accelerated BSN) with the ladder, timing, and cost range behind the recommendation.\n\nWhen to use:\n- Someone asks whether to become an LPN first or go straight for RN.\n- A career changer with a non-nursing bachelor's degree is weighing an accelerated BSN.\n- You need a staged plan (credential by credential) rather than a single program suggestion.\n\nSources:\n- BLS Occupational Employment and Wage Statistics (LPN and RN national medians, May 2024)\n- MyNursingSchools program catalog (program lengths and tuition ranges)","tags":["calculators"],"parameters":[{"name":"starting_point","in":"query","required":true,"description":"Where the person is today: `none` (new to healthcare), `healthcare` (CNA/MA/EMT/caregiver), `degree_holder` (holds a non-nursing bachelor's).","example":"none","schema":{"type":"string","enum":["none","healthcare","degree_holder"]}},{"name":"end_goal","in":"query","required":true,"description":"`nurse_now` (become a licensed nurse the practical way), `become_rn`, or `advanced` (RN now, advanced practice later).","example":"become_rn","schema":{"type":"string","enum":["nurse_now","become_rn","advanced"]}},{"name":"priority","in":"query","required":true,"description":"What matters most: speed to work, long-term pay, cost, or flexibility.","example":"speed","schema":{"type":"string","enum":["speed","pay","cost","flexibility"]}},{"name":"timeline","in":"query","required":true,"description":"`asap` (starting within months), `year`, or `open`.","example":"asap","schema":{"type":"string","enum":["asap","year","open"]}},{"name":"budget","in":"query","required":true,"description":"Out-of-pocket budget: `tight`, `moderate`, or `flexible`.","example":"tight","schema":{"type":"string","enum":["tight","moderate","flexible"]}}],"responses":{"200":{"description":"Calculation result with inputs, assumptions, sources, and links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatorResult"}}}},"400":{"description":"A parameter was missing or outside its allowed values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/calculators/admission-readiness":{"get":{"operationId":"getAdmissionReadiness","summary":"Nursing school admission readiness","description":"Scores an applicant profile (GPA, entrance exam, prerequisites, experience, target program) 0–100 and returns the readiness band with concrete next steps.\n\nWhen to use:\n- Someone asks whether their GPA and TEAS score are competitive for a program type.\n- Building a balanced reach/match/likely application list.\n- You need next steps for a weak application rather than a yes/no answer.\n\nSources:\n- MyNursingSchools admissions rubric (published weighting, see /tools/admission-calculator)","tags":["calculators"],"parameters":[{"name":"gpa","in":"query","required":true,"description":"Prerequisite or science GPA on a 0–4 scale. Values outside the range are clamped.","example":3.4,"schema":{"type":"number"}},{"name":"entrance_exam_score","in":"query","required":true,"description":"TEAS or equivalent entrance exam score, 0–100. Values outside the range are clamped. Alias: `teas_score`.","example":78,"schema":{"type":"number"}},{"name":"program_type","in":"query","required":true,"description":"Target program: `ADN` (ADN (Associate's)), `BSN` (Traditional BSN), `ABSN` (Accelerated BSN), `RN_TO_BSN` (RN to BSN), `MSN` (MSN / Advanced practice).","example":"BSN","schema":{"type":"string","enum":["ADN","BSN","ABSN","RN_TO_BSN","MSN"]}},{"name":"experience","in":"query","required":true,"description":"Healthcare experience: `none` (No healthcare experience yet), `volunteer` (Volunteer, shadowing, or patient-care exposure), `cna` (CNA, medical assistant, EMT, or similar), `lpn` (Current LPN or LVN), `rn` (Current RN).","example":"cna","schema":{"type":"string","enum":["none","volunteer","cna","lpn","rn"]}},{"name":"science_prereqs_complete","in":"query","required":false,"description":"Core science prerequisites complete or in progress. Defaults to true.","example":true,"schema":{"type":"boolean","default":true}},{"name":"has_retakes","in":"query","required":false,"description":"One or more repeated prerequisite courses on the transcript. Defaults to false.","example":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Calculation result with inputs, assumptions, sources, and links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatorResult"}}}},"400":{"description":"A parameter was missing or outside its allowed values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"CalculatorResult":{"type":"object","required":["calculator","inputs","result","assumptions","sources","links"],"properties":{"calculator":{"type":"string","description":"Calculator id that produced the result."},"inputs":{"type":"object","description":"Parameters after parsing, clamping, and defaults."},"result":{"type":"object","description":"The calculation itself."},"assumptions":{"type":"array","items":{"type":"string"},"description":"What the numbers assume — quote these alongside any figure."},"sources":{"type":"array","items":{"type":"string"},"description":"Primary sources behind the inputs."},"links":{"type":"object","description":"Human pages to cite, including the page that runs the same calculation."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_parameter","unknown_calculator"]},"message":{"type":"string"},"parameter":{"type":"string"},"allowed_values":{"type":"array","items":{"type":"string"}}}},"documentation_url":{"type":"string","format":"uri"}}}}}}