{"openapi":"3.0.3","info":{"title":"Vitals Vault Educational API","description":"Public API for accessing educational biomarker information, lab packages, and health insights.\n\n## Overview\nThis API provides comprehensive educational content about biomarkers, their optimal ranges, \nand related health information. It is designed for mobile applications and web platforms \nthat need to display biomarker educational content.\n\n## Key Features\n- Comprehensive biomarker database with 100+ markers\n- Optimal ranges by age and gender\n- Nutrition and testing guidelines\n- Lab package information\n- User-generated content (stories and Q&A)\n- Search and trending functionality\n\n## Authentication\nMost endpoints are public and do not require authentication or an API key. Admin endpoints\nrequire an operator-issued bearer token restricted to the admin endpoints; not part of\nthe public surface. Partner access to patient data goes through the separate\nFHIR R4 rail, which uses OAuth 2.0 authorization code + PKCE with per-resource scopes\n(`patient/Patient.rs`, `patient/Observation.rs`, `patient/DiagnosticReport.rs`); see the\n`PartnerOAuth2` security scheme and https://www.vitalsvault.com/developers. The FHIR rail\nis enabled per environment and may be disabled on production.\n\n## Rate Limiting\nPublic Educational API GET endpoints share one budget of 100 requests per 15 minutes by default\nper client (IP), enforced across all servers. Exceeding the limit returns HTTP 429 with a Retry-After\nheader and X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.\n\n## Response Format\nAll responses follow a consistent format with `success`, `data`, and optional `error` fields.\nError responses also implement RFC 9457 `application/problem+json` (`type`, `title`, `status`,\n`detail`, `instance`) while keeping `success: false` and `error: { code, message }` for\nexisting clients.\n\n## Versioning\nThe public surface is URL-versioned at `/api/v1`. Breaking changes ship as a new path prefix\n(`/api/v2`) with at least six months of notice. Deprecated routes send `Deprecation` and\n`Sunset` headers. Policy: https://www.vitalsvault.com/developers/versioning\n\n## Execution Model\nAll public Educational API operations are synchronous and return a final response in the same\nHTTP request. Follow the pagination parameters declared by each operation: the biomarker list\nsupports cursor parameters in addition to `page` and `pageSize`, while category and lab-package\nlists declare `page` and `pageSize`. `POST /api/v1/biomarkers/batch` accepts at most 50 biomarker\nslugs. The public API does not expose asynchronous jobs, `202 Accepted` status URLs, or polling\nendpoints.\n\nPOST operations accept an optional `Idempotency-Key` header. The batch biomarker endpoint\nreplays a stored response when the same key and body are sent again within 24 hours.\n","version":"1.0.0","contact":{"name":"Vitals Vault API Support","email":"support@vitalsvault.com","url":"https://www.vitalsvault.com/developers"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://www.vitalsvault.com","description":"Production"}],"tags":[{"name":"Biomarker Categories","description":"Operations related to biomarker categories"},{"name":"Biomarkers","description":"Operations related to individual biomarkers"},{"name":"Lab Packages","description":"Lab test packages and bundles"},{"name":"User Content","description":"User-generated content like stories and Q&A"},{"name":"Admin","description":"Administrative operations"}],"paths":{"/api/v1/biomarkers/categories":{"get":{"tags":["Biomarker Categories"],"summary":"List biomarker categories","description":"Get a paginated list of all biomarker categories","operationId":"listCategories","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"},{"name":"sortBy","in":"query","schema":{"type":"string"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort order"}],"responses":{"200":{"description":"Successfully retrieved categories","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamins-minerals"},"name":{"type":"string","example":"Vitamins and Minerals"},"description":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"displayOrder":{"type":"integer"},"biomarkerCount":{"type":"integer","description":"Number of biomarkers in this category"},"commonConditions":{"type":"array","items":{"type":"string"}},"keyBenefits":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["page","pageSize","totalCount","totalPages"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"},"hasPrevious":{"type":"boolean","description":"Whether there is a previous page"},"cursor":{"type":"string","description":"Cursor representing the current offset"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when hasNext is false"}}}}}}}]},"example":{"success":true,"data":{"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","slug":"vitamins-minerals","name":"Vitamins and Minerals","description":"Essential nutrients for optimal health","biomarkerCount":15}],"pagination":{"page":1,"pageSize":20,"totalCount":10,"totalPages":1}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/validation-error","title":"Invalid request parameters","status":400,"detail":"Invalid request parameters","success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request parameters","details":"Page must be a positive integer"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/categories/{slug}":{"get":{"tags":["Biomarker Categories"],"summary":"Get category details","description":"Get detailed information about a specific biomarker category","operationId":"getCategoryBySlug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug","example":"vitamins-minerals"}],"responses":{"200":{"description":"Successfully retrieved category","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamins-minerals"},"name":{"type":"string","example":"Vitamins and Minerals"},"description":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"displayOrder":{"type":"integer"},"biomarkerCount":{"type":"integer","description":"Number of biomarkers in this category"},"commonConditions":{"type":"array","items":{"type":"string"}},"keyBenefits":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}]}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/not-found","title":"Resource not found","status":404,"detail":"Resource not found","success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers":{"get":{"tags":["Biomarkers"],"summary":"List biomarkers","description":"Get a paginated list of biomarkers with optional filtering","operationId":"listBiomarkers","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Alias for pageSize (cursor-friendly clients)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous next_cursor; takes precedence over page"},{"name":"sortBy","in":"query","schema":{"type":"string"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort order"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return, or 'minimal'/'card' for predefined sets"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},{"name":"gender","in":"query","schema":{"type":"string","enum":["male","female"]},"description":"Filter by applicable gender"},{"name":"hasJunctionMapping","in":"query","schema":{"type":"boolean"},"description":"Filter biomarkers with Junction Health integration"},{"name":"inPackages","in":"query","schema":{"type":"string"},"description":"Comma-separated list of package slugs"}],"responses":{"200":{"description":"Successfully retrieved biomarkers","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["page","pageSize","totalCount","totalPages"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"},"hasPrevious":{"type":"boolean","description":"Whether there is a previous page"},"cursor":{"type":"string","description":"Cursor representing the current offset"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when hasNext is false"}}}}}}}]},"example":{"success":true,"data":{"data":[{"id":"456e7890-e89b-12d3-a456-426614174000","slug":"vitamin-d","name":"Vitamin D (25-OH)","categorySlug":"vitamins-minerals","summary":"Essential vitamin for bone health and immune function","unit":"ng/mL"}],"pagination":{"page":1,"pageSize":20,"totalCount":111,"totalPages":6}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/validation-error","title":"Invalid request parameters","status":400,"detail":"Invalid request parameters","success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request parameters","details":"Page must be a positive integer"}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/batch":{"post":{"tags":["Biomarkers"],"summary":"Batch biomarker lookup","description":"Fetch up to 50 biomarkers by slug in one request. Optional Idempotency-Key replays the original response for 24 hours.","operationId":"batchBiomarkers","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":256},"description":"Optional replay key for POST operations. The same key and body return the original response for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slugs"],"properties":{"slugs":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"example":["ferritin","apob"]}}}}}},"responses":{"200":{"description":"Batch lookup result. Missing slugs are returned as null in the same order.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"allOf":[{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}],"nullable":true}},"found":{"type":"integer"},"requested":{"type":"integer"}}}}}]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/validation-error","title":"Invalid request parameters","status":400,"detail":"Invalid request parameters","success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request parameters","details":"Page must be a positive integer"}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/search":{"get":{"tags":["Biomarkers"],"summary":"Search biomarkers","description":"Full-text search across biomarker names, summaries, and significance","operationId":"searchBiomarkers","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Search query"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},{"name":"gender","in":"query","schema":{"type":"string","enum":["male","female"]},"description":"Filter by applicable gender"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Maximum number of results"}],"responses":{"200":{"description":"Successfully searched biomarkers","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"allOf":[{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"relevanceScore":{"type":"number","format":"float","description":"Search relevance score"}}}]}},"query":{"type":"string"},"totalResults":{"type":"integer"},"searchTime":{"type":"integer","description":"Search execution time in ms"}}}}}]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/validation-error","title":"Invalid request parameters","status":400,"detail":"Invalid request parameters","success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request parameters","details":"Page must be a positive integer"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/trending":{"get":{"tags":["Biomarkers"],"summary":"Get trending biomarkers","description":"Get biomarkers with highest trending scores based on views and searches","operationId":"getTrendingBiomarkers","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10},"description":"Number of trending biomarkers to return"},{"name":"timeframe","in":"query","schema":{"type":"string","enum":["day","week","month"],"default":"week"},"description":"Timeframe for trending calculation"}],"responses":{"200":{"description":"Successfully retrieved trending biomarkers","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"trendingRank":{"type":"integer","description":"Ranking position"},"trendingChange":{"type":"string","enum":["up","down","stable"],"description":"Trend direction"}}}]}}}}]}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/{slug}":{"get":{"tags":["Biomarkers"],"summary":"Get biomarker details","description":"Get comprehensive information about a specific biomarker","operationId":"getBiomarkerBySlug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Biomarker slug","example":"vitamin-d"},{"name":"include","in":"query","schema":{"type":"string"},"description":"Comma-separated list of related data to include"}],"responses":{"200":{"description":"Successfully retrieved biomarker","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"allOf":[{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"category":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamins-minerals"},"name":{"type":"string","example":"Vitamins and Minerals"},"description":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"displayOrder":{"type":"integer"},"biomarkerCount":{"type":"integer","description":"Number of biomarkers in this category"},"commonConditions":{"type":"array","items":{"type":"string"}},"keyBenefits":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"optimalRanges":{"type":"array","items":{"type":"object","required":["gender","ageMin","ageMax","optimalMin","optimalMax","unit"],"properties":{"id":{"type":"string","format":"uuid"},"gender":{"type":"string","enum":["male","female","both"]},"ageMin":{"type":"integer"},"ageMax":{"type":"integer"},"optimalMin":{"type":"number"},"optimalMax":{"type":"number"},"normalMin":{"type":"number"},"normalMax":{"type":"number"},"unit":{"type":"string"},"source":{"type":"string"},"notes":{"type":"string"},"isPregnancySpecific":{"type":"boolean","default":false},"pregnancyTrimester":{"type":"integer","minimum":1,"maximum":3}}}},"nutritionGuidelines":{"type":"array","items":{"type":"object","required":["purpose","recommendation"],"properties":{"id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["increase","decrease","maintain"]},"recommendation":{"type":"string"},"foods":{"type":"array","items":{"type":"string"}},"supplements":{"type":"array","items":{"type":"string"}},"avoidFoods":{"type":"array","items":{"type":"string"}},"timing":{"type":"string"},"dosage":{"type":"string"},"interactions":{"type":"array","items":{"type":"string"}},"contraindications":{"type":"array","items":{"type":"string"}}}}},"testingGuidelines":{"type":"array","items":{"type":"object","required":["frequency","conditions"],"properties":{"id":{"type":"string","format":"uuid"},"frequency":{"type":"string","example":"Every 3 months"},"conditions":{"type":"array","items":{"type":"string"}},"fastingRequired":{"type":"boolean"},"bestTimeOfDay":{"type":"string"},"preparation":{"type":"array","items":{"type":"string"}},"interferingFactors":{"type":"array","items":{"type":"string"}},"relatedTests":{"type":"array","items":{"type":"string"}}}}},"researchLinks":{"type":"array","items":{"type":"object","required":["title","url","type"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publishDate":{"type":"string","format":"date"},"authors":{"type":"array","items":{"type":"string"}},"journal":{"type":"string"},"type":{"type":"string","enum":["clinical_trial","meta_analysis","review","case_study","guideline"]},"keyFindings":{"type":"array","items":{"type":"string"}},"relevanceScore":{"type":"number","format":"float","minimum":0,"maximum":1}}}}}}]}}}]},"example":{"success":true,"data":{"id":"456e7890-e89b-12d3-a456-426614174000","slug":"vitamin-d","name":"Vitamin D (25-OH)","categorySlug":"vitamins-minerals","summary":"Essential vitamin for bone health","significance":"Critical for calcium absorption and immune function","unit":"ng/mL","optimalRanges":[{"gender":"both","ageMin":18,"ageMax":99,"optimalMin":30,"optimalMax":80,"unit":"ng/mL"}]}}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/not-found","title":"Resource not found","status":404,"detail":"Resource not found","success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/{slug}/stories":{"get":{"tags":["User Content"],"summary":"Get user stories for a biomarker","description":"Get approved user stories and experiences related to a biomarker","operationId":"getBiomarkerStories","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Biomarker slug"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["recent","helpful"],"default":"recent"},"description":"Sort order for stories"}],"responses":{"200":{"description":"Successfully retrieved stories","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","biomarkerId","title","content","isApproved"],"properties":{"id":{"type":"string","format":"uuid"},"biomarkerId":{"type":"string","format":"uuid"},"biomarkerSlug":{"type":"string"},"userId":{"type":"string","format":"uuid"},"userDisplayName":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"helpfulCount":{"type":"integer","default":0},"isAnonymous":{"type":"boolean","default":false},"isApproved":{"type":"boolean","default":false},"moderationStatus":{"type":"string","enum":["pending","approved","rejected"]},"moderationNotes":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["page","pageSize","totalCount","totalPages"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"},"hasPrevious":{"type":"boolean","description":"Whether there is a previous page"},"cursor":{"type":"string","description":"Cursor representing the current offset"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when hasNext is false"}}}}}}}]}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/not-found","title":"Resource not found","status":404,"detail":"Resource not found","success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/biomarkers/{slug}/questions":{"get":{"tags":["User Content"],"summary":"Get Q&A for a biomarker","description":"Get approved questions and answers about a biomarker","operationId":"getBiomarkerQuestions","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Biomarker slug"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"},{"name":"category","in":"query","schema":{"type":"string","enum":["general","testing","interpretation","improvement","medical"]},"description":"Filter by question category"},{"name":"featured","in":"query","schema":{"type":"boolean"},"description":"Show only featured questions"}],"responses":{"200":{"description":"Successfully retrieved questions","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","biomarkerId","question","answer","isApproved"],"properties":{"id":{"type":"string","format":"uuid"},"biomarkerId":{"type":"string","format":"uuid"},"biomarkerSlug":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"category":{"type":"string","enum":["general","testing","interpretation","improvement","medical"]},"authorType":{"type":"string","enum":["user","expert","ai_generated"]},"authorId":{"type":"string","format":"uuid"},"authorCredentials":{"type":"string"},"helpfulCount":{"type":"integer","default":0},"viewCount":{"type":"integer","default":0},"isApproved":{"type":"boolean","default":false},"isFeatured":{"type":"boolean","default":false},"moderationStatus":{"type":"string","enum":["pending","approved","rejected"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["page","pageSize","totalCount","totalPages"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"},"hasPrevious":{"type":"boolean","description":"Whether there is a previous page"},"cursor":{"type":"string","description":"Cursor representing the current offset"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when hasNext is false"}}}}}}}]}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/not-found","title":"Resource not found","status":404,"detail":"Resource not found","success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/lab-packages":{"get":{"tags":["Lab Packages"],"summary":"List lab packages","description":"Get a paginated list of available lab test packages","operationId":"listLabPackages","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"},{"name":"sortBy","in":"query","schema":{"type":"string"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort order"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category focus"},{"name":"condition","in":"query","schema":{"type":"string"},"description":"Filter by target condition"},{"name":"minPrice","in":"query","schema":{"type":"number","format":"float","minimum":0},"description":"Minimum price filter"},{"name":"maxPrice","in":"query","schema":{"type":"number","format":"float"},"description":"Maximum price filter"},{"name":"sampleType","in":"query","schema":{"type":"string","enum":["blood","urine","saliva","stool"]},"description":"Filter by sample type"},{"name":"isActive","in":"query","schema":{"type":"boolean"},"description":"Filter by active status"}],"responses":{"200":{"description":"Successfully retrieved lab packages","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","slug","name","price","biomarkerIds"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number","format":"float"},"compareAtPrice":{"type":"number","format":"float"},"currency":{"type":"string","default":"USD"},"biomarkerIds":{"type":"array","items":{"type":"string","format":"uuid"}},"biomarkerCount":{"type":"integer"},"categoryFocus":{"type":"array","items":{"type":"string"}},"targetConditions":{"type":"array","items":{"type":"string"}},"sampleType":{"type":"string","enum":["blood","urine","saliva","stool"]},"fastingRequired":{"type":"boolean"},"turnaroundTime":{"type":"string"},"popularityScore":{"type":"integer"},"junctionTestIds":{"type":"array","items":{"type":"string"}},"preparationInstructions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"displayOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["page","pageSize","totalCount","totalPages"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"},"hasPrevious":{"type":"boolean","description":"Whether there is a previous page"},"cursor":{"type":"string","description":"Cursor representing the current offset"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when hasNext is false"}}}}}}}]},"example":{"success":true,"data":{"data":[{"id":"789e0123-e89b-12d3-a456-426614174000","slug":"comprehensive-metabolic","name":"Comprehensive Metabolic Panel","description":"Complete metabolic health assessment","price":129.99,"biomarkerCount":14,"sampleType":"blood","turnaroundTime":"2-3 business days"}],"pagination":{"page":1,"pageSize":20,"totalCount":25,"totalPages":2}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/validation-error","title":"Invalid request parameters","status":400,"detail":"Invalid request parameters","success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request parameters","details":"Page must be a positive integer"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/lab-packages/{slug}":{"get":{"tags":["Lab Packages"],"summary":"Get lab package details","description":"Get detailed information about a specific lab package including biomarkers","operationId":"getLabPackageBySlug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Lab package slug","example":"comprehensive-metabolic"},{"name":"includeBiomarkers","in":"query","schema":{"type":"boolean","default":true},"description":"Include full biomarker details"}],"responses":{"200":{"description":"Successfully retrieved lab package","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"allOf":[{"type":"object","required":["id","slug","name","price","biomarkerIds"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number","format":"float"},"compareAtPrice":{"type":"number","format":"float"},"currency":{"type":"string","default":"USD"},"biomarkerIds":{"type":"array","items":{"type":"string","format":"uuid"}},"biomarkerCount":{"type":"integer"},"categoryFocus":{"type":"array","items":{"type":"string"}},"targetConditions":{"type":"array","items":{"type":"string"}},"sampleType":{"type":"string","enum":["blood","urine","saliva","stool"]},"fastingRequired":{"type":"boolean"},"turnaroundTime":{"type":"string"},"popularityScore":{"type":"integer"},"junctionTestIds":{"type":"array","items":{"type":"string"}},"preparationInstructions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"displayOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"biomarkers":{"type":"array","items":{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}]}}}]},"example":{"success":true,"data":{"id":"789e0123-e89b-12d3-a456-426614174000","slug":"comprehensive-metabolic","name":"Comprehensive Metabolic Panel","description":"Complete metabolic health assessment","price":129.99,"compareAtPrice":189.99,"currency":"USD","biomarkerCount":14,"biomarkers":[{"id":"456e7890-e89b-12d3-a456-426614174001","slug":"glucose","name":"Glucose","unit":"mg/dL"},{"id":"456e7890-e89b-12d3-a456-426614174002","slug":"sodium","name":"Sodium","unit":"mmol/L"}],"sampleType":"blood","fastingRequired":true,"turnaroundTime":"2-3 business days","preparationInstructions":["Fast for 8-12 hours before the test","Drink water normally","Avoid strenuous exercise 24 hours before"]}}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/not-found","title":"Resource not found","status":404,"detail":"Resource not found","success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}},"/api/v1/admin/performance":{"get":{"tags":["Admin"],"summary":"Get performance statistics","description":"Retrieve detailed performance metrics including database queries, cache stats, and memory usage","operationId":"getPerformanceStats","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved performance statistics","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","required":["database","cache","memory"],"properties":{"database":{"type":"object","properties":{"totalQueries":{"type":"integer"},"averageDuration":{"type":"number","description":"Average query duration in ms"},"cacheHitRate":{"type":"number","minimum":0,"maximum":1},"slowQueries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"duration":{"type":"number"},"rowCount":{"type":"integer"}}}}}},"cache":{"type":"object","properties":{"edgeCache":{"type":"object","properties":{"size":{"type":"integer","description":"Number of cached entries"},"entries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"age":{"type":"number","description":"Age in seconds"},"expires":{"type":"number","description":"Expiry timestamp"}}}}}}}},"memory":{"type":"object","properties":{"used":{"type":"integer","description":"Used memory in MB"},"total":{"type":"integer","description":"Total memory in MB"},"percentage":{"type":"integer","minimum":0,"maximum":100}}}}}}}]},"example":{"success":true,"data":{"database":{"totalQueries":150,"averageDuration":45,"cacheHitRate":0.85,"slowQueries":[{"query":"biomarkers_list","duration":250,"rowCount":100}]},"cache":{"edgeCache":{"size":25,"entries":[{"key":"biomarkers_list_page1","age":120,"expires":1640995200000}]}},"memory":{"used":120,"total":512,"percentage":23}}}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/unauthorized","title":"Authentication required","status":401,"detail":"Authentication required","success":false,"error":{"code":"UNAUTHORIZED","message":"Authentication required"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}},"delete":{"tags":["Admin"],"summary":"Clear cache","description":"Clear various cache layers","operationId":"clearCache","security":[{"BearerAuth":[]}],"parameters":[{"name":"target","in":"query","schema":{"type":"string","enum":["cache","all"],"default":"all"},"description":"Cache target to clear"}],"responses":{"200":{"description":"Successfully cleared cache","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},{"type":"object","properties":{"data":{"type":"object","properties":{"cleared":{"type":"array","items":{"type":"string"}}}}}}]},"example":{"success":true,"data":{"cleared":["cache"]}}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/unauthorized","title":"Authentication required","status":401,"detail":"Authentication required","success":false,"error":{"code":"UNAUTHORIZED","message":"Authentication required"}}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}}}},"components":{"schemas":{"ApiResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (only present if success is true)"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"meta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}}}},"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}},"ResponseMeta":{"type":"object","properties":{"queryTime":{"type":"integer","description":"Query execution time in milliseconds"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}}},"PaginationInfo":{"type":"object","required":["page","pageSize","totalCount","totalPages"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"},"hasPrevious":{"type":"boolean","description":"Whether there is a previous page"},"cursor":{"type":"string","description":"Cursor representing the current offset"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when hasNext is false"}}},"Problem":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"BiomarkerCategory":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamins-minerals"},"name":{"type":"string","example":"Vitamins and Minerals"},"description":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"displayOrder":{"type":"integer"},"biomarkerCount":{"type":"integer","description":"Number of biomarkers in this category"},"commonConditions":{"type":"array","items":{"type":"string"}},"keyBenefits":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Biomarker":{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"BiomarkerDetail":{"allOf":[{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"category":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamins-minerals"},"name":{"type":"string","example":"Vitamins and Minerals"},"description":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"displayOrder":{"type":"integer"},"biomarkerCount":{"type":"integer","description":"Number of biomarkers in this category"},"commonConditions":{"type":"array","items":{"type":"string"}},"keyBenefits":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"optimalRanges":{"type":"array","items":{"type":"object","required":["gender","ageMin","ageMax","optimalMin","optimalMax","unit"],"properties":{"id":{"type":"string","format":"uuid"},"gender":{"type":"string","enum":["male","female","both"]},"ageMin":{"type":"integer"},"ageMax":{"type":"integer"},"optimalMin":{"type":"number"},"optimalMax":{"type":"number"},"normalMin":{"type":"number"},"normalMax":{"type":"number"},"unit":{"type":"string"},"source":{"type":"string"},"notes":{"type":"string"},"isPregnancySpecific":{"type":"boolean","default":false},"pregnancyTrimester":{"type":"integer","minimum":1,"maximum":3}}}},"nutritionGuidelines":{"type":"array","items":{"type":"object","required":["purpose","recommendation"],"properties":{"id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["increase","decrease","maintain"]},"recommendation":{"type":"string"},"foods":{"type":"array","items":{"type":"string"}},"supplements":{"type":"array","items":{"type":"string"}},"avoidFoods":{"type":"array","items":{"type":"string"}},"timing":{"type":"string"},"dosage":{"type":"string"},"interactions":{"type":"array","items":{"type":"string"}},"contraindications":{"type":"array","items":{"type":"string"}}}}},"testingGuidelines":{"type":"array","items":{"type":"object","required":["frequency","conditions"],"properties":{"id":{"type":"string","format":"uuid"},"frequency":{"type":"string","example":"Every 3 months"},"conditions":{"type":"array","items":{"type":"string"}},"fastingRequired":{"type":"boolean"},"bestTimeOfDay":{"type":"string"},"preparation":{"type":"array","items":{"type":"string"}},"interferingFactors":{"type":"array","items":{"type":"string"}},"relatedTests":{"type":"array","items":{"type":"string"}}}}},"researchLinks":{"type":"array","items":{"type":"object","required":["title","url","type"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publishDate":{"type":"string","format":"date"},"authors":{"type":"array","items":{"type":"string"}},"journal":{"type":"string"},"type":{"type":"string","enum":["clinical_trial","meta_analysis","review","case_study","guideline"]},"keyFindings":{"type":"array","items":{"type":"string"}},"relevanceScore":{"type":"number","format":"float","minimum":0,"maximum":1}}}}}}]},"OptimalRange":{"type":"object","required":["gender","ageMin","ageMax","optimalMin","optimalMax","unit"],"properties":{"id":{"type":"string","format":"uuid"},"gender":{"type":"string","enum":["male","female","both"]},"ageMin":{"type":"integer"},"ageMax":{"type":"integer"},"optimalMin":{"type":"number"},"optimalMax":{"type":"number"},"normalMin":{"type":"number"},"normalMax":{"type":"number"},"unit":{"type":"string"},"source":{"type":"string"},"notes":{"type":"string"},"isPregnancySpecific":{"type":"boolean","default":false},"pregnancyTrimester":{"type":"integer","minimum":1,"maximum":3}}},"NutritionGuideline":{"type":"object","required":["purpose","recommendation"],"properties":{"id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["increase","decrease","maintain"]},"recommendation":{"type":"string"},"foods":{"type":"array","items":{"type":"string"}},"supplements":{"type":"array","items":{"type":"string"}},"avoidFoods":{"type":"array","items":{"type":"string"}},"timing":{"type":"string"},"dosage":{"type":"string"},"interactions":{"type":"array","items":{"type":"string"}},"contraindications":{"type":"array","items":{"type":"string"}}}},"TestingGuideline":{"type":"object","required":["frequency","conditions"],"properties":{"id":{"type":"string","format":"uuid"},"frequency":{"type":"string","example":"Every 3 months"},"conditions":{"type":"array","items":{"type":"string"}},"fastingRequired":{"type":"boolean"},"bestTimeOfDay":{"type":"string"},"preparation":{"type":"array","items":{"type":"string"}},"interferingFactors":{"type":"array","items":{"type":"string"}},"relatedTests":{"type":"array","items":{"type":"string"}}}},"ResearchLink":{"type":"object","required":["title","url","type"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publishDate":{"type":"string","format":"date"},"authors":{"type":"array","items":{"type":"string"}},"journal":{"type":"string"},"type":{"type":"string","enum":["clinical_trial","meta_analysis","review","case_study","guideline"]},"keyFindings":{"type":"array","items":{"type":"string"}},"relevanceScore":{"type":"number","format":"float","minimum":0,"maximum":1}}},"LabPackage":{"type":"object","required":["id","slug","name","price","biomarkerIds"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number","format":"float"},"compareAtPrice":{"type":"number","format":"float"},"currency":{"type":"string","default":"USD"},"biomarkerIds":{"type":"array","items":{"type":"string","format":"uuid"}},"biomarkerCount":{"type":"integer"},"categoryFocus":{"type":"array","items":{"type":"string"}},"targetConditions":{"type":"array","items":{"type":"string"}},"sampleType":{"type":"string","enum":["blood","urine","saliva","stool"]},"fastingRequired":{"type":"boolean"},"turnaroundTime":{"type":"string"},"popularityScore":{"type":"integer"},"junctionTestIds":{"type":"array","items":{"type":"string"}},"preparationInstructions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"displayOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"LabPackageDetail":{"allOf":[{"type":"object","required":["id","slug","name","price","biomarkerIds"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number","format":"float"},"compareAtPrice":{"type":"number","format":"float"},"currency":{"type":"string","default":"USD"},"biomarkerIds":{"type":"array","items":{"type":"string","format":"uuid"}},"biomarkerCount":{"type":"integer"},"categoryFocus":{"type":"array","items":{"type":"string"}},"targetConditions":{"type":"array","items":{"type":"string"}},"sampleType":{"type":"string","enum":["blood","urine","saliva","stool"]},"fastingRequired":{"type":"boolean"},"turnaroundTime":{"type":"string"},"popularityScore":{"type":"integer"},"junctionTestIds":{"type":"array","items":{"type":"string"}},"preparationInstructions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"displayOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"biomarkers":{"type":"array","items":{"type":"object","required":["id","slug","name","categorySlug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"vitamin-d"},"name":{"type":"string","example":"Vitamin D (25-OH)"},"categoryId":{"type":"string","format":"uuid"},"categorySlug":{"type":"string"},"applicableGender":{"type":"string","enum":["male","female","both"],"default":"both"},"summary":{"type":"string","description":"Brief summary of the biomarker"},"significance":{"type":"string","description":"Medical significance of the biomarker"},"symptoms":{"type":"array","items":{"type":"string"}},"causes":{"type":"array","items":{"type":"string"}},"metaDescription":{"type":"string","description":"SEO meta description"},"keyInsights":{"type":"array","items":{"type":"string"}},"loincCode":{"type":"string","example":"25873-0"},"loincName":{"type":"string"},"unit":{"type":"string","example":"ng/mL"},"hasContent":{"type":"boolean","default":true},"junctionMarkerId":{"type":"string","description":"Junction Health marker ID for lab integration"},"includedInPackages":{"type":"array","items":{"type":"string"}},"seoVariations":{"type":"array","items":{"type":"string"},"description":"Alternative search terms"},"medicalReviewStatus":{"type":"string","enum":["pending","reviewed","approved"]},"lastMedicalReview":{"type":"string","format":"date-time"},"viewCount":{"type":"integer","default":0},"searchVolume":{"type":"integer","default":0},"trendingScore":{"type":"number","format":"float"},"lastUpdated":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}]},"BiomarkerUserStory":{"type":"object","required":["id","biomarkerId","title","content","isApproved"],"properties":{"id":{"type":"string","format":"uuid"},"biomarkerId":{"type":"string","format":"uuid"},"biomarkerSlug":{"type":"string"},"userId":{"type":"string","format":"uuid"},"userDisplayName":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"helpfulCount":{"type":"integer","default":0},"isAnonymous":{"type":"boolean","default":false},"isApproved":{"type":"boolean","default":false},"moderationStatus":{"type":"string","enum":["pending","approved","rejected"]},"moderationNotes":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"BiomarkerQuestion":{"type":"object","required":["id","biomarkerId","question","answer","isApproved"],"properties":{"id":{"type":"string","format":"uuid"},"biomarkerId":{"type":"string","format":"uuid"},"biomarkerSlug":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"category":{"type":"string","enum":["general","testing","interpretation","improvement","medical"]},"authorType":{"type":"string","enum":["user","expert","ai_generated"]},"authorId":{"type":"string","format":"uuid"},"authorCredentials":{"type":"string"},"helpfulCount":{"type":"integer","default":0},"viewCount":{"type":"integer","default":0},"isApproved":{"type":"boolean","default":false},"isFeatured":{"type":"boolean","default":false},"moderationStatus":{"type":"string","enum":["pending","approved","rejected"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PerformanceStats":{"type":"object","required":["database","cache","memory"],"properties":{"database":{"type":"object","properties":{"totalQueries":{"type":"integer"},"averageDuration":{"type":"number","description":"Average query duration in ms"},"cacheHitRate":{"type":"number","minimum":0,"maximum":1},"slowQueries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"duration":{"type":"number"},"rowCount":{"type":"integer"}}}}}},"cache":{"type":"object","properties":{"edgeCache":{"type":"object","properties":{"size":{"type":"integer","description":"Number of cached entries"},"entries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"age":{"type":"number","description":"Age in seconds"},"expires":{"type":"number","description":"Expiry timestamp"}}}}}}}},"memory":{"type":"object","properties":{"used":{"type":"integer","description":"Used memory in MB"},"total":{"type":"integer","description":"Total memory in MB"},"percentage":{"type":"integer","minimum":0,"maximum":100}}}}}},"parameters":{"PageParam":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},"PageSizeParam":{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"},"SortByParam":{"name":"sortBy","in":"query","schema":{"type":"string"},"description":"Field to sort by"},"SortOrderParam":{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort order"},"SearchParam":{"name":"search","in":"query","schema":{"type":"string"},"description":"Search query"},"FieldsParam":{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return, or 'minimal'/'card' for predefined sets"},"CategoryParam":{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},"GenderParam":{"name":"gender","in":"query","schema":{"type":"string","enum":["male","female"]},"description":"Filter by applicable gender"},"HasJunctionMappingParam":{"name":"hasJunctionMapping","in":"query","schema":{"type":"boolean"},"description":"Filter biomarkers with Junction Health integration"},"InPackagesParam":{"name":"inPackages","in":"query","schema":{"type":"string"},"description":"Comma-separated list of package slugs"},"IncludeParam":{"name":"include","in":"query","schema":{"type":"string"},"description":"Comma-separated list of related data to include"},"LimitParam":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Alias for pageSize (cursor-friendly clients)"},"CursorParam":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous next_cursor; takes precedence over page"},"IdempotencyKeyHeader":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":256},"description":"Optional replay key for POST operations. The same key and body return the original response for 24 hours."}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/validation-error","title":"Invalid request parameters","status":400,"detail":"Invalid request parameters","success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request parameters","details":"Page must be a positive integer"}}}}},"NotFound":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/not-found","title":"Resource not found","status":404,"detail":"Resource not found","success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"}}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/unauthorized","title":"Authentication required","status":401,"detail":"Authentication required","success":false,"error":{"code":"UNAUTHORIZED","message":"Authentication required"}}}}},"InternalError":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}},"example":{"type":"https://www.vitalsvault.com/problems/internal-error","title":"An unexpected error occurred","status":500,"detail":"An unexpected error occurred","success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}},"TooManyRequests":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}},"application/json":{"schema":{"type":"object","required":["type","title","status","success","error"],"description":"RFC 9457 problem+json with the legacy Educational API error envelope","properties":{"type":{"type":"string","format":"uri","example":"https://www.vitalsvault.com/problems/not-found"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code for programmatic handling","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message","example":"Resource not found"},"details":{"type":"string","description":"Additional error details"}}}}}}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"An operator-issued bearer token; not part of the public surface. Restricted to the admin endpoints."},"PartnerOAuth2":{"type":"oauth2","description":"Partner OAuth 2.0 for the FHIR R4 rail. Authorization code with PKCE (S256). The partner's\nback channel initiates the handshake by pushing an authorization request to `/api/oauth/par`\nauthenticated with the application's `vvfhir_` bearer credential (partner identity token and\na PKCE S256 code challenge) and receives a `request_id`; this is a proprietary back-channel\ninit, not RFC 9126 `request_uri`. The member is sent to `/oauth/authorize` with `client_id`\nand `request_id` and approves on the Vitals Vault consent screen. The code is redeemed at\n`/api/oauth/token` (authorization_code + PKCE `code_verifier`, or a signed JWT client\nassertion for the attested exchange); refresh uses `refresh_token`; revoke at\n`/api/oauth/revoke`. Every access token is scoped: the scopes granted are the intersection of\nthe partner organisation licence, the registered application's allowed scopes, and what the\npatient consented to. Requesting a scope above that ceiling is rejected with `invalid_scope`.\nThe handshake is documented for approved partners in the partner portal and is not a generic\nRFC 8414 / RFC 9126 server. Production availability is per partner agreement; the sandbox\nenvironment is available to approved partners.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.vitalsvault.com/oauth/authorize","tokenUrl":"https://www.vitalsvault.com/api/oauth/token","refreshUrl":"https://www.vitalsvault.com/api/oauth/token","scopes":{"patient/Patient.rs":"Read and search the consenting patient's FHIR Patient resource","patient/Observation.rs":"Read and search lab Observations for the consenting patient","patient/DiagnosticReport.rs":"Read and search DiagnosticReports for the consenting patient"}}}},"PartnerClientSecret":{"type":"http","scheme":"bearer","description":"Partner application credential (`vvfhir_` secret issued per registered application) used on the\nback channel only: pushed authorization requests (`/api/oauth/par`), the token endpoint\n(`/api/oauth/token` — the legacy arm authenticates with the same `vvfhir_` bearer), and token\nrevocation (`/api/oauth/revoke`). Each credential is bound to one application and one environment\n(sandbox or production) and inherits that application's allowed scopes.\n"}}}}