{"openapi":"3.0.3","info":{"title":"Bill Sherlock API","version":"1.0.0","description":"Bill Sherlock API for medical bill error detection and healthcare transparency","contact":{"name":"API Support","url":"https://www.billsherlock.app/contact"}},"servers":[{"url":"http://localhost:3000","description":"Development server"},{"url":"https://www.billsherlock.app/api","description":"Production server"}],"paths":{"/v1/health":{"get":{"summary":"Health check endpoint","description":"Returns the health status of the API service","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/version":{"get":{"summary":"Version information","description":"Returns API version and build information","responses":{"200":{"description":"Version information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/auth/magic-link":{"post":{"summary":"Send magic link for authentication","description":"Sends a magic link to the user's email for authentication","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"User's email address"}},"required":["email"]}}}},"responses":{"200":{"description":"Magic link sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/investigate":{"post":{"operationId":"investigateBill","summary":"Investigate medical bill charges for billing errors and Medicare rate comparison","description":"Accepts structured line items with service codes (CPT/HCPCS, revenue codes, NDC, or internal codes) and charge amounts. Returns Medicare rate benchmarks and AI-powered billing error analysis with specific findings, confidence scores, and recommended next steps. No authentication is required. Results are informational only and do not constitute medical, legal, or financial advice. Do not send patient names, dates of birth, member IDs, claim numbers, account numbers, addresses, phone numbers, or full document text.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigateRequest"}}}},"responses":{"200":{"description":"Investigation results with benchmarks, findings, and full audit link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigateResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/cases":{"get":{"summary":"List user cases","description":"Retrieve a list of cases for the authenticated user","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of user cases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create new case","description":"Create a new medical bill analysis case","security":[{"BearerAuth":[]},{"CaseToken":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Case creation data"}}}},"responses":{"200":{"description":"Case created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase JWT token or case token"},"CaseToken":{"type":"http","scheme":"bearer","description":"Case-specific access token"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","description":"Optional header to enable idempotency. When provided, repeated POST requests with the same key will return the cached response (with X-Idempotency-Replay: true). If omitted, the request is processed normally without idempotency.","schema":{"type":"string","format":"uuid"}},"RequestId":{"name":"X-Request-ID","in":"header","description":"Request ID for tracing","schema":{"type":"string","format":"uuid"}}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"HealthResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}},"required":["status","timestamp"]},"meta":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"}}}},"required":["data"]},"VersionResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"version":{"type":"string"},"build":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}},"required":["version","build","timestamp"]}},"required":["data"]},"InvestigateRequest":{"type":"object","additionalProperties":false,"required":["line_items"],"properties":{"line_items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/InvestigateLineItem"}},"facility_type":{"type":"string","enum":["professional_office","professional_facility","outpatient_facility","inpatient_facility","lab_diagnostic"]},"facility_name":{"type":"string","maxLength":200,"description":"Required when facility_type is professional_facility, outpatient_facility, or inpatient_facility."},"state":{"type":"string","pattern":"^[A-Z]{2}$"},"payer_id":{"type":"string","maxLength":20},"insurance_company":{"type":"string","maxLength":100},"network_status":{"type":"string","enum":["IN_NETWORK","OUT_OF_NETWORK","UNKNOWN"]}}},"InvestigateLineItem":{"type":"object","additionalProperties":false,"required":["code","charge"],"properties":{"code":{"type":"string","maxLength":20},"code_type":{"type":"string","enum":["CPT_HCPCS","NDC","REV_CODE","INTERNAL","UNKNOWN"],"description":"If omitted, inferred from the code format."},"charge":{"type":"number","exclusiveMinimum":0,"maximum":999999.99},"description":{"type":"string","maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":99,"default":1},"modifiers":{"type":"array","maxItems":4,"items":{"type":"string"}},"service_date":{"type":"string","format":"date"},"rev_code":{"type":"string","pattern":"^\\d{3,4}$"}}},"InvestigateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["line_items","analysis_status","analysis","summary","input_quality","limitations","upsell"],"properties":{"line_items":{"type":"array","items":{"$ref":"#/components/schemas/InvestigateResultLineItem"}},"analysis_status":{"type":"string","enum":["complete","unavailable"]},"analysis":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/InvestigateAnalysis"}]},"summary":{"$ref":"#/components/schemas/InvestigateSummary"},"input_quality":{"$ref":"#/components/schemas/InvestigateInputQuality"},"limitations":{"type":"array","items":{"type":"string"}},"upsell":{"$ref":"#/components/schemas/InvestigateUpsell"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string"},"rate_limit":{"type":"object","properties":{"remaining":{"type":"integer","minimum":0},"reset_at":{"type":"string","format":"date-time"}}}}}}},"InvestigateResultLineItem":{"type":"object","required":["code","code_type","charge","medicare_rate","ratio","pricing_tier","benchmark_source","benchmark_year","benchmark_basis"],"properties":{"code":{"type":"string"},"code_type":{"type":"string"},"charge":{"type":"number"},"medicare_rate":{"type":"number","nullable":true},"ratio":{"type":"number","nullable":true},"pricing_tier":{"type":"string","enum":["fair-price","tier-2x","tier-3x","tier-4x","tier-5x"],"nullable":true},"benchmark_source":{"type":"string","enum":["PFS","CLFS","OPPS","PART_B_DRUGS","IPPS"],"nullable":true},"benchmark_year":{"type":"integer","nullable":true},"benchmark_basis":{"type":"string","enum":["national","locality"],"nullable":true}}},"InvestigateAnalysis":{"type":"object","required":["overall_assessment","findings","quick_checks"],"properties":{"overall_assessment":{"type":"string","enum":["MAJOR_ISSUES","MODERATE_ISSUES","MINOR_ISSUES","CLEAN_BILL"]},"findings":{"type":"array","items":{"$ref":"#/components/schemas/InvestigateFinding"}},"quick_checks":{"type":"array","items":{"type":"string"}}}},"InvestigateFinding":{"type":"object","required":["category","title","explanation","financial_impact","confidence_score","estimated_effort","estimated_resolution_time","recommendation"],"properties":{"category":{"type":"string"},"title":{"type":"string"},"explanation":{"type":"string"},"financial_impact":{"type":"number"},"confidence_score":{"type":"integer","minimum":0,"maximum":100},"estimated_effort":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"estimated_resolution_time":{"type":"string"},"recommendation":{"type":"string"}}},"InvestigateSummary":{"type":"object","properties":{"total_charged":{"type":"number"},"total_medicare_benchmark":{"type":"number"},"overall_ratio":{"type":"number","nullable":true},"findings_count":{"type":"integer"},"potential_savings":{"type":"number"}}},"InvestigateInputQuality":{"type":"object","properties":{"score":{"type":"string","enum":["complete","partial","minimal"]},"missing_fields":{"type":"array","items":{"type":"string"}},"next_best_questions":{"type":"array","items":{"type":"string"}}}},"InvestigateUpsell":{"type":"object","properties":{"message":{"type":"string"},"url":{"type":"string","format":"uri"},"full_audit_includes":{"type":"array","items":{"type":"string"}}}}}}}