{ "openapi": "3.1.0", "info": { "title": "Rivendell API Documentation", "version": "0.1.0", "description": "This is the OpenAPI specification for Rivendell iOS app." }, "servers": [ { "url": "https://rivendell.health/api", "description": "Rivendell production app" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "AccessibilityBucketSchema": { "type": "string", "enum": [ "MOBILITY", "VISION", "HEARING", "COGNITIVE", "NEURODIVERGENT", "SPEECH_LANGUAGE", "DEXTERITY", "PAIN_FATIGUE", "MENTAL_HEALTH", "SENSORY", "TRANSPORTATION", "CARE_NAVIGATION", "LANGUAGE_INTERPRETER", "TECH_ACCESS", "OTHER" ] }, "AccessibilityNeedSchema": { "type": "object", "properties": { "need": { "type": "string", "minLength": 1, "description": "Accessibility or functional need described by the user" }, "bucket": { "allOf": [ { "$ref": "#/components/schemas/AccessibilityBucketSchema" } ], "description": "Bucket for matching care modality and accommodations" }, "notes": { "type": "string", "minLength": 1, "description": "Optional details for care routing" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence between 0 and 1" } }, "required": [ "need", "bucket" ] }, "AccountDeletionResponseSchema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "requested" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "accessClosed": { "type": "boolean", "enum": [ true ] }, "retainedRecordCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "requestedAt", "accessClosed", "retainedRecordCategories" ] }, "AccountIdSchema": { "type": "string", "pattern": "^account_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "AccountSchema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "entity_id": { "type": [ "string", "null" ] }, "informational_entity_id": { "type": [ "string", "null" ] }, "program_id": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "currency": { "type": "string" }, "bank": { "type": "string" }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] }, "funding": { "type": "string", "enum": [ "loan", "deposits" ] }, "loan": { "type": [ "object", "null" ], "properties": { "loan_id": { "type": "string" } }, "required": [ "loan_id" ] }, "interest_rate": { "type": "string" }, "type": { "type": "string", "enum": [ "account" ] }, "idempotency_key": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "entity_id", "informational_entity_id", "program_id", "status", "currency", "bank", "created_at", "closed_at", "funding", "loan", "interest_rate", "type", "idempotency_key" ] }, "ActiveServiceCategorySchema": { "type": "string", "description": "Service category for new claims and pre-authorizations" }, "ActivityDaySchema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "day": { "type": "string" }, "steps": { "$ref": "#/components/schemas/nullableNumber" }, "activeCalories": { "$ref": "#/components/schemas/nullableNumber" }, "totalCalories": { "$ref": "#/components/schemas/nullableNumber" }, "strain": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "WHOOP day strain, 0-21. Oura has none." }, "score": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Oura activity score, 0-100. WHOOP has none." }, "averageHeartRate": { "$ref": "#/components/schemas/nullableNumber" }, "maxHeartRate": { "$ref": "#/components/schemas/nullableNumber" }, "raw": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" }, "description": "The untouched provider payload. Present only when includeRaw=true." } }, "required": [ "provider", "day", "steps", "activeCalories", "totalCalories", "strain", "score", "averageHeartRate", "maxHeartRate" ] }, "ActivityResponseSchema": { "type": "object", "properties": { "range": { "$ref": "#/components/schemas/WearableRangeSchema" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityDaySchema" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/WearableProviderOutcomeSchema" } }, "noConnections": { "type": "boolean", "description": "No wearable is linked to this account at all." }, "continueWith": { "description": "Present when the upstream page budget ran out before the window did. Pass these dates back to fetch the older records that were cut.", "allOf": [ { "$ref": "#/components/schemas/WearableRangeSchema" } ], "nullable": true } }, "required": [ "range", "days", "providers", "noConnections", "continueWith" ] }, "addOnPricingSchema": { "type": "object", "properties": { "dentalVisionCents": { "$ref": "#/components/schemas/centsSchema" }, "carrotCents": { "$ref": "#/components/schemas/centsSchema" }, "wellnessPackCents": { "$ref": "#/components/schemas/centsSchema" }, "lifestylePerkCents": { "$ref": "#/components/schemas/centsSchema" } }, "required": [ "dentalVisionCents", "carrotCents", "wellnessPackCents", "lifestylePerkCents" ], "additionalProperties": false }, "AddressSchema": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1, "description": "City" }, "region": { "type": "string", "minLength": 1, "description": "State or region code" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code" }, "postalCode": { "type": "string", "minLength": 1, "description": "Postal or ZIP code" } }, "required": [ "city", "region", "countryCode", "postalCode" ] }, "AdjudicateClaimRequestSchema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "APPROVE", "REJECT" ] }, "notes": { "type": "string", "description": "Optional admin notes" }, "approvedAmount": { "type": "integer", "minimum": 0, "description": "Optional approved amount override (in cents)" }, "rejectionReason": { "type": "string", "description": "Required when rejecting a claim" }, "preAuthorizationId": { "description": "Deprecated and ignored. Card claims link consumed pre-authorizations automatically.", "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationIdSchema" } ], "nullable": true } }, "required": [ "decision" ] }, "AdjudicateClaimResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "claimId": { "type": "string" }, "payout": { "type": "object", "properties": { "success": { "type": "boolean" }, "achTransferId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "AdjudicationDecisionSchema": { "type": "object", "properties": { "claimId": { "type": "string" }, "decision": { "type": "string", "enum": [ "APPROVE", "REJECT" ] }, "notes": { "type": "string" }, "rejectionReason": { "type": "string" } }, "required": [ "claimId", "decision" ] }, "AdminClaimInvoiceRequestSchema": { "type": "object", "properties": { "receiptKey": { "type": "string", "minLength": 1 }, "doctorId": { "type": "string", "minLength": 1 }, "ownerUserId": { "type": "string", "minLength": 1 } }, "required": [ "receiptKey", "doctorId", "ownerUserId" ] }, "AdminClaimInvoiceResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "claimId": { "type": "string" }, "memberInvoiceId": { "type": "string" }, "parseStatus": { "type": "string", "enum": [ "PENDING", "SUCCESS", "PARTIAL", "FAILED" ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "AdminClaimReceiptRequestSchema": { "type": "object", "properties": { "receiptKey": { "type": "string", "minLength": 1 }, "ownerUserId": { "type": "string", "minLength": 1 }, "replaceExisting": { "type": "boolean", "default": false } }, "required": [ "receiptKey", "ownerUserId" ] }, "AdminClaimReceiptResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "claimId": { "type": "string" }, "receiptKey": { "type": "string" }, "uploadedAt": { "type": "string" }, "claimStatus": { "type": "string", "enum": [ "PENDING_SUBSTANTIATION", "SUBMITTED", "IN_REVIEW", "APPROVED", "REJECTED", "PAID", "DRAFT" ] } }, "required": [ "success", "claimId", "receiptKey", "uploadedAt", "claimStatus" ] }, "AmountSchema": { "type": "object", "properties": { "cents": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "ISO 4217 currency code" } }, "required": [ "cents", "currency" ] }, "ApiCallLogIdSchema": { "type": "string", "pattern": "^api_call_log_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ApiCapabilitiesSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "api_capabilities" ] }, "api_version": { "type": "string" }, "base_urls": { "type": "object", "properties": { "production": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "current_origin": { "type": "string", "format": "uri" }, "current_api": { "type": "string", "format": "uri" } }, "required": [ "production", "api" ] }, "capabilities_url": { "type": "string" }, "openapi_url": { "type": "string" }, "llms_url": { "type": "string" }, "llms_full_url": { "type": "string" }, "mcp_url": { "type": "string" }, "auth": { "type": "object", "properties": { "modes": { "type": "array", "items": { "$ref": "#/components/schemas/AuthModeSchema" } }, "sandbox_key": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "sk_sandbox_PUBLIC" ] }, "allowed_path_prefix": { "type": "string", "enum": [ "/api/sandbox/" ] }, "rejected_elsewhere": { "type": "boolean", "enum": [ true ] } }, "required": [ "value", "allowed_path_prefix", "rejected_elsewhere" ] } }, "required": [ "modes", "sandbox_key" ] }, "idempotency": { "type": "object", "properties": { "header": { "type": "string", "enum": [ "Idempotency-Key" ] }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "POST", "PATCH", "DELETE" ] } }, "ttl_hours": { "type": "integer", "exclusiveMinimum": 0 }, "replay_header": { "type": "string" }, "rules": { "type": "array", "items": { "type": "string" } } }, "required": [ "header", "methods", "ttl_hours", "replay_header", "rules" ] }, "lists": { "type": "object", "properties": { "envelope": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } }, "required": [ "envelope" ] }, "errors": { "type": "object", "properties": { "envelope": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "validation_error": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400 ] }, "type": { "type": "string", "enum": [ "validation_error" ] }, "recovery_hint": { "type": "string", "enum": [ "CHECK_INPUT" ] } }, "required": [ "status", "type", "recovery_hint" ] }, "idempotency_conflict": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 409 ] }, "type": { "type": "string", "enum": [ "idempotency_key_already_used_error" ] }, "recovery_hint": { "type": "string", "enum": [ "CHECK_INPUT" ] } }, "required": [ "status", "type", "recovery_hint" ] } }, "required": [ "envelope", "validation_error", "idempotency_conflict" ] }, "ids": { "type": "object", "properties": { "pattern": { "type": "string" }, "new_id_body": { "type": "string" }, "description": { "type": "string" }, "malformed_id_error": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400 ] }, "type": { "type": "string", "enum": [ "validation_error" ] }, "recovery_hint": { "type": "string", "enum": [ "CHECK_INPUT" ] } }, "required": [ "status", "type", "recovery_hint" ] } }, "required": [ "pattern", "new_id_body", "description", "malformed_id_error" ] }, "sandbox": { "type": "object", "properties": { "supported": { "type": "boolean", "enum": [ true ] }, "livemode": { "type": "boolean", "enum": [ false ] }, "key": { "type": "string", "enum": [ "sk_sandbox_PUBLIC" ] }, "base_path": { "type": "string", "enum": [ "/api/sandbox" ] }, "stateless_except_idempotency": { "type": "boolean", "enum": [ true ] }, "endpoints": { "type": "array", "items": { "type": "string" } } }, "required": [ "supported", "livemode", "key", "base_path", "stateless_except_idempotency", "endpoints" ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSummarySchema" } } }, "required": [ "object", "api_version", "base_urls", "capabilities_url", "openapi_url", "llms_url", "llms_full_url", "mcp_url", "auth", "idempotency", "lists", "errors", "ids", "sandbox", "resources" ] }, "ApiErrorEnvelopeSchema": { "type": "object", "properties": { "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "ApiMetadataSchema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "propertyNames": { "type": "string", "maxLength": 500 } }, "ApiMutationResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ], "additionalProperties": true }, "ApiTokenIdSchema": { "type": "string", "pattern": "^api_token_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "apiTokenScopeSchema": { "type": "string", "enum": [ "org:read", "members:read", "members:write", "claims:read", "claims:write", "webhooks:read", "webhooks:write", "wearables:read" ] }, "AppointmentCancelRequestSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel" ], "description": "The action to perform" } }, "required": [ "action" ], "description": "Request body for appointment cancellation" }, "AppointmentCancelResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "appointmentId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ] }, "AppointmentDeleteResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "appointmentId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ] }, "AppointmentDetailsSchema": { "type": "object", "properties": { "startAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Appointment start time" }, "location": { "type": [ "string", "null" ] }, "practitionerName": { "type": [ "string", "null" ] }, "memberNotes": { "type": [ "string", "null" ] }, "doctor": { "$ref": "#/components/schemas/DoctorResultSchema" }, "memberPrice": { "description": "Member obligation confirmed when the appointment was booked", "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "nullable": true }, "rate": { "description": "Cash pay rate, the full amount charged by the provider", "allOf": [ { "$ref": "#/components/schemas/RateSchema" } ], "nullable": true }, "coverageEstimate": { "description": "Estimated coverage breakdown based on current plan and benefit usage", "allOf": [ { "$ref": "#/components/schemas/CoverageEstimateSchema" } ], "nullable": true } }, "required": [ "startAt", "location", "practitionerName", "memberNotes", "doctor", "rate", "coverageEstimate" ] }, "AppointmentIdParamsSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/DoctorAppointmentJobIdSchema" } ], "description": "Appointment ID" } }, "required": [ "id" ], "description": "Path parameters for appointment actions" }, "AppointmentListParamsSchema": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/AppointmentScopeSchema" } ], "default": "upcoming", "description": "Which appointments to return: upcoming, past, or all." } }, "description": "Query params for appointment list." }, "AppointmentRequestKindSchema": { "type": "string", "enum": [ "appointment", "procedure_negotiation" ] }, "AppointmentScopeSchema": { "type": "string", "enum": [ "upcoming", "past", "all" ] }, "AppointmentsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentSummarySchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "AppointmentStateSchema": { "type": "string", "enum": [ "planning", "booking", "booked", "failed", "cancelling", "cancelled" ] }, "AppointmentSummarySchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "appointment" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^doctor_appointment_job_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "state": { "$ref": "#/components/schemas/AppointmentStateSchema" }, "updated_at": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" }, "requestedAt": { "type": "string", "format": "date-time", "description": "When the member submitted the request" }, "closedReason": { "type": [ "string", "null" ], "description": "Member-safe reason a failed or cancelled request was closed" }, "requestedSpecialty": { "type": [ "string", "null" ], "description": "Specialty from the original request" }, "requestKind": { "allOf": [ { "$ref": "#/components/schemas/AppointmentRequestKindSchema" } ], "description": "Whether operations is booking an appointment or negotiating a procedure" }, "requestedProcedure": { "type": [ "string", "null" ], "description": "Procedure named by the member for a negotiation request" }, "appointment": { "type": "object" } }, "required": [ "object", "id", "created", "livemode", "metadata", "state", "updated_at", "createdAt", "updatedAt", "appointment" ] }, "ApprovePreAuthorizationRequestSchema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "category": { "allOf": [ { "$ref": "#/components/schemas/ActiveServiceCategorySchema" } ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "ApprovePreAuthorizationResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "preAuthorizationId": { "type": "string" }, "preAuthorization": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationSchema" } ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "AssistantHistoryMessageSchema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant", "user" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 800 } }, "required": [ "role", "content" ] }, "AssistantMessageIdSchema": { "type": "string", "pattern": "^assistant_message_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "AssistantMessageRequestSchema": { "type": "object", "properties": { "threadId": { "type": "string", "pattern": "^assistant_thread_[A-Za-z0-9]{24,32}$", "description": "Existing thread to continue; omit to start a new thread" }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "clientMessageId": { "type": "string", "pattern": "^[A-Za-z0-9-]{8,64}$", "description": "Client-generated retry key, unique per member (UUID recommended). Keep it for the lifetime of the send: reusing it after a dropped stream replays the existing reply, or resumes a turn that was accepted but never answered, instead of duplicating the message or opening a second thread. Generate a new one only for a genuinely new message." } }, "required": [ "message" ] }, "AssistantMessageRoleSchema": { "type": "string", "enum": [ "MEMBER", "ASSISTANT", "HUMAN_AGENT" ] }, "AssistantMessageSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "assistant_message" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^assistant_message_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "role": { "$ref": "#/components/schemas/AssistantMessageRoleSchema" }, "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "created", "livemode", "metadata", "role", "text", "createdAt" ], "additionalProperties": true }, "AssistantThreadDetailsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "assistant_thread" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^assistant_thread_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "title": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantMessageSchema" } } }, "required": [ "object", "id", "created", "livemode", "metadata", "title", "createdAt", "updatedAt", "messages" ], "additionalProperties": true }, "AssistantThreadIdSchema": { "type": "string", "pattern": "^assistant_thread_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "AssistantThreadListItemSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "assistant_thread" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^assistant_thread_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "title": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "created", "livemode", "metadata", "title", "lastMessagePreview", "createdAt", "updatedAt" ], "additionalProperties": true }, "AssistantThreadListQuerySchema": { "type": "object", "properties": { "limit": { "description": "Max number of threads to return", "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "offset": { "description": "Offset for pagination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "AssistantThreadParamsSchema": { "type": "object", "properties": { "threadId": { "allOf": [ { "$ref": "#/components/schemas/AssistantThreadIdSchema" } ], "description": "Assistant thread ID" } }, "required": [ "threadId" ], "description": "Path parameters for assistant thread endpoints" }, "AssistantThreadsListResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantThreadListItemSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ], "additionalProperties": true }, "AuthModeSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer_token", "session_cookie", "sandbox_key" ] }, "header": { "type": "string" }, "use_when": { "type": "string" } }, "required": [ "type", "header", "use_when" ] }, "AvailabilityInputSchema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "required": [ "start", "end" ] }, "minItems": 1 } }, "required": [ "date", "slots" ] } }, "AvailabilitySchema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for the day (e.g. 2024-01-01T00:00:00Z)" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for start of availability window" }, "end": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for end of availability window" } }, "required": [ "start", "end" ] }, "minItems": 1, "description": "Available time slots for this day" } }, "required": [ "date", "slots" ] }, "minItems": 1, "description": "Availability preferences grouped by day" }, "BalanceBucketSchema": { "type": "object", "properties": { "used": { "$ref": "#/components/schemas/AmountSchema" }, "limit": { "$ref": "#/components/schemas/AmountSchema" }, "remaining": { "$ref": "#/components/schemas/AmountSchema" } }, "required": [ "used", "limit", "remaining" ] }, "BankAccountDeleteResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "bankAccountId": { "type": "string" }, "newPrimaryBankAccountId": { "type": [ "string", "null" ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "BankAccountIdParamsSchema": { "type": "object", "properties": { "bankAccountId": { "allOf": [ { "$ref": "#/components/schemas/BankAccountIdSchema" } ], "description": "Bank account ID" } }, "required": [ "bankAccountId" ], "description": "Path parameters for bank account actions" }, "BankAccountIdSchema": { "type": "string", "pattern": "^bank_account_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "BankAccountListItemSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "bank_account" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^bank_account_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "bank_name": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "updated_at": { "type": "integer" }, "stripe_financial_connections_link_state": { "type": [ "string", "null" ], "enum": [ "ACTIVE", "RELINK_REQUIRED", "DISCONNECTED", null ] }, "bankName": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "stripeFinancialConnectionsLinkState": { "type": [ "string", "null" ], "enum": [ "ACTIVE", "RELINK_REQUIRED", "DISCONNECTED", null ] } }, "required": [ "object", "id", "created", "livemode", "metadata", "bank_name", "is_primary", "updated_at", "stripe_financial_connections_link_state", "bankName", "last4", "isPrimary", "createdAt", "updatedAt", "stripeFinancialConnectionsLinkState" ] }, "BankAccountListResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountListItemSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "BankLinkTokenRequestSchema": { "type": "object", "properties": { "ownerType": { "type": "string", "enum": [ "USER", "ORGANIZATION" ] } }, "required": [ "ownerType" ] }, "BankLinkTokenResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "clientSecret": { "type": "string" }, "sessionId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ] }, "BenefitAccumulatorIdSchema": { "type": "string", "pattern": "^benefit_accumulator_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "benefitGridSchema": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "enum": [ 3 ] }, "coinsurancePercent": { "type": "integer", "enum": [ 20 ] }, "categories": { "$ref": "#/components/schemas/dispatchableCategoriesSchema" }, "pharmacy": { "$ref": "#/components/schemas/pharmacySchema" }, "categoryMap": { "$ref": "#/components/schemas/dispatchableCategoryMapSchema" }, "chronicPreventiveListKey": { "type": "string", "enum": [ "rivendell-chronic-preventive-2026-v1" ] }, "accumulatorPolicy": { "$ref": "#/components/schemas/dispatchableAccumulatorPolicySchema" } }, "required": [ "schemaVersion", "coinsurancePercent", "categories", "pharmacy", "categoryMap", "chronicPreventiveListKey", "accumulatorPolicy" ], "additionalProperties": false }, "BenefitsAssistantOutputSchema": { "type": "object", "properties": { "answer": { "type": "string", "minLength": 1, "maxLength": 4000 }, "citationIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3 }, "suggestedQuestions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 3 } }, "required": [ "answer", "citationIds", "suggestedQuestions" ] }, "BenefitsAssistantRequestSchema": { "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantHistoryMessageSchema" }, "minItems": 1, "maxItems": 8 }, "previousResponseId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "history" ] }, "BenefitsAssistantResponseSchema": { "type": "object", "properties": { "answer": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "href": { "type": "string" } }, "required": [ "title", "href" ] } }, "responseId": { "type": [ "string", "null" ] }, "suggestedQuestions": { "type": "array", "items": { "type": "string" } } }, "required": [ "answer", "citations", "responseId", "suggestedQuestions" ] }, "BenefitsCitationSchema": { "type": "object", "properties": { "title": { "type": "string" }, "href": { "type": "string" } }, "required": [ "title", "href" ] }, "BillingAddressSchema": { "type": "object", "properties": { "city": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "state": { "type": "string" } }, "required": [ "city", "line1", "line2", "postal_code", "state" ] }, "BillingCadenceApiSchema": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ], "description": "Expected recurrence for a known charge" }, "biomarkerObservationSchema": { "type": "object", "properties": { "canonicalName": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "rawName": { "type": "string", "minLength": 1 }, "rawValue": { "type": "number" }, "rawUnit": { "type": "string" }, "loincCode": { "type": "string", "minLength": 1 }, "referenceRanges": { "type": "array", "items": { "$ref": "#/components/schemas/referenceRangeSchema" } }, "flag": { "type": "string", "enum": [ "LOW", "HIGH", "CRITICAL_LOW", "CRITICAL_HIGH", "NORMAL" ] }, "notes": { "type": "string" } }, "required": [ "rawName", "rawValue", "rawUnit" ], "additionalProperties": false }, "BiometricIdSchema": { "type": "string", "pattern": "^biometric_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "BookAppointmentInputSchema": { "type": "object", "properties": { "doctorId": { "allOf": [ { "$ref": "#/components/schemas/DoctorIdSchema" } ], "description": "Primary Rivendell doctor ID" }, "alternateDoctorIds": { "type": "array", "items": { "$ref": "#/components/schemas/DoctorIdSchema" } }, "visitedStatus": { "type": "string", "enum": [ "yes", "no", "maybe" ], "default": "no" }, "location": { "type": "object", "properties": { "zipCode": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "zipCode" ] }, "specialty": { "type": "string", "minLength": 1 }, "careType": { "type": "string", "minLength": 1 }, "symptoms": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "notes": { "type": "string", "maxLength": 2000 }, "urgency": { "type": "string", "enum": [ "routine", "soon", "immediate" ], "default": "soon" }, "visitType": { "type": "string", "enum": [ "virtual", "inperson", "any" ], "default": "inperson" }, "availability": { "$ref": "#/components/schemas/AvailabilityInputSchema" } }, "required": [ "doctorId", "alternateDoctorIds", "visitedStatus", "location", "specialty", "symptoms", "urgency", "visitType", "availability" ] }, "CancelAppointmentInputSchema": { "type": "object", "properties": { "appointmentId": { "allOf": [ { "$ref": "#/components/schemas/DoctorAppointmentJobIdSchema" } ], "description": "Rivendell appointment job ID" } }, "required": [ "appointmentId" ] }, "CancelClaimPaymentRequestSchema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "MEMBER_CANCELED", "REIMBURSED_ELSEWHERE" ] } }, "required": [ "reason" ] }, "CancelPreAuthorizationResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "preAuthorizationId": { "type": "string" }, "preAuthorization": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationSchema" } ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "CanonicalCensusEmployeeSchema": { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/nullableText" }, "firstName": { "$ref": "#/components/schemas/nullableText" }, "lastName": { "$ref": "#/components/schemas/nullableText" }, "dob": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$" }, "sex": { "type": [ "string", "null" ], "enum": [ "M", "F", null ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "$ref": "#/components/schemas/nullableText" }, "enrollmentTier": { "$ref": "#/components/schemas/CensusEnrollmentTierSchema" } }, "required": [ "ref", "firstName", "lastName", "dob", "zip", "sex", "email", "phone", "enrollmentTier" ], "additionalProperties": false }, "CardActivityItemSchema": { "type": "object", "properties": { "id": { "type": "string" }, "cardId": { "type": [ "string", "null" ] }, "decision": { "type": "string" }, "declineReason": { "type": [ "string", "null" ] }, "amount": { "type": "integer" }, "presentmentCurrency": { "type": [ "string", "null" ] }, "merchantDescriptor": { "type": [ "string", "null" ] }, "merchantCategoryCode": { "type": [ "string", "null" ] }, "processingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "cardId", "decision", "declineReason", "amount", "presentmentCurrency", "merchantDescriptor", "merchantCategoryCode", "processingCategory", "createdAt" ] }, "CardActivityQuerySchema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor for pagination" }, "limit": { "description": "Max number of items to return (default 20)", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "decision": { "allOf": [ { "$ref": "#/components/schemas/DecisionSchema" } ], "description": "Filter by decision (approve or decline)" } } }, "CardActivityResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CardActivityItemSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "CardAddressSyncSchema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "synced", "pending" ] }, "cards_updated": { "type": "integer", "minimum": 0 } }, "required": [ "status", "cards_updated" ], "description": "Provider card-address synchronization result" }, "CardAuthorizationLogIdSchema": { "type": "string", "pattern": "^card_authorization_log_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "CardDetailsErrorSchema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages" } }, "required": [ "error" ], "description": "Error response payload" }, "CardDetailsResponseSchema": { "type": "object", "properties": { "cardDetails": { "$ref": "#/components/schemas/CardDetailsSchema" } }, "required": [ "cardDetails" ], "description": "Successful card details response payload" }, "CardDetailsSchema": { "type": "object", "properties": { "card_id": { "type": "string" }, "primary_account_number": { "type": "string" }, "expiration_month": { "type": "number" }, "expiration_year": { "type": "number" }, "verification_code": { "type": "string" }, "pin": { "type": "string" }, "type": { "type": "string", "enum": [ "card_details" ] } }, "required": [ "card_id", "primary_account_number", "expiration_month", "expiration_year", "verification_code", "pin", "type" ] }, "CardErrorSchema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages" } }, "required": [ "error" ], "description": "Error response payload" }, "CardIdParamsSchema": { "type": "object", "properties": { "cardId": { "allOf": [ { "$ref": "#/components/schemas/CardIdSchema" } ], "description": "Unique identifier for the card" } }, "required": [ "cardId" ], "description": "Path parameters for card endpoints" }, "CardIdSchema": { "type": "string", "pattern": "^card_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "CardRecordSchema": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "last4": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "CANCELED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "userId", "last4", "status", "createdAt", "updatedAt" ], "description": "Card record stored in the database" }, "CardResponseSchema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/CardSchema" } }, "required": [ "card" ], "description": "Successful card response payload" }, "CardSchema": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled", "canceled" ] }, "created_at": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "last4": { "type": "string" }, "expiration_month": { "type": "number" }, "expiration_year": { "type": "number" }, "billing_address": { "$ref": "#/components/schemas/BillingAddressSchema" }, "digital_wallet": { "$ref": "#/components/schemas/DigitalWalletSchema" }, "entity_id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "card" ] } }, "required": [ "id", "account_id", "status", "created_at", "description", "last4", "expiration_month", "expiration_year", "billing_address", "digital_wallet", "entity_id", "idempotency_key", "type" ] }, "CardStatusUpdateErrorSchema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages" } }, "required": [ "error" ], "description": "Error response payload" }, "CardStatusUpdateRequestSchema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED" ], "description": "New card status" } }, "required": [ "status" ], "description": "Request body for updating card status" }, "CardStatusUpdateResponseSchema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/CardSchema" } }, "required": [ "card" ], "description": "Updated card response payload" }, "CardStepUpResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "card_step_up_grant" ] }, "token": { "type": "string", "description": "Short-lived grant to send as the x-step-up-token header on GET /cards/{cardId}/details" }, "expires_at": { "type": "number", "description": "Unix seconds at which the grant stops working" } }, "required": [ "object", "token", "expires_at" ], "description": "Step-up grant for revealing sensitive card details" }, "CashPayRateIdSchema": { "type": "string", "pattern": "^cash_pay_rate_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "categoryMapEntrySchema": { "type": "object", "properties": { "inPerson": { "type": "string", "enum": [ "virtualCare", "preventive", "inPersonPrimaryCare", "inPersonUrgentCare", "mentalHealthInPerson", "labWork", "specialist", "generalMedical", "maternity", "dental", "vision", "lifestylePerk" ] }, "virtual": { "type": "string", "enum": [ "virtualCare", "preventive", "inPersonPrimaryCare", "inPersonUrgentCare", "mentalHealthInPerson", "labWork", "specialist", "generalMedical", "maternity", "dental", "vision", "lifestylePerk" ] } }, "required": [ "inPerson" ], "additionalProperties": false }, "CensusDependentEntrySchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Dependent census entry identifier" }, "firstName": { "type": "string", "description": "Dependent first name" }, "lastName": { "type": "string", "description": "Dependent last name" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Dependent email address" }, "dob": { "type": [ "string", "null" ], "format": "date-time", "description": "Dependent date of birth" }, "sex": { "description": "Dependent sex at birth", "allOf": [ { "$ref": "#/components/schemas/SexSchema" } ], "nullable": true }, "zip": { "type": [ "string", "null" ], "description": "Dependent postal ZIP code" }, "relationship": { "allOf": [ { "$ref": "#/components/schemas/RelationshipSchema" } ], "description": "Dependent relationship to employee" }, "activationStatus": { "$ref": "#/components/schemas/DependentActivationStatusSchema" }, "isAdult": { "type": "boolean", "description": "Whether the dependent is 18 or older" } }, "required": [ "id", "firstName", "lastName", "email", "dob", "sex", "zip", "relationship", "activationStatus", "isAdult" ], "description": "Dependent census data for the employee" }, "CensusEnrollmentTierSchema": { "type": "string", "enum": [ "EMPLOYEE_ONLY", "EMPLOYEE_SPOUSE", "EMPLOYEE_CHILD", "EMPLOYEE_FAMILY" ] }, "CensusEntryIdSchema": { "type": "string", "pattern": "^census_entry_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "CensusEntryResponseSchema": { "type": "object", "properties": { "entry": { "allOf": [ { "$ref": "#/components/schemas/CensusEntrySchema" } ], "nullable": true } }, "required": [ "entry" ], "description": "Census entry response payload for the authenticated employee" }, "CensusEntrySchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Census entry identifier" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Employee email address" }, "firstName": { "type": "string", "description": "Employee first name" }, "lastName": { "type": "string", "description": "Employee last name" }, "dob": { "type": [ "string", "null" ], "format": "date-time", "description": "Employee date of birth" }, "sex": { "description": "Employee sex at birth", "allOf": [ { "$ref": "#/components/schemas/SexSchema" } ], "nullable": true }, "zip": { "type": [ "string", "null" ], "description": "Employee postal ZIP code" }, "enrollmentTier": { "description": "Employee enrollment tier for health plan coverage", "allOf": [ { "$ref": "#/components/schemas/EnrollmentTierSchema" } ], "nullable": true }, "dependents": { "type": "array", "items": { "$ref": "#/components/schemas/CensusDependentEntrySchema" } } }, "required": [ "id", "email", "firstName", "lastName", "dob", "sex", "zip", "enrollmentTier", "dependents" ], "description": "Census entry for the authenticated employee" }, "CensusExtractionSchema": { "type": "object", "properties": { "companyName": { "$ref": "#/components/schemas/nullableText" }, "effectiveDate": { "type": [ "string", "null" ], "format": "date" }, "employees": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalCensusEmployeeSchema" }, "maxItems": 5000 }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/CensusIssueSchema" }, "maxItems": 5000 } }, "required": [ "companyName", "effectiveDate", "employees", "issues" ], "additionalProperties": false }, "CensusIssueSchema": { "type": "object", "properties": { "row": { "type": "string", "minLength": 1 }, "missingFields": { "type": "array", "items": { "type": "string", "enum": [ "zip", "enrollmentTier", "effectiveDate" ] }, "minItems": 1 }, "note": { "$ref": "#/components/schemas/nullableText" } }, "required": [ "row", "missingFields", "note" ], "additionalProperties": false }, "CensusQuoteRequestSchema": { "type": "object", "properties": { "effectiveDate": { "type": "string", "format": "date", "description": "Coverage start date, YYYY-MM-DD." }, "csv": { "type": "string", "minLength": 1, "maxLength": 2000000 }, "employees": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "minLength": 1, "description": "Canonical tier or common wording such as EE Only, Family, or EE + Spouse." }, "zip": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } }, "required": [ "tier" ] }, "minItems": 1, "maxItems": 5000 }, "elections": { "allOf": [ { "$ref": "#/components/schemas/ElectionsSchema" } ] }, "benchmarkAnnualCents": { "type": "integer", "exclusiveMinimum": 0 }, "correction": { "type": "string", "enum": [ "auto", "always", "disabled" ] } }, "required": [ "effectiveDate" ] }, "CensusQuoteResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "census_quote" ] }, "designVersion": { "$ref": "#/components/schemas/CurrentPlanDesignKeySchema" }, "rateBasis": { "type": "object", "properties": { "label": { "type": "string" }, "pricedThrough": { "type": "string" } }, "required": [ "label", "pricedThrough" ] }, "anchorMetro": { "type": [ "string", "null" ] }, "fallbackFactor": { "type": "number" }, "totalEmployees": { "type": "integer" }, "tierCounts": { "type": "object", "properties": { "EMPLOYEE_ONLY": { "type": "integer" }, "EMPLOYEE_SPOUSE": { "type": "integer" }, "EMPLOYEE_CHILD": { "type": "integer" }, "EMPLOYEE_FAMILY": { "type": "integer" } }, "required": [ "EMPLOYEE_ONLY", "EMPLOYEE_SPOUSE", "EMPLOYEE_CHILD", "EMPLOYEE_FAMILY" ] }, "fallbackPricedEmployees": { "type": "integer" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "elections": { "$ref": "#/components/schemas/ElectionsSchema" }, "monthly": { "$ref": "#/components/schemas/MoneyBreakdownSchema" }, "annual": { "$ref": "#/components/schemas/MoneyBreakdownSchema" }, "employees": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": [ "string", "null" ] }, "tier": { "$ref": "#/components/schemas/EnrollmentTierSchema" }, "location": { "type": [ "string", "null" ] }, "regionalFactor": { "type": "number" }, "fallbackPriced": { "type": "boolean" }, "insuranceMonthlyCents": { "type": "integer" }, "hsaSeedMonthlyCents": { "type": "integer" }, "addOnsMonthlyCents": { "type": "integer" }, "totalMonthlyCents": { "type": "integer" } }, "required": [ "ref", "tier", "location", "regionalFactor", "fallbackPriced", "insuranceMonthlyCents", "hsaSeedMonthlyCents", "addOnsMonthlyCents", "totalMonthlyCents" ] } }, "blendedTiers": { "type": "array", "items": { "type": "object", "properties": { "tier": { "$ref": "#/components/schemas/EnrollmentTierSchema" }, "employees": { "type": "integer" }, "insuranceMonthlyCentsTotal": { "type": "integer" }, "totalMonthlyCentsTotal": { "type": "integer" }, "insuranceMonthlyCentsPerEmployee": { "type": "integer" }, "totalMonthlyCentsPerEmployee": { "type": "integer" } }, "required": [ "tier", "employees", "insuranceMonthlyCentsTotal", "totalMonthlyCentsTotal", "insuranceMonthlyCentsPerEmployee", "totalMonthlyCentsPerEmployee" ] } }, "comparison": { "type": [ "object", "null" ], "properties": { "benchmarkAnnualCents": { "type": "integer" }, "deltaAnnualCents": { "type": "integer" }, "deltaPercent": { "type": "number" } }, "required": [ "benchmarkAnnualCents", "deltaAnnualCents", "deltaPercent" ] } }, "required": [ "label", "elections", "monthly", "annual", "employees", "blendedTiers", "comparison" ] } }, "warnings": { "type": "array", "items": { "type": "string" } }, "normalizedCensus": { "$ref": "#/components/schemas/NormalizedCensusSchema" }, "source": { "type": "object", "properties": { "normalization": { "type": "string", "enum": [ "deterministic", "model" ] }, "censusFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "warnings": { "type": "array", "items": { "type": "string" } }, "columns": { "type": [ "object", "null" ], "properties": { "zip": { "type": "string" }, "tier": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "effectiveDate": { "type": [ "string", "null" ] } }, "required": [ "zip", "tier", "id", "effectiveDate" ] }, "correction": { "type": [ "object", "null" ], "properties": { "model": { "type": "string" }, "promptVersion": { "type": "string" }, "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "cacheHit": { "type": "boolean" } }, "required": [ "model", "promptVersion", "sourceHash", "cacheHit" ] }, "effectiveDate": { "type": "string", "format": "date" } }, "required": [ "normalization", "censusFingerprint", "warnings", "columns", "correction", "effectiveDate" ] } }, "required": [ "object", "designVersion", "rateBasis", "anchorMetro", "fallbackFactor", "totalEmployees", "tierCounts", "fallbackPricedEmployees", "variants", "warnings", "normalizedCensus", "source" ] }, "CensusUploadFormDataSchema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream" }, "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "file" ], "description": "Multipart payload containing a census file for analysis." }, "CensusUploadResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "url": { "type": "string", "format": "uri", "description": "Signed URL for the uploaded census file" }, "fileKey": { "type": "string", "description": "R2 object key for the uploaded census file" }, "filename": { "type": "string", "description": "Original census filename" }, "contentType": { "type": "string", "description": "MIME type preserved from the uploaded census file" }, "fileSize": { "type": "integer", "minimum": 0, "description": "Original census file size in bytes" } }, "required": [ "success", "url", "fileKey", "filename", "contentType", "fileSize" ], "description": "Successful census file upload response" }, "centsSchema": { "type": "integer", "minimum": 0 }, "ChronicitySchema": { "type": "string", "enum": [ "CHRONIC", "ACUTE", "UNKNOWN" ] }, "ClaimAdjudicationSnapshotIdSchema": { "type": "string", "pattern": "^claim_adjudication_snapshot_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClaimBillingTypeApiSchema": { "type": "string", "enum": [ "SERVICE", "MEMBERSHIP" ], "description": "Whether the charge purchased rendered care or program access" }, "ClaimDetailsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^claim_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "source": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "billingType": { "$ref": "#/components/schemas/ClaimBillingTypeApiSchema" }, "billingCadence": { "allOf": [ { "$ref": "#/components/schemas/BillingCadenceApiSchema" } ], "nullable": true }, "membershipProgram": { "type": [ "string", "null" ] }, "submittedAmount": { "type": "number" }, "approvedAmount": { "type": [ "number", "null" ] }, "memberOwes": { "type": [ "number", "null" ] }, "deductibleApplied": { "type": [ "number", "null" ] }, "coinsuranceApplied": { "type": [ "number", "null" ] }, "serviceDate": { "type": "string", "format": "date-time" }, "merchantName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "receiptUrl": { "type": [ "string", "null" ] }, "uploadedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rejectionReason": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "adjudication": { "type": [ "object", "null" ], "properties": { "outcome": { "type": "string", "description": "Engine outcome code. Diagnostics only, never displayed." }, "rule": { "type": "string", "description": "Engine rule path. Diagnostics only, never displayed." }, "treatment": { "type": "string", "description": "Engine treatment code. Diagnostics only, never displayed." }, "note": { "type": [ "string", "null" ], "description": "Engine note. Diagnostics only, never displayed." }, "summary": { "type": "string", "description": "The member-language explanation. This is the only field of this object intended for display." } }, "required": [ "outcome", "rule", "treatment", "note", "summary" ] }, "reviewer": { "type": [ "object", "null" ], "properties": { "firstName": { "type": "string" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "firstName", "reviewedAt" ] }, "substantiation": { "type": [ "object", "null" ], "properties": { "method": { "type": "string" }, "label": { "type": "string", "description": "Member-language label for how the bill was checked" }, "substantiatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "method", "label", "substantiatedAt" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "enrollment": { "type": "object", "properties": { "id": { "type": "string" }, "healthPlan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "id", "healthPlan" ] }, "memberInvoiceSummary": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "parseStatus": { "type": "string", "enum": [ "PENDING", "SUCCESS", "PARTIAL", "FAILED" ] }, "parseWarningsCount": { "type": "integer" }, "totalChargedCents": { "type": [ "integer", "null" ] } }, "required": [ "id", "parseStatus", "parseWarningsCount", "totalChargedCents" ] }, "transaction": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "merchantName": { "type": [ "string", "null" ] }, "authorizedAmount": { "type": "number" }, "settledAmount": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "required": [ "id", "externalId", "merchantName", "authorizedAmount", "settledAmount", "status" ] } }, "required": [ "object", "id", "created", "livemode", "metadata", "source", "status", "category", "billingType", "billingCadence", "membershipProgram", "submittedAmount", "approvedAmount", "memberOwes", "deductibleApplied", "coinsuranceApplied", "serviceDate", "merchantName", "description", "receiptUrl", "uploadedAt", "rejectionReason", "notes", "reviewedAt", "adjudication", "reviewer", "substantiation", "createdAt", "updatedAt", "enrollment", "memberInvoiceSummary", "transaction" ], "additionalProperties": true }, "ClaimIdParamsSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" } }, "required": [ "id" ], "description": "Path parameters for claim endpoints" }, "ClaimIdSchema": { "type": "string", "pattern": "^claim_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClaimIntakeServiceCategorySchema": { "type": "string" }, "ClaimInvoiceRequestSchema": { "type": "object", "properties": { "receiptKey": { "type": "string", "minLength": 1 }, "doctorId": { "allOf": [ { "$ref": "#/components/schemas/DoctorIdSchema" } ], "description": "Doctor ID associated with the invoice" } }, "required": [ "receiptKey", "doctorId" ] }, "ClaimInvoiceResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "claimId": { "type": "string" }, "memberInvoiceId": { "type": "string" }, "parseStatus": { "type": "string", "enum": [ "PENDING", "SUCCESS", "PARTIAL", "FAILED" ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "ClaimInvoiceStatusResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "memberInvoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "parseStatus": { "type": "string", "enum": [ "PENDING", "SUCCESS", "PARTIAL", "FAILED" ] }, "parseWarnings": { "type": "array", "items": { "type": "string" } }, "parseFailureReason": { "type": [ "string", "null" ] }, "invoiceDate": { "type": [ "string", "null" ], "format": "date-time" }, "serviceDate": { "type": [ "string", "null" ], "format": "date-time" }, "totalChargedCents": { "type": [ "integer", "null" ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "lineIndex": { "type": "integer" }, "serviceName": { "type": [ "string", "null" ] }, "cptCode": { "type": [ "string", "null" ] }, "amountCents": { "type": "integer" }, "quotedRateId": { "type": [ "string", "null" ] }, "invoiceActualRateId": { "type": [ "string", "null" ] } }, "required": [ "id", "lineIndex", "serviceName", "cptCode", "amountCents", "quotedRateId", "invoiceActualRateId" ] } } }, "required": [ "id", "parseStatus", "parseWarnings", "parseFailureReason", "invoiceDate", "serviceDate", "totalChargedCents", "lineItems" ] } }, "required": [ "success", "memberInvoice" ] }, "ClaimListItemSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^claim_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "source": { "$ref": "#/components/schemas/ClaimSourceSchema" }, "status": { "$ref": "#/components/schemas/ClaimStatusSchema" }, "category": { "$ref": "#/components/schemas/ServiceCategoryReadSchema" }, "billingType": { "$ref": "#/components/schemas/ClaimBillingTypeApiSchema" }, "billingCadence": { "allOf": [ { "$ref": "#/components/schemas/BillingCadenceApiSchema" } ], "nullable": true }, "membershipProgram": { "type": [ "string", "null" ] }, "submittedAmount": { "type": "integer" }, "approvedAmount": { "type": [ "integer", "null" ] }, "memberOwes": { "type": [ "integer", "null" ] }, "serviceDate": { "type": "string", "format": "date-time" }, "merchantName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "receiptUrl": { "type": [ "string", "null" ], "format": "uri" }, "uploadedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "transaction": { "allOf": [ { "$ref": "#/components/schemas/ClaimListTransactionSchema" } ], "nullable": true } }, "required": [ "object", "id", "created", "livemode", "metadata", "source", "status", "category", "billingType", "billingCadence", "membershipProgram", "submittedAmount", "approvedAmount", "memberOwes", "serviceDate", "merchantName", "description", "receiptUrl", "uploadedAt", "createdAt", "updatedAt", "transaction" ], "additionalProperties": true }, "ClaimListTransactionSchema": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "merchantName": { "type": [ "string", "null" ] }, "authorizedAmount": { "type": "integer" }, "settledAmount": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/TransactionStatusSchema" } }, "required": [ "id", "externalId", "merchantName", "authorizedAmount", "settledAmount", "status" ] }, "ClaimModalityApiSchema": { "type": "string", "enum": [ "IN_PERSON", "VIRTUAL" ], "description": "How care was delivered; defaults to IN_PERSON when omitted" }, "ClaimModalitySchema": { "type": "string", "enum": [ "IN_PERSON", "VIRTUAL" ] }, "ClaimPaymentAuthorizationIdSchema": { "type": "string", "pattern": "^claim_payment_authorization_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClaimPaymentAuthorizationModeSchema": { "type": "string", "enum": [ "ASK_EVERY_TIME", "AUTO_WITH_REVIEW_WINDOW" ] }, "ClaimPaymentAuthorizationResourceSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim_payment_authorization" ] }, "id": { "type": "string" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/ApiMetadataSchema" }, "mode": { "$ref": "#/components/schemas/ClaimPaymentAuthorizationModeSchema" }, "enrollment_id": { "type": "string" }, "hsa_account_id": { "type": [ "string", "null" ] }, "terms_version": { "type": "string" }, "consent_text": { "type": "string" }, "review_window_minutes": { "type": "integer" }, "dependent_expenses_allowed": { "type": "boolean" }, "runout_allowed": { "type": "boolean" }, "accepted_at": { "type": "integer" }, "effective_at": { "type": "integer" }, "revoked_at": { "type": [ "integer", "null" ] } }, "required": [ "object", "id", "created", "livemode", "metadata", "mode", "enrollment_id", "hsa_account_id", "terms_version", "consent_text", "review_window_minutes", "dependent_expenses_allowed", "runout_allowed", "accepted_at", "effective_at", "revoked_at" ] }, "ClaimPaymentAuthorizationResponseSchema": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/ClaimPaymentAuthorizationModeSchema" }, "effective": { "type": "boolean" }, "execution_enabled": { "type": "boolean" }, "review_window_minutes": { "type": "integer" }, "coverage_ends_at": { "type": [ "integer", "null" ] }, "terms_version": { "type": "string" }, "consent_text_by_mode": { "type": "object", "properties": { "ASK_EVERY_TIME": { "type": "string" }, "AUTO_WITH_REVIEW_WINDOW": { "type": "string" } }, "required": [ "ASK_EVERY_TIME", "AUTO_WITH_REVIEW_WINDOW" ] }, "authorization": { "allOf": [ { "$ref": "#/components/schemas/ClaimPaymentAuthorizationResourceSchema" } ], "nullable": true } }, "required": [ "mode", "effective", "execution_enabled", "review_window_minutes", "coverage_ends_at", "terms_version", "consent_text_by_mode", "authorization" ] }, "ClaimPaymentProposalIdSchema": { "type": "string", "pattern": "^claim_payment_proposal_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClaimPaymentProposalResourceSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim_payment_proposal" ] }, "id": { "type": "string" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/ApiMetadataSchema" }, "claim_id": { "type": "string" }, "adjudication_snapshot_id": { "type": "string" }, "authorization_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTION_REQUIRED", "NOTICE_PENDING", "NOTICE_SENDING", "SCHEDULED", "PROCESSING", "PAID", "FAILED", "CANCELED", "PARTIALLY_REFUNDED", "REFUNDED" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "selected_source": { "allOf": [ { "$ref": "#/components/schemas/ClaimPaymentSourceSchema" } ], "nullable": true }, "initiation_mode": { "type": [ "string", "null" ], "enum": [ "MEMBER_CONFIRMED", "AUTOMATIC", null ] }, "hsa_account_id": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "integer", "null" ] }, "execute_after": { "type": [ "integer", "null" ] }, "confirmed_at": { "type": [ "integer", "null" ] }, "confirmed_consent_text": { "type": [ "string", "null" ] }, "confirmed_consent_version": { "type": [ "string", "null" ] }, "processing_at": { "type": [ "integer", "null" ] }, "completed_at": { "type": [ "integer", "null" ] }, "canceled_at": { "type": [ "integer", "null" ] }, "cancellation_reason": { "type": [ "string", "null" ] }, "failure_code": { "type": [ "string", "null" ] }, "fund_transfer_id": { "type": [ "string", "null" ] }, "refunded_amount_cents": { "type": "integer" }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimPaymentRefundResourceSchema" } } }, "required": [ "object", "id", "created", "livemode", "metadata", "claim_id", "adjudication_snapshot_id", "authorization_id", "status", "amount_cents", "currency", "selected_source", "initiation_mode", "hsa_account_id", "bank_account_id", "scheduled_at", "execute_after", "confirmed_at", "confirmed_consent_text", "confirmed_consent_version", "processing_at", "completed_at", "canceled_at", "cancellation_reason", "failure_code", "fund_transfer_id", "refunded_amount_cents", "refunds" ] }, "ClaimPaymentProposalResponseSchema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "NOT_READY", "NOT_REQUIRED", "ACTION_REQUIRED", "NOTICE_PENDING", "NOTICE_SENDING", "SCHEDULED", "PROCESSING", "PAID", "FAILED", "CANCELED", "PARTIALLY_REFUNDED", "REFUNDED" ] }, "proposal": { "allOf": [ { "$ref": "#/components/schemas/ClaimPaymentProposalResourceSchema" } ], "nullable": true }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimPaymentSourceOptionSchema" } } }, "required": [ "state", "proposal", "sources" ] }, "ClaimPaymentRefundIdSchema": { "type": "string", "pattern": "^claim_payment_refund_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClaimPaymentRefundResourceSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim_payment_refund" ] }, "id": { "type": "string" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/ApiMetadataSchema" }, "source": { "$ref": "#/components/schemas/ClaimPaymentSourceSchema" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELED" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "fund_transfer_id": { "type": [ "string", "null" ] }, "failure_code": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "integer", "null" ] } }, "required": [ "object", "id", "created", "livemode", "metadata", "source", "status", "amount_cents", "currency", "fund_transfer_id", "failure_code", "completed_at" ] }, "ClaimPaymentSourceOptionSchema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ClaimPaymentSourceSchema" }, "available": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "AVAILABLE", "HSA_NOT_ELIGIBLE", "OTHER_REIMBURSEMENT_REPORTED", "HSA_ACCOUNT_NOT_OPEN", "EXPENSE_PREDATES_HSA", "INSUFFICIENT_HSA_BALANCE", "BANK_ACCOUNT_NOT_LINKED", "BANK_ACCOUNT_RELINK_REQUIRED", "PROCESSOR_NOT_CONFIGURED" ] }, "account_id": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] }, "available_balance_cents": { "type": [ "integer", "null" ] }, "confirmation_text": { "type": [ "string", "null" ] }, "confirmation_version": { "type": [ "string", "null" ] } }, "required": [ "source", "available", "reason", "account_id", "last4", "available_balance_cents", "confirmation_text", "confirmation_version" ] }, "ClaimPaymentSourceSchema": { "type": "string", "enum": [ "HSA", "BANK_ACCOUNT", "CARD" ] }, "ClaimPaymentStepUpGrantIdSchema": { "type": "string", "pattern": "^claim_payment_step_up_grant_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClaimPaymentStepUpResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim_payment_step_up_grant" ] }, "token": { "type": "string" }, "expires_at": { "type": "integer" } }, "required": [ "object", "token", "expires_at" ] }, "ClaimsListQuerySchema": { "type": "object", "properties": { "status": { "type": "string", "description": "Comma-separated claim statuses (e.g. SUBMITTED,APPROVED)" }, "source": { "allOf": [ { "$ref": "#/components/schemas/ClaimSourceSchema" } ], "description": "Claim source filter" }, "limit": { "description": "Max number of claims to return", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "offset": { "description": "Offset for pagination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "ClaimsListResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimListItemSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "ClaimSourceSchema": { "type": "string", "enum": [ "CARD_TRANSACTION", "REIMBURSEMENT" ] }, "ClaimStatusFilterSchema": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimStatusSchema" } }, "ClaimStatusSchema": { "type": "string", "enum": [ "DRAFT", "PENDING_SUBSTANTIATION", "SUBMITTED", "IN_REVIEW", "APPROVED", "REJECTED", "PAID" ] }, "CleanupPdfRequestSchema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "Relative filename under public/generated to remove" } }, "required": [ "filename" ], "description": "PDF cleanup request body" }, "CleanupPdfResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the operation succeeded" }, "message": { "type": "string", "description": "Success message" }, "error": { "type": "string", "description": "Failure reason when success is false" } }, "required": [ "success" ], "description": "Result of the PDF cleanup operation" }, "clientSchema": { "type": "object", "properties": { "NEXT_PUBLIC_APP_URL": { "type": "string", "format": "uri", "default": "http://localhost:3000" }, "NEXT_PUBLIC_POSTHOG_KEY": { "type": "string" }, "NEXT_PUBLIC_GOOGLE_CLIENT_ID": { "type": "string" }, "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY": { "type": "string" }, "NEXT_PUBLIC_APP_DOWNLOAD_URL": { "type": "string", "format": "uri", "default": "https://apps.apple.com/us/app/rivendell-health/id6752309679" }, "NEXT_PUBLIC_ASSET_BASE_URL": { "type": "string", "format": "uri", "default": "https://assets.rivendell.health" } }, "required": [ "NEXT_PUBLIC_APP_URL", "NEXT_PUBLIC_GOOGLE_CLIENT_ID", "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY", "NEXT_PUBLIC_APP_DOWNLOAD_URL", "NEXT_PUBLIC_ASSET_BASE_URL" ] }, "ClinicalGateRecordIdSchema": { "type": "string", "pattern": "^clinical_gate_record_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ClinicalGateRecordParamsSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ClinicalGateRecordIdSchema" } ], "description": "Clinical gate record ID" } }, "required": [ "id" ], "description": "Path parameters for clinical gate admin actions" }, "ClinicalGateRecordSchema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ClinicalGateRecordIdSchema" }, "userId": { "$ref": "#/components/schemas/UserIdSchema" }, "gateType": { "type": "string" }, "source": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveUntil": { "type": [ "string", "null" ], "format": "date-time" }, "evidenceRef": { "type": [ "string", "null" ] }, "createdBy": { "$ref": "#/components/schemas/UserIdSchema" }, "endedBy": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "nullable": true }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean" } }, "required": [ "id", "userId", "gateType", "source", "effectiveFrom", "effectiveUntil", "evidenceRef", "createdBy", "endedBy", "endedAt", "createdAt", "updatedAt", "livemode" ] }, "ConditionBucketSchema": { "type": "string", "enum": [ "RESPIRATORY", "CARDIOVASCULAR", "METABOLIC", "ENDOCRINE", "NEUROLOGIC", "MENTAL_HEALTH", "MUSCULOSKELETAL", "GASTROINTESTINAL", "DERMATOLOGIC", "IMMUNE_AUTOIMMUNE", "ONCOLOGY", "RENAL_UROLOGIC", "REPRODUCTIVE", "INFECTIOUS", "HEMATOLOGIC", "OTHER" ] }, "ConditionItemSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Condition name as provided by the user" }, "normalizedName": { "type": "string", "minLength": 1, "description": "Normalized condition name for internal use" }, "bucket": { "allOf": [ { "$ref": "#/components/schemas/ConditionBucketSchema" } ], "description": "Coarse bucket for routing/care programs" }, "chronicity": { "allOf": [ { "$ref": "#/components/schemas/ChronicitySchema" } ], "description": "Whether the condition is chronic or acute" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence between 0 and 1" } }, "required": [ "name", "chronicity" ] }, "ConfirmClaimPaymentRequestSchema": { "type": "object", "properties": { "proposalId": { "$ref": "#/components/schemas/ClaimPaymentProposalIdSchema" }, "amountCents": { "type": "integer", "exclusiveMinimum": 0 }, "source": { "$ref": "#/components/schemas/ClaimPaymentSourceSchema" }, "bankAccountId": { "allOf": [ { "$ref": "#/components/schemas/BankAccountIdSchema" } ], "nullable": true }, "consentAccepted": { "type": "boolean", "enum": [ true ] }, "consentVersion": { "type": "string" }, "confirmationText": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "proposalId", "amountCents", "source", "consentAccepted", "consentVersion", "confirmationText" ] }, "ConfirmedMajorCareItemSchema": { "type": "object", "properties": { "doctorId": { "type": "string", "minLength": 1, "description": "Linked doctor ID when selected" }, "description": { "type": "string", "minLength": 1, "description": "User-described procedure or condition" }, "type": { "allOf": [ { "$ref": "#/components/schemas/MajorCareTypeSchema" } ], "description": "Whether the item is a procedure or condition" }, "timeframe": { "allOf": [ { "$ref": "#/components/schemas/MajorCareTimeframeSchema" } ], "description": "Rough timeframe for when the care occurred" }, "facility": { "type": [ "string", "null" ], "minLength": 1, "description": "Facility or hospital name if known" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence between 0 and 1" }, "missingFields": { "type": "array", "items": { "type": "string", "enum": [ "facility", "timeframe", "description", "type" ] }, "description": "Fields that require follow-up before confirmation" } }, "required": [ "description", "type", "timeframe", "facility" ] }, "CopayCollectionIdSchema": { "type": "string", "pattern": "^copay_collection_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "CostPlusDrugResultSchema": { "type": "object", "properties": { "brand_name": { "type": [ "string", "null" ] }, "brand_generic": { "type": [ "string", "null" ] }, "form": { "type": [ "string", "null" ] }, "medication_name": { "type": [ "string", "null" ] }, "ndc": { "type": [ "string", "null" ] }, "pill_nonpill": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "strength": { "type": [ "string", "null" ] }, "unit_price": { "type": [ "string", "null" ] }, "unit_billing_price": { "type": [ "string", "null" ] }, "requested_quote": { "type": [ "string", "null" ] }, "requested_quote_units": { "type": [ "string", "null" ] }, "auto_refill": { "type": [ "boolean", "null" ] }, "insurance_eligible": { "type": [ "string", "null" ] }, "medispan_pack_size": { "type": [ "string", "null" ] }, "medispan_pack_size_units": { "type": [ "string", "null" ] }, "medispan_quantity": { "type": [ "string", "null" ] }, "special_handling": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "CostPlusDrugsResponseSchema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CostPlusDrugResultSchema" } } }, "required": [ "results" ] }, "CoverageBreakdownSchema": { "type": "object", "properties": { "submittedAmount": { "type": "number" }, "categoryCoverage": { "type": "string" }, "deductibleRemaining": { "type": "number" }, "oopMaxRemaining": { "type": "number" }, "stipendRemaining": { "type": "number" } }, "required": [ "submittedAmount", "categoryCoverage", "deductibleRemaining", "oopMaxRemaining" ] }, "CoverageEstimateSchema": { "type": "object", "properties": { "copay": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Member out-of-pocket responsibility after insurance" }, "deductibleApplied": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Amount applied to deductible" }, "coinsuranceApplied": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Amount applied as coinsurance" }, "planPays": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Amount covered by the plan" }, "fullyCovered": { "type": "boolean", "description": "Whether the visit is fully covered, such as primary care" } }, "required": [ "copay", "deductibleApplied", "coinsuranceApplied", "planPays", "fullyCovered" ] }, "CoverageResultSchema": { "type": "object", "properties": { "approvedAmount": { "type": "number" }, "memberOwes": { "type": "number" }, "deductibleApplied": { "type": "number" }, "coinsuranceApplied": { "type": "number" }, "fullyCovered": { "type": "boolean" }, "outcome": { "type": "string" }, "trace": { "type": "object", "properties": { "rule": { "type": "string" }, "treatment": { "type": "string" }, "note": { "type": "string" } }, "required": [ "rule", "treatment" ] }, "breakdown": { "$ref": "#/components/schemas/CoverageBreakdownSchema" } }, "required": [ "approvedAmount", "memberOwes", "deductibleApplied", "coinsuranceApplied", "fullyCovered", "breakdown" ] }, "CreateAccountErrorSchema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages" } }, "required": [ "error" ], "description": "Error response payload" }, "CreateAccountInputSchema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Account name (max 200 characters)" }, "entity_id": { "type": "string", "description": "Entity that will own the account (defaults to INCREASE_RIVENDELL_ENTITY_ID)" }, "informational_entity_id": { "type": "string", "description": "Entity associated with activity but not owning the account" } }, "required": [ "name" ] }, "CreateAccountResponseSchema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountSchema" } }, "required": [ "account" ], "description": "Successful account creation response" }, "CreateCardBillingAddressSchema": { "type": "object", "properties": { "city": { "type": "string", "maxLength": 200, "description": "City" }, "line1": { "type": "string", "maxLength": 200, "description": "First line of the address" }, "line2": { "type": "string", "maxLength": 200, "description": "Second line of the address" }, "postal_code": { "type": "string", "maxLength": 200, "description": "Postal code" }, "state": { "type": "string", "maxLength": 200, "description": "State" } }, "required": [ "city", "line1", "postal_code", "state" ] }, "CreateCardClaimSchema": { "type": "object", "properties": { "enrollmentId": { "type": "string" }, "transactionId": { "type": "string" }, "serviceCategory": { "$ref": "#/components/schemas/ClaimIntakeServiceCategorySchema" }, "modality": { "type": "string" }, "billingType": { "type": "string" }, "billingCadence": { "type": [ "string", "null" ] }, "membershipProgram": { "type": [ "string", "null" ], "minLength": 1 }, "personUserId": { "type": "string" }, "submittedAmount": { "type": "integer", "exclusiveMinimum": 0 }, "serviceDate": { "type": "string", "format": "date-time" }, "merchantName": { "type": "string" } }, "required": [ "enrollmentId", "transactionId", "serviceCategory", "submittedAmount", "serviceDate" ] }, "CreateCardDigitalWalletSchema": { "type": "object", "properties": { "digital_card_profile_id": { "type": "string", "description": "Digital card profile ID" }, "email": { "type": "string", "maxLength": 200, "description": "Email for two-factor auth" }, "phone": { "type": "string", "maxLength": 200, "description": "Phone for two-factor auth" } } }, "CreateCardErrorSchema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages" } }, "required": [ "error" ], "description": "Error response payload" }, "CreateCardInputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "description": "The Account the card should belong to" }, "billing_address": { "allOf": [ { "$ref": "#/components/schemas/CreateCardBillingAddressSchema" } ], "description": "Card billing address" }, "description": { "type": "string", "maxLength": 200, "description": "Card description for display" }, "digital_wallet": { "allOf": [ { "$ref": "#/components/schemas/CreateCardDigitalWalletSchema" } ], "description": "Contact information for digital wallet setup" }, "entity_id": { "type": "string", "description": "Entity the card belongs to" } }, "required": [ "account_id" ] }, "CreateCardRequestSchema": { "type": "object", "properties": { "billing_address": { "allOf": [ { "$ref": "#/components/schemas/CreateCardBillingAddressSchema" } ], "description": "Deprecated and ignored; the server uses the member residential address" }, "description": { "type": "string", "description": "Deprecated and ignored; the server derives the card name" }, "digital_wallet": { "allOf": [ { "$ref": "#/components/schemas/CreateCardDigitalWalletSchema" } ], "description": "Contact information for digital wallet setup" } }, "additionalProperties": false, "description": "Request body for creating a card" }, "CreateCardResponseSchema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/CardSchema" } }, "required": [ "card" ], "description": "Successful card creation response" }, "CreateClinicalGateRequestSchema": { "type": "object", "properties": { "enrollmentId": { "$ref": "#/components/schemas/EnrollmentIdSchema" }, "organizationId": { "$ref": "#/components/schemas/OrganizationIdSchema" }, "userId": { "$ref": "#/components/schemas/UserIdSchema" }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveUntil": { "type": [ "string", "null" ], "format": "date-time" }, "evidenceRef": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "enrollmentId", "organizationId", "userId", "effectiveFrom", "evidenceRef" ] }, "CreateClinicalGateResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "clinicalGateRecord": { "$ref": "#/components/schemas/ClinicalGateRecordSchema" } }, "required": [ "success", "clinicalGateRecord" ] }, "CreateLegalAcceptanceRequestSchema": { "type": "object", "discriminator": { "propertyName": "platform" }, "oneOf": [ { "type": "object", "properties": { "subjectUserId": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Person whose acceptance is recorded, either the authenticated user or a covered minor child they represent" }, "documentType": { "$ref": "#/components/schemas/LegalDocumentTypeSchema" }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "documentContentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Client-observed hash of the exact published document. The server rejects a mismatch and remains authoritative." }, "appVersion": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] }, "platform": { "type": "string", "enum": [ "ios" ] }, "appBuild": { "$ref": "#/components/schemas/RequiredMobileAppBuildSchema" } }, "required": [ "documentType", "documentVersion", "platform", "appBuild" ] }, { "type": "object", "properties": { "subjectUserId": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Person whose acceptance is recorded, either the authenticated user or a covered minor child they represent" }, "documentType": { "$ref": "#/components/schemas/LegalDocumentTypeSchema" }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "documentContentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Client-observed hash of the exact published document. The server rejects a mismatch and remains authoritative." }, "appVersion": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] }, "platform": { "type": "string", "enum": [ "android" ] }, "appBuild": { "$ref": "#/components/schemas/RequiredMobileAppBuildSchema" } }, "required": [ "documentType", "documentVersion", "platform", "appBuild" ] }, { "type": "object", "properties": { "subjectUserId": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Person whose acceptance is recorded, either the authenticated user or a covered minor child they represent" }, "documentType": { "$ref": "#/components/schemas/LegalDocumentTypeSchema" }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "documentContentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Client-observed hash of the exact published document. The server rejects a mismatch and remains authoritative." }, "appVersion": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] }, "platform": { "type": "string", "enum": [ "web" ] }, "appBuild": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] } }, "required": [ "documentType", "documentVersion", "platform" ] }, { "type": "object", "properties": { "subjectUserId": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Person whose acceptance is recorded, either the authenticated user or a covered minor child they represent" }, "documentType": { "$ref": "#/components/schemas/LegalDocumentTypeSchema" }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "documentContentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Client-observed hash of the exact published document. The server rejects a mismatch and remains authoritative." }, "appVersion": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] }, "platform": { "type": "string", "enum": [ "other" ] }, "appBuild": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] } }, "required": [ "documentType", "documentVersion", "platform" ] } ] }, "CreateLegalAcceptanceResponseSchema": { "type": "object", "properties": { "acceptance": { "$ref": "#/components/schemas/LegalAcceptanceSchema" } }, "required": [ "acceptance" ] }, "CreateMemberMedicationRequestSchema": { "type": "object", "properties": { "ndc": { "allOf": [ { "$ref": "#/components/schemas/NdcSchema" } ], "nullable": true }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "strength": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "form": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "prescriberName": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "pharmacyPreference": { "allOf": [ { "$ref": "#/components/schemas/PharmacyPreferenceSchema" } ], "default": "amazon_pharmacy" }, "lastFilledAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "displayName" ], "description": "A medication the authenticated member currently takes." }, "CreateMemberPreAuthorizationRequestSchema": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/ActiveServiceCategorySchema" }, "modality": { "allOf": [ { "$ref": "#/components/schemas/ClaimModalityApiSchema" } ] }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "description": { "type": "string", "maxLength": 500, "description": "What the care is for, in the member's words" } }, "required": [ "category", "amount" ] }, "CreateMerchantRuleResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "merchantRule": { "$ref": "#/components/schemas/MerchantRuleSchema" } }, "required": [ "success", "merchantRule" ] }, "CreateMerchantRuleSchema": { "type": "object", "properties": { "merchantPattern": { "type": "string", "minLength": 3, "maxLength": 200 }, "merchantCategoryCode": { "type": "string", "pattern": "^\\d{4}$" }, "serviceCategory": { "type": "string" }, "modality": { "allOf": [ { "$ref": "#/components/schemas/ClaimModalitySchema" } ] }, "billingType": { "allOf": [ { "$ref": "#/components/schemas/ClaimBillingTypeApiSchema" } ] }, "billingCadence": { "allOf": [ { "$ref": "#/components/schemas/BillingCadenceApiSchema" } ] }, "membershipProgram": { "type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$" }, "amountMin": { "type": "integer", "minimum": 0 }, "amountMax": { "type": "integer", "minimum": 0 }, "maxAmount": { "type": "integer", "exclusiveMinimum": 0 }, "reason": { "type": "string", "maxLength": 500 }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } } }, "CreatePreAuthorizationRequestSchema": { "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/UserIdSchema" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/OrganizationIdSchema" } ], "description": "Organization ID - required for support admin, optional for org admins" }, "merchantCategoryCode": { "type": "string", "pattern": "^\\d{3,4}$" }, "merchantDescriptor": { "type": "string", "minLength": 1 }, "category": { "$ref": "#/components/schemas/ActiveServiceCategorySchema" }, "modality": { "allOf": [ { "$ref": "#/components/schemas/ClaimModalityApiSchema" } ] }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "expiresAt": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 500 }, "approveNow": { "type": "boolean" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } }, "required": [ "userId", "category", "amount" ] }, "CreatePreAuthorizationResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "preAuthorizationId": { "type": "string" }, "preAuthorization": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationSchema" } ] }, "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "required": [ "success" ] }, "CreateProcedureRequestSchema": { "type": "object", "properties": { "procedure": { "type": "string", "minLength": 2, "maxLength": 160 }, "referralStatus": { "$ref": "#/components/schemas/ProcedureSupportingMaterialStatusSchema" }, "imagingStatus": { "$ref": "#/components/schemas/ProcedureSupportingMaterialStatusSchema" }, "timingFlexibility": { "$ref": "#/components/schemas/ProcedureTimingFlexibilitySchema" }, "notes": { "type": "string", "maxLength": 2000 }, "zipCode": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Existing member ZIP context for the operations search" } }, "required": [ "procedure", "referralStatus", "imagingStatus", "timingFlexibility" ] }, "CreateReimbursementClaimRequestSchema": { "type": "object", "properties": { "serviceCategory": { "$ref": "#/components/schemas/ActiveServiceCategorySchema" }, "modality": { "type": "string", "enum": [ "IN_PERSON", "VIRTUAL" ], "description": "How care was delivered; defaults to IN_PERSON" }, "submittedAmount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "serviceDate": { "type": "string", "format": "date-time", "description": "Date the service was provided" }, "merchantName": { "type": "string", "description": "Name of the merchant/provider" }, "description": { "type": "string", "description": "Description of the service" }, "receiptKey": { "type": "string", "description": "R2 file key for the receipt" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ], "description": "Public API metadata as string key-value pairs" } }, "required": [ "serviceCategory", "submittedAmount", "serviceDate" ] }, "CreateReimbursementClaimResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "claimId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ] }, "CreateReimbursementClaimSchema": { "type": "object", "properties": { "serviceCategory": { "$ref": "#/components/schemas/ClaimIntakeServiceCategorySchema" }, "modality": { "type": "string" }, "submittedAmount": { "type": "integer", "exclusiveMinimum": 0 }, "serviceDate": { "type": "string", "format": "date-time" }, "merchantName": { "type": "string" }, "description": { "type": "string" }, "receiptKey": { "type": "string" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } }, "required": [ "serviceCategory", "submittedAmount", "serviceDate" ] }, "CreateTransactionSchema": { "type": "object", "properties": { "externalId": { "type": "string" }, "cardId": { "type": "string" }, "status": { "type": "string" }, "authorizedAmount": { "type": "integer", "minimum": 0 }, "settledAmount": { "type": "integer" }, "reversedAmount": { "type": "integer" }, "incrementedAmount": { "type": "integer" }, "fuelConfirmedAmount": { "type": "integer" }, "refundAuthorizedAmount": { "type": "integer" }, "refundedAmount": { "type": "integer" }, "merchantName": { "type": "string" }, "merchantCategoryCode": { "type": "string" }, "merchantCity": { "type": "string" }, "merchantState": { "type": "string" }, "merchantCountry": { "type": "string" } }, "required": [ "externalId", "cardId", "authorizedAmount" ] }, "CurrentPlanDesignKeySchema": { "type": "string", "enum": [ "rivendell-one-2026-r7" ] }, "cursorSchema": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time" }, "i": { "type": "string" } }, "required": [ "t", "i" ] }, "DecisionSchema": { "type": "string", "enum": [ "approve", "decline" ] }, "DeleteMerchantRuleResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "DeleteResponseSchema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ], "description": "Personal email deletion result" }, "DependentActivationStatusSchema": { "type": "string", "enum": [ "not_invited", "invited", "missing_email", "activated" ], "description": "Activation status for the dependent account" }, "DependentIdSchema": { "type": "string", "pattern": "^dependent_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DependentInviteParamsSchema": { "type": "object", "properties": { "dependentId": { "allOf": [ { "$ref": "#/components/schemas/DependentIdSchema" } ], "description": "Dependent census entry ID" } }, "required": [ "dependentId" ], "description": "Path parameters for dependent invite endpoints" }, "DependentInviteResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "description": "Dependent invite response payload" }, "DependentParamsSchema": { "type": "object", "properties": { "dependentId": { "allOf": [ { "$ref": "#/components/schemas/DependentIdSchema" } ], "description": "Dependent census entry ID" } }, "required": [ "dependentId" ], "description": "Path parameters for dependent census endpoints" }, "DependentSchema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "dob": { "type": [ "string", "null" ], "format": "date-time", "description": "Dependent date of birth" } }, "required": [ "name", "email", "dob" ] }, "DigitalWalletSchema": { "type": [ "object", "null" ], "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "digital_card_profile_id": { "type": [ "string", "null" ] } }, "required": [ "email", "phone", "digital_card_profile_id" ] }, "dispatchableAccumulatorPolicySchema": { "type": "object", "properties": { "deductible": { "type": "object", "properties": { "familyStructure": { "type": "string", "enum": [ "aggregate" ] }, "individualCents": { "type": "integer", "enum": [ 170000 ] }, "familyCents": { "type": "integer", "enum": [ 340000 ] } }, "required": [ "familyStructure", "individualCents", "familyCents" ], "additionalProperties": false }, "oop": { "type": "object", "properties": { "familyStructure": { "type": "string", "enum": [ "embedded" ] }, "individualCents": { "type": "integer", "enum": [ 500000 ] }, "familyCents": { "type": "integer", "enum": [ 1000000 ] } }, "required": [ "familyStructure", "individualCents", "familyCents" ], "additionalProperties": false } }, "required": [ "deductible", "oop" ], "additionalProperties": false }, "dispatchableCategoriesSchema": { "type": "object", "properties": { "virtualCare": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "zero_dollar" ] } }, "required": [ "mode" ], "additionalProperties": false }, "preventive": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "zero_dollar" ] } }, "required": [ "mode" ], "additionalProperties": false }, "inPersonPrimaryCare": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "inPersonUrgentCare": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "mentalHealthInPerson": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "labWork": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "specialist": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "generalMedical": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "maternity": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "dental": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "vision": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "deductible_then_coinsurance" ] } }, "required": [ "mode" ], "additionalProperties": false }, "lifestylePerk": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "payroll_excluded" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "virtualCare", "preventive", "inPersonPrimaryCare", "inPersonUrgentCare", "mentalHealthInPerson", "labWork", "specialist", "generalMedical", "maternity", "dental", "vision", "lifestylePerk" ], "additionalProperties": false }, "dispatchableCategoryMapSchema": { "type": "object", "properties": { "medical": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/categoryMapEntrySchema" }, "propertyNames": { "type": "string" } }, "pharmacy": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "chronicPreventive", "generic", "brand", "specialty", "glp1" ] }, "propertyNames": { "type": "string" } } }, "required": [ "medical", "pharmacy" ], "additionalProperties": false }, "DoctorAppointmentAttemptIdSchema": { "type": "string", "pattern": "^doctor_appointment_attempt_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorAppointmentJobIdSchema": { "type": "string", "pattern": "^doctor_appointment_job_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorAppointmentRequestIdSchema": { "type": "string", "pattern": "^doctor_appointment_request_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorAppointmentSelectionIdSchema": { "type": "string", "pattern": "^doctor_appointment_selection_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorBookingCallIdSchema": { "type": "string", "pattern": "^doctor_booking_call_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorIdSchema": { "type": "string", "pattern": "^doctor_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorIntakeCallIdSchema": { "type": "string", "pattern": "^doctor_intake_call_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorPriceReferenceIdSchema": { "type": "string", "pattern": "^doctor_price_reference_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorResultSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal doctor ID used for scheduling" }, "name": { "type": "string" }, "specialtyDisplay": { "type": "string" }, "starRating": { "type": [ "number", "null" ] }, "totalRatings": { "type": [ "number", "null" ] }, "address": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] }, "popularVisitReasons": { "type": "array", "items": { "type": "string" } }, "reviewKeywords": { "type": "array", "items": { "type": "string" } }, "reviewSummary": { "type": [ "string", "null" ] }, "reviewAttributes": { "type": "array", "items": { "type": "string" } }, "reviewSummaryStatus": { "type": "string", "enum": [ "ready", "pending", "empty", "failed" ] }, "copayAmount": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "nullable": true } }, "required": [ "id", "name", "specialtyDisplay", "starRating", "totalRatings", "address", "websiteUrl", "imageUrl", "phoneNumber", "popularVisitReasons", "reviewKeywords", "reviewSummary", "reviewAttributes", "reviewSummaryStatus" ] }, "DoctorReviewInsightIdSchema": { "type": "string", "pattern": "^doctor_review_insight_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "DoctorSelectionSchema": { "type": "object", "properties": { "doctorId": { "type": "string" }, "visitedStatus": { "type": "string", "enum": [ "yes", "no", "maybe" ] } }, "required": [ "doctorId", "visitedStatus" ] }, "DoctorSuggestQuerySchema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Doctor name query for autocomplete" }, "limit": { "description": "Maximum number of results to return", "type": "integer", "minimum": 1, "maximum": 20 }, "city": { "type": "string", "minLength": 1, "description": "City for location bias" }, "region": { "type": "string", "minLength": 1, "description": "State or region code for location bias" }, "postalCode": { "type": "string", "minLength": 1, "description": "Postal or ZIP code for location bias" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code" } }, "required": [ "q" ] }, "DoctorSuggestResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DoctorSuggestResultSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "DoctorSuggestResultSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal doctor ID used for scheduling" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "address", "phoneNumber", "websiteUrl", "imageUrl" ] }, "ElectionsSchema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "direct", "brokered" ], "default": "brokered" }, "foundingCohort": { "type": "boolean", "default": false }, "seedPercent": { "type": "integer", "enum": [ 0, 100 ], "default": 100 }, "addOns": { "type": "object", "properties": { "dentalVision": { "type": "boolean", "default": false }, "carrot": { "type": "boolean", "default": false }, "wellnessPack": { "type": "boolean", "default": false }, "lifestylePerk": { "type": "boolean", "default": false } }, "required": [ "dentalVision", "carrot", "wellnessPack", "lifestylePerk" ] } }, "required": [ "channel", "foundingCohort", "seedPercent", "addOns" ] }, "EmptyInputSchema": { "type": "object", "properties": {} }, "EndClinicalGateRequestSchema": { "type": "object", "properties": { "enrollmentId": { "$ref": "#/components/schemas/EnrollmentIdSchema" }, "organizationId": { "$ref": "#/components/schemas/OrganizationIdSchema" } }, "required": [ "enrollmentId", "organizationId" ] }, "EndClinicalGateResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "clinicalGateRecordId": { "$ref": "#/components/schemas/ClinicalGateRecordIdSchema" }, "effectiveUntil": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" } }, "required": [ "success", "clinicalGateRecordId", "effectiveUntil", "endedAt" ] }, "EnrollmentIdSchema": { "type": "string", "pattern": "^enrollment_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "EnrollmentTierSchema": { "type": "string", "enum": [ "EMPLOYEE_ONLY", "EMPLOYEE_SPOUSE", "EMPLOYEE_CHILD", "EMPLOYEE_FAMILY" ], "description": "Employee enrollment tier for health plan coverage" }, "extractionMetadataSchema": { "type": "object", "properties": { "panelName": { "type": "string" }, "panelCode": { "type": "string" }, "collectedAt": { "allOf": [ { "$ref": "#/components/schemas/parseableDateStringSchema" } ] }, "reportedAt": { "allOf": [ { "$ref": "#/components/schemas/parseableDateStringSchema" } ] }, "labProvider": { "type": "string" }, "patientName": { "type": "string" }, "notes": { "type": "string" } }, "additionalProperties": false }, "ExtractLabRequestSchema": { "type": "object", "properties": { "fileKey": { "type": "string", "minLength": 1, "pattern": "^lab-results\\/[a-zA-Z0-9-]+\\/\\d+-[a-zA-Z0-9-_.]+$", "description": "File key returned from /api/upload/initiate. Must start with lab-results/{userId}/" }, "testType": { "allOf": [ { "$ref": "#/components/schemas/TestTypeSchema" } ], "description": "Type of lab test (e.g., BLOOD_PANEL, LIPID_PANEL)" } }, "required": [ "fileKey", "testType" ], "description": "Request body for extracting lab results from an uploaded file" }, "ExtractLabResponseSchema": { "allOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "labTestId": { "type": "string", "description": "ID of the created lab test record" }, "testType": { "allOf": [ { "$ref": "#/components/schemas/TestTypeSchema" } ], "description": "Type of lab test (e.g., BLOOD_PANEL)" }, "labProvider": { "type": [ "string", "null" ], "description": "Lab provider name when available" }, "testDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the lab test was taken" }, "pdfPath": { "type": "string", "description": "URL of the lab result file in R2" }, "fileKey": { "type": "string", "description": "R2 file key for the lab result file" }, "extractedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when extraction completed (null if still processing)" }, "metadata": { "description": "Additional metadata from the extraction process", "nullable": true } }, "required": [ "success", "labTestId", "testType", "labProvider", "testDate", "pdfPath", "extractedAt", "metadata" ] }, { "$ref": "#/components/schemas/IngestionStatusSchema" } ], "description": "Response from lab extraction endpoint" }, "extractorModelResponseSchema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/extractionMetadataSchema" }, "biomarkers": { "type": "array", "items": { "$ref": "#/components/schemas/biomarkerObservationSchema" }, "minItems": 1 }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "metadata", "biomarkers" ], "additionalProperties": false }, "FindCareOptionsInputSchema": { "type": "object", "properties": { "location": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1 }, "region": { "type": "string", "minLength": 1 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "default": "US" }, "postalCode": { "type": "string", "minLength": 1 } }, "required": [ "city", "region", "countryCode", "postalCode" ] }, "specialty": { "type": "string", "minLength": 1 }, "careType": { "type": "string", "minLength": 1 }, "symptoms": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "urgency": { "type": "string", "enum": [ "routine", "soon", "immediate" ], "default": "soon" }, "visitType": { "type": "string", "enum": [ "virtual", "inperson", "any" ], "default": "inperson" }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } }, "required": [ "location", "specialty", "symptoms", "urgency", "visitType", "maxResults" ] }, "FindDoctorsRequestSchema": { "type": "object", "properties": { "location": { "$ref": "#/components/schemas/AddressSchema" }, "specialty": { "type": "string", "description": "Doctor field or specialty (e.g., 'dentist', 'cardiologist')" }, "careType": { "type": "string", "description": "Type of care or consultation (e.g., 'skin problem', 'hair loss')" }, "symptoms": { "type": "array", "items": { "type": "string" }, "description": "List of patient symptoms (e.g., ['acne', 'tooth pain'])" }, "urgency": { "type": "string", "enum": [ "routine", "soon", "immediate" ], "description": "Level of urgency" }, "visitType": { "type": "string", "enum": [ "virtual", "inperson", "any" ], "description": "Preferred visit type" }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Maximum number of results to return" } }, "required": [ "location", "specialty", "urgency", "visitType", "maxResults" ] }, "FindDoctorsResponseSchema": { "type": "array", "items": { "$ref": "#/components/schemas/DoctorResultSchema" } }, "FindHealthPlanInputSchema": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "all", "instructions", "data" ], "default": "all", "description": "Which portion of the skill to return. 'instructions' returns the agent runtime directives (SKILL.md). 'data' returns the embedded market knowledge (DATA.md). 'all' returns both, which is the recommended starting payload." } }, "required": [ "section" ] }, "FundingAttestationInputSchema": { "type": "object", "properties": { "spouseGeneralPurposeFsa": { "type": "boolean", "description": "Spouse has a general-purpose FSA" }, "medicare": { "type": "boolean", "description": "Enrolled in Medicare" }, "tricareOrOtherCoverage": { "type": "boolean", "description": "TRICARE or other disqualifying coverage" }, "automaticClaimPayments": { "type": "boolean", "description": "Explicit onboarding choice. Omission preserves ASK_EVERY_TIME without creating an authorization." }, "claimPaymentConsentAccepted": { "type": "boolean", "enum": [ true ] }, "claimPaymentTermsVersion": { "type": "string" } }, "required": [ "spouseGeneralPurposeFsa", "medicare", "tricareOrOtherCoverage" ] }, "FundingAttestationResponseSchema": { "type": "object", "properties": { "accountType": { "type": [ "string", "null" ], "enum": [ "HSA", "HRA", null ] }, "status": { "type": "string", "enum": [ "eligibility_required", "not_applicable", "hsa_opening_pending", "hsa_contribution_pending", "hsa_active", "hra_review_pending", "hra_active" ] }, "attestedAt": { "type": [ "string", "null" ] }, "claimPaymentMode": { "type": "string", "enum": [ "ASK_EVERY_TIME", "AUTO_WITH_REVIEW_WINDOW" ] }, "claimPaymentExecutionEnabled": { "type": "boolean" }, "claimPaymentReviewWindowMinutes": { "type": "integer" }, "claimPaymentTermsVersion": { "type": "string" }, "claimPaymentConsentText": { "type": "string" } }, "required": [ "accountType", "status", "attestedAt", "claimPaymentMode", "claimPaymentExecutionEnabled", "claimPaymentReviewWindowMinutes", "claimPaymentTermsVersion", "claimPaymentConsentText" ] }, "FundingTransactionsQuerySchema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor for pagination" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } } }, "FundingTransactionsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberFundingTransactionSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] }, "accountType": { "type": "string", "enum": [ "HSA", "HRA" ] }, "asOf": { "type": "string", "format": "date-time" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url", "next_cursor", "accountType", "asOf", "hasMore", "nextCursor" ] }, "FundTransferIdSchema": { "type": "string", "pattern": "^fund_transfer_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "GetClaimDetailsInputSchema": { "type": "object", "properties": { "claimId": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Rivendell claim ID" } }, "required": [ "claimId" ] }, "GetDependentsInputSchema": { "type": "object", "properties": { "onlyAdults": { "type": "boolean", "default": false } }, "required": [ "onlyAdults" ] }, "HealthDataPointSchema": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {}, "propertyNames": {} } }, "required": [ "date", "data" ] }, "HealthPlanIdSchema": { "type": "string", "pattern": "^health_plan_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "HealthSnapshotSchema": { "type": "object", "properties": { "workouts": { "type": "array", "items": { "$ref": "#/components/schemas/HealthDataPointSchema" } }, "exerciseTime": { "type": "array", "items": { "$ref": "#/components/schemas/HealthDataPointSchema" } }, "standTime": { "type": "array", "items": { "$ref": "#/components/schemas/HealthDataPointSchema" } }, "vo2Max": { "type": "array", "items": { "$ref": "#/components/schemas/HealthDataPointSchema" } }, "sleep": { "type": "array", "items": { "$ref": "#/components/schemas/HealthDataPointSchema" } } }, "required": [ "workouts", "exerciseTime", "standTime", "vo2Max", "sleep" ] }, "HsaCardResponseSchema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/CardSchema" } }, "required": [ "card" ], "description": "The member's HSA-backed card" }, "HsaMemberFundingTransactionSchema": { "type": "object", "properties": { "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "EMPLOYER_CONTRIBUTION", "MEMBER_CONTRIBUTION", "CARD_PAYMENT", "CLAIM_PAYMENT", "REIMBURSEMENT", "INTEREST", "CASHBACK", "FEE", "ADJUSTMENT", "REVERSAL" ] }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "description": { "type": "string" }, "claimId": { "type": [ "string", "null" ] }, "cardActivityId": { "type": [ "string", "null" ] }, "runningBalance": { "type": "integer" } }, "required": [ "id", "occurredAt", "postedAt", "kind", "amount", "currency", "description", "claimId", "cardActivityId", "runningBalance" ] }, "HsaSeedBillingLineIdSchema": { "type": "string", "pattern": "^hsa_seed_billing_line_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "hsaSeedSchema": { "type": "object", "properties": { "individualAnnualCents": { "$ref": "#/components/schemas/centsSchema" }, "familyAnnualCents": { "$ref": "#/components/schemas/centsSchema" }, "individualQuarterlyCents": { "$ref": "#/components/schemas/centsSchema" }, "familyQuarterlyCents": { "$ref": "#/components/schemas/centsSchema" }, "individualMonthlyDisplayCents": { "$ref": "#/components/schemas/centsSchema" }, "familyMonthlyDisplayCents": { "$ref": "#/components/schemas/centsSchema" } }, "required": [ "individualAnnualCents", "familyAnnualCents", "individualQuarterlyCents", "familyQuarterlyCents", "individualMonthlyDisplayCents", "familyMonthlyDisplayCents" ], "additionalProperties": false }, "HsaTransactionsQuerySchema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor for pagination" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } } }, "HsaTransactionsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HsaMemberFundingTransactionSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] }, "accountType": { "type": "string", "enum": [ "HSA", "HRA" ] }, "asOf": { "type": "string", "format": "date-time" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url", "next_cursor", "accountType", "asOf", "hasMore", "nextCursor" ] }, "IdempotencyKeyIdSchema": { "type": "string", "pattern": "^idempotency_key_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "IncreaseAccountIdSchema": { "type": "string", "pattern": "^account_[a-z0-9]{1,64}$" }, "IncreaseCardIdParamsSchema": { "type": "object", "properties": { "cardId": { "allOf": [ { "$ref": "#/components/schemas/IncreaseCardIdSchema" } ], "description": "Increase card identifier" } }, "required": [ "cardId" ], "description": "Path parameters for Increase card endpoints" }, "IncreaseCardIdSchema": { "type": "string", "pattern": "^card_[a-z0-9]{1,64}$" }, "IncreaseWebhookEventSchema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string" }, "category": { "type": "string" }, "associated_object_type": { "type": "string" }, "associated_object_id": { "type": "string" } }, "required": [ "id", "type", "created_at", "category", "associated_object_type", "associated_object_id" ] }, "IngestionStatusSchema": { "type": "object", "discriminator": { "propertyName": "status" }, "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed" ] }, "analyzerVersion": { "type": "string", "description": "Version of the AI analyzer used" }, "needsReviewCount": { "type": "number", "description": "Number of results that need manual review" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Any warnings during processing" }, "processedAt": { "type": "string", "format": "date-time", "description": "Timestamp of processing completion" } }, "required": [ "status", "analyzerVersion", "needsReviewCount", "warnings", "processedAt" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing_failed" ] }, "reason": { "type": "string", "description": "Reason for processing failure" } }, "required": [ "status", "reason" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing" ] } }, "required": [ "status" ] } ] }, "InitiateUploadRequestSchema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Original filename including extension" }, "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the file to be uploaded" }, "purpose": { "allOf": [ { "$ref": "#/components/schemas/UploadPurposeSchema" } ], "description": "Upload purpose" }, "fileSize": { "type": "number", "exclusiveMinimum": 0, "description": "File size in bytes (max 15MB)" }, "ownerUserId": { "type": "string", "minLength": 1, "description": "Optional member owner for support uploads. Only valid for member-invoices." } }, "required": [ "fileName", "contentType", "purpose", "fileSize" ], "description": "Request body for initiating a direct R2 upload" }, "InitiateUploadResponseSchema": { "type": "object", "properties": { "uploadUrl": { "type": "string", "format": "uri", "description": "Pre-signed URL for uploading the file directly to R2" }, "fileKey": { "type": "string", "description": "File key/path in R2" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "Visibility classification for the uploaded object" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the pre-signed URL expires" }, "metadata": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Sanitized filename" }, "contentType": { "type": "string", "description": "MIME type of the file" }, "fileSize": { "type": "number", "description": "File size in bytes" }, "purpose": { "$ref": "#/components/schemas/UploadPurposeSchema" }, "userId": { "type": "string", "description": "ID of the file owner path used for the upload" } }, "required": [ "fileName", "contentType", "fileSize", "purpose", "userId" ] } }, "required": [ "uploadUrl", "fileKey", "visibility", "expiresAt", "metadata" ], "description": "Successful upload initiation response" }, "InvitationIdSchema": { "type": "string", "pattern": "^invitation_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "InvoicePreviewExtractedSchema": { "type": "object", "properties": { "submittedAmount": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "serviceDate": { "type": [ "string", "null" ], "format": "date-time" }, "merchantName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "serviceCategory": { "allOf": [ { "$ref": "#/components/schemas/ActiveServiceCategorySchema" } ], "nullable": true } }, "required": [ "submittedAmount", "currency", "serviceDate", "merchantName", "description", "serviceCategory" ] }, "InvoicePreviewFieldReviewSchema": { "type": "object", "properties": { "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "sourcePage": { "type": "integer", "exclusiveMinimum": 0 }, "sourceText": { "type": "string" } }, "required": [ "confidence", "sourcePage", "sourceText" ] }, "InvoicePreviewRequestSchema": { "type": "object", "properties": { "fileKey": { "type": "string", "minLength": 1, "description": "R2 file key for the uploaded invoice (claim-invoices/{userId}/...)" } }, "required": [ "fileKey" ] }, "InvoicePreviewResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "extracted": { "$ref": "#/components/schemas/InvoicePreviewExtractedSchema" }, "review": { "type": "object", "properties": { "readiness": { "type": "string", "enum": [ "READY", "NEEDS_REVIEW" ] }, "fields": { "type": "object", "properties": { "submittedAmount": { "allOf": [ { "$ref": "#/components/schemas/InvoicePreviewFieldReviewSchema" } ] }, "currency": { "allOf": [ { "$ref": "#/components/schemas/InvoicePreviewFieldReviewSchema" } ] }, "serviceDate": { "allOf": [ { "$ref": "#/components/schemas/InvoicePreviewFieldReviewSchema" } ] }, "merchantName": { "allOf": [ { "$ref": "#/components/schemas/InvoicePreviewFieldReviewSchema" } ] }, "description": { "allOf": [ { "$ref": "#/components/schemas/InvoicePreviewFieldReviewSchema" } ] }, "serviceCategory": { "allOf": [ { "$ref": "#/components/schemas/InvoicePreviewFieldReviewSchema" } ] } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/InvoiceWarningCodeSchema" }, "field": { "type": "string", "enum": [ "submittedAmount", "currency", "serviceDate", "merchantName", "description", "serviceCategory" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } }, "required": [ "readiness", "fields", "warnings" ] } }, "required": [ "success", "extracted" ] }, "InvoiceWarningCodeSchema": { "type": "string", "enum": [ "MISSING_REQUIRED_FIELD", "LOW_CONFIDENCE", "SOURCE_NOT_FOUND", "AMOUNT_AMBIGUOUS", "DATE_AMBIGUOUS", "UNSUPPORTED_CURRENCY", "CATEGORY_UNCERTAIN" ] }, "LabTestIdSchema": { "type": "string", "pattern": "^lab_test_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "LegalAcceptanceDocumentStatusSchema": { "type": "object", "properties": { "documentType": { "$ref": "#/components/schemas/LegalDocumentTypeSchema" }, "documentVersion": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "url": { "type": "string" }, "contentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "needsAcceptance": { "type": "boolean" } }, "required": [ "documentType", "documentVersion", "effectiveDate", "url", "contentHash", "acceptedAt", "needsAcceptance" ] }, "LegalAcceptanceSchema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/LegalDocumentAcceptanceIdSchema" }, "subjectUserId": { "$ref": "#/components/schemas/UserIdSchema" }, "acceptedByUserId": { "$ref": "#/components/schemas/UserIdSchema" }, "documentType": { "$ref": "#/components/schemas/LegalDocumentTypeSchema" }, "documentVersion": { "type": "string" }, "documentUrl": { "type": "string" }, "documentContentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "acceptanceCapacity": { "type": "string", "enum": [ "self", "guardian_for_minor" ] }, "guardianRelationship": { "type": [ "string", "null" ], "enum": [ "child", null ] }, "subjectWasMinorAtAcceptance": { "type": [ "boolean", "null" ] }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/OrganizationIdSchema" } ], "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time" }, "platform": { "$ref": "#/components/schemas/LegalPlatformSchema" }, "appVersion": { "type": [ "string", "null" ] }, "appBuild": { "type": [ "string", "null" ] } }, "required": [ "id", "subjectUserId", "acceptedByUserId", "documentType", "documentVersion", "documentUrl", "documentContentHash", "acceptanceCapacity", "guardianRelationship", "subjectWasMinorAtAcceptance", "organizationId", "acceptedAt", "platform", "appVersion", "appBuild" ] }, "LegalAcceptanceStatusResponseSchema": { "type": "object", "properties": { "subjects": { "type": "array", "items": { "$ref": "#/components/schemas/LegalAcceptanceSubjectStatusSchema" } } }, "required": [ "subjects" ] }, "LegalAcceptanceSubjectStatusSchema": { "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/UserIdSchema" }, "name": { "type": "string" }, "relationship": { "type": "string", "enum": [ "self", "guardian_for_minor" ] }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/LegalAcceptanceDocumentStatusSchema" } } }, "required": [ "userId", "name", "relationship", "documents" ] }, "LegalClientContextSchema": { "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/LegalPlatformSchema" }, "appVersion": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] }, "appBuild": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100 } ] } }, "required": [ "platform" ] }, "LegalDocumentAcceptanceIdSchema": { "type": "string", "pattern": "^legal_document_acceptance_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "LegalDocumentSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "terms", "privacy" ] }, "version": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "url": { "type": "string" }, "contentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } }, "required": [ "type", "version", "effectiveDate", "url", "contentHash" ] }, "LegalDocumentsResponseSchema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/LegalDocumentSchema" } } }, "required": [ "documents" ] }, "LegalDocumentTypeSchema": { "type": "string", "enum": [ "terms", "privacy" ] }, "LegalPlatformSchema": { "type": "string", "enum": [ "ios", "android", "web", "other" ] }, "LinkBankAccountRequestSchema": { "type": "object", "properties": { "ownerType": { "type": "string", "enum": [ "USER", "ORGANIZATION" ] }, "financialConnectionsSessionId": { "type": "string", "minLength": 1 }, "financialConnectionsAccountId": { "type": "string", "minLength": 1 }, "consentAccepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "ownerType", "financialConnectionsSessionId", "financialConnectionsAccountId", "consentAccepted" ] }, "LinkBankAccountResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "bankAccountId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ] }, "LinkRequestSchema": { "type": "object", "properties": { "callbackURL": { "type": "string", "format": "uri", "description": "URL to redirect to after Google OAuth completes (e.g. rivendell://...)" }, "errorCallbackURL": { "type": "string", "format": "uri", "description": "URL to redirect to if linking fails, with ?error= appended. When omitted, Better Auth uses the Rivendell web error page." } }, "required": [ "callbackURL" ], "description": "Request to initiate secondary Google account linking" }, "LinkResponseSchema": { "type": "object", "properties": { "url": { "type": "string", "description": "Google OAuth authorization URL to open" }, "redirect": { "type": "boolean" } }, "required": [ "url", "redirect" ], "description": "Google OAuth link initiation result" }, "ListAppointmentsInputSchema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "upcoming", "past", "all" ], "default": "upcoming" } }, "required": [ "scope" ] }, "ListBankAccountsQuerySchema": { "type": "object", "properties": {} }, "ListCardsQueryParamsSchema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "CANCELED" ], "description": "Filter cards by status (ACTIVE, DISABLED, CANCELED)" } } }, "ListCardsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CardSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ], "description": "List of cards for the authenticated user" }, "ListClaimsInputSchema": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "type": "string", "enum": [ "DRAFT", "PENDING_SUBSTANTIATION", "SUBMITTED", "IN_REVIEW", "APPROVED", "REJECTED", "PAID" ] } }, "source": { "type": "string", "enum": [ "CARD_TRANSACTION", "REIMBURSEMENT" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "offset": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "statuses", "limit", "offset" ] }, "ListClaimsNeedingInvoicesInputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "offset": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "limit", "offset" ] }, "MajorCareItemSchema": { "type": "object", "properties": { "doctorId": { "type": "string", "minLength": 1, "description": "Linked doctor ID when selected" }, "description": { "type": "string", "minLength": 1, "description": "User-described procedure or condition" }, "type": { "allOf": [ { "$ref": "#/components/schemas/MajorCareTypeSchema" } ], "description": "Whether the item is a procedure or condition" }, "timeframe": { "allOf": [ { "$ref": "#/components/schemas/MajorCareTimeframeSchema" } ], "description": "Rough timeframe for when the care occurred" }, "facility": { "type": [ "string", "null" ], "minLength": 1, "description": "Facility or hospital name if known" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence between 0 and 1" }, "missingFields": { "type": "array", "items": { "type": "string", "enum": [ "facility", "timeframe", "description", "type" ] }, "description": "Fields that require follow-up before confirmation" } }, "required": [ "description", "type", "timeframe", "facility" ] }, "MajorCareTimeframeSchema": { "type": "string", "enum": [ "PAST_3_MONTHS", "PAST_6_MONTHS", "PAST_YEAR", "PAST_2_YEARS", "MORE_THAN_2_YEARS", "UNKNOWN" ] }, "MajorCareTypeSchema": { "type": "string", "enum": [ "PROCEDURE", "CONDITION", "UNKNOWN" ] }, "MandateLogIdSchema": { "type": "string", "pattern": "^mandate_log_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "ManualBankAccountCreateResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "bankAccountId": { "type": "string" }, "bankAccount": { "allOf": [ { "$ref": "#/components/schemas/BankAccountListItemSchema" } ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "ManualBankAccountCreateSchema": { "type": "object", "properties": { "ownerType": { "type": "string", "enum": [ "USER", "ORGANIZATION" ], "default": "USER" }, "bankName": { "type": "string", "minLength": 1 }, "routingNumber": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "minLength": 1 }, "funding": { "type": "string", "enum": [ "checking", "savings" ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } }, "required": [ "ownerType", "bankName", "routingNumber", "accountNumber" ] }, "ManualBankAccountNormalizedSchema": { "type": "object", "properties": { "ownerType": { "type": "string", "enum": [ "USER", "ORGANIZATION" ] }, "bankName": { "type": "string", "minLength": 1 }, "routingNumber": { "type": "string", "pattern": "^\\d{9}$" }, "accountNumber": { "type": "string", "pattern": "^\\d{4,17}$" }, "funding": { "type": "string", "enum": [ "checking", "savings" ] } }, "required": [ "ownerType", "bankName", "routingNumber", "accountNumber" ] }, "MedicalHistoryAccessibilityIdSchema": { "type": "string", "pattern": "^medical_history_accessibility_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MedicalHistoryConditionIdSchema": { "type": "string", "pattern": "^medical_history_condition_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MedicalHistoryExtractRequestSchema": { "type": "object", "properties": { "medicationsInput": { "type": "string", "description": "Freeform medication input from the member" }, "conditionsInput": { "type": "string", "description": "Freeform condition input from the member" }, "majorCareInput": { "type": "string", "description": "Freeform major care input from the member" }, "accessibilityInput": { "type": "string", "description": "Freeform accessibility input from the member" } } }, "MedicalHistoryExtractResponseSchema": { "type": "object", "properties": { "extractedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the extraction was performed" }, "medications": { "type": "object" }, "conditions": { "type": "object" }, "majorCare": { "type": "object" }, "accessibility": { "type": "object" } }, "required": [ "extractedAt", "medications", "conditions", "majorCare", "accessibility" ] }, "MedicalHistoryMajorCareIdSchema": { "type": "string", "pattern": "^medical_history_major_care_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MedicalHistoryMedicationIdSchema": { "type": "string", "pattern": "^medical_history_medication_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MedicalHistoryResponseSchema": { "type": "object", "properties": { "snapshot": { "allOf": [ { "$ref": "#/components/schemas/MedicalHistorySnapshotSchema" } ], "nullable": true } }, "required": [ "snapshot" ] }, "MedicalHistorySignalsSchema": { "type": "object", "properties": { "medications": { "type": "array", "items": { "$ref": "#/components/schemas/MedicationItemSchema" } }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionItemSchema" } }, "majorCare": { "type": "array", "items": { "$ref": "#/components/schemas/MajorCareItemSchema" } }, "accessibility": { "type": "array", "items": { "$ref": "#/components/schemas/AccessibilityNeedSchema" } } }, "required": [ "medications", "conditions", "majorCare", "accessibility" ] }, "MedicalHistorySnapshotIdSchema": { "type": "string", "pattern": "^medical_history_snapshot_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MedicalHistorySnapshotSchema": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "medicationsRaw": { "type": [ "string", "null" ] }, "conditionsRaw": { "type": [ "string", "null" ] }, "majorCareRaw": { "type": [ "string", "null" ] }, "accessibilityRaw": { "type": [ "string", "null" ] }, "medications": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MedicationItemSchema" } }, "conditions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ConditionItemSchema" } }, "majorCare": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MajorCareItemSchema" } }, "accessibility": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AccessibilityNeedSchema" } }, "extractedAt": { "type": [ "string", "null" ], "format": "date-time" }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "userId", "medicationsRaw", "conditionsRaw", "majorCareRaw", "accessibilityRaw", "medications", "conditions", "majorCare", "accessibility", "extractedAt", "confirmedAt", "createdAt", "updatedAt" ] }, "MedicalHistoryUpdateSchema": { "type": "object", "properties": { "medicationsRaw": { "type": [ "string", "null" ], "description": "Raw medication input for audit" }, "conditionsRaw": { "type": [ "string", "null" ], "description": "Raw condition input for audit" }, "majorCareRaw": { "type": [ "string", "null" ], "description": "Raw major care input for audit" }, "accessibilityRaw": { "type": [ "string", "null" ], "description": "Raw accessibility input for audit" }, "medications": { "type": "array", "items": { "$ref": "#/components/schemas/MedicationItemSchema" }, "description": "Confirmed medication signals" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionItemSchema" }, "description": "Confirmed condition signals" }, "majorCare": { "type": "array", "items": { "$ref": "#/components/schemas/ConfirmedMajorCareItemSchema" }, "description": "Confirmed major care signals" }, "accessibility": { "type": "array", "items": { "$ref": "#/components/schemas/AccessibilityNeedSchema" }, "description": "Confirmed accessibility needs" } } }, "MedicationCategorySchema": { "type": "string", "enum": [ "CARDIOVASCULAR", "RESPIRATORY", "METABOLIC", "ENDOCRINE", "MENTAL_HEALTH", "NEUROLOGIC", "PAIN", "AUTOIMMUNE", "ONCOLOGY", "INFECTIOUS", "GASTROINTESTINAL", "ALLERGY", "OTHER" ] }, "MedicationItemSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Medication name as provided by the user" }, "normalizedName": { "type": "string", "minLength": 1, "description": "Normalized medication name for internal use" }, "category": { "allOf": [ { "$ref": "#/components/schemas/MedicationCategorySchema" } ], "description": "Coarse bucket for routing/cost signals" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence between 0 and 1" } }, "required": [ "name" ] }, "MedicationSearchIdSchema": { "type": "string", "pattern": "^medication_search_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MedicationSearchQuerySchema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Search query for medication autocomplete" }, "limit": { "description": "Max number of results to return", "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "description": "Pagination offset", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "q" ] }, "MedicationSearchResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MedicationSearchResultSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "MedicationSearchResultSchema": { "type": "object", "properties": { "id": { "type": "string" }, "ndc": { "type": "string", "description": "National Drug Code (no hyphens)" }, "medicationName": { "type": "string" }, "brandName": { "type": [ "string", "null" ] }, "strength": { "type": "string" }, "form": { "type": [ "string", "null" ] }, "formattedPrice": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "object", "properties": { "cents": { "type": "integer" }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "cents", "currency" ] }, "source": { "type": "string", "enum": [ "cost_plus_drugs" ] }, "sourceLabel": { "type": "string" }, "asOf": { "type": "string", "format": "date-time" }, "url": { "type": [ "string", "null" ] } }, "required": [ "amount", "source", "sourceLabel", "asOf", "url" ], "description": "Source-labelled cash comparison, not an Amazon Pharmacy quote" } }, "required": [ "id", "ndc", "medicationName", "brandName", "strength", "form", "formattedPrice", "url", "displayName" ] }, "memberAddOnFactSchema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "monthlyCents": { "$ref": "#/components/schemas/centsSchema" } }, "required": [ "key", "title", "summary", "monthlyCents" ], "additionalProperties": false }, "memberBenefitFactSchema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 } }, "required": [ "key", "title", "summary" ], "additionalProperties": false }, "memberFaqFactSchema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "answer": { "type": "string", "minLength": 1 } }, "required": [ "question", "answer" ], "additionalProperties": false }, "MemberFundingSchema": { "type": [ "object", "null" ], "properties": { "fundingRole": { "type": "string", "enum": [ "primary_member", "covered_dependent" ], "description": "The authenticated person's funding relationship. Covered dependents must skip personal HSA/HRA attestation, account-opening, and ownership flows." }, "accountType": { "type": [ "string", "null" ], "enum": [ "HSA", "HRA", null ] }, "status": { "type": "string", "enum": [ "eligibility_required", "not_applicable", "hsa_opening_pending", "hsa_contribution_pending", "hsa_active", "hra_review_pending", "hra_active" ], "description": "Funding workflow status for the authenticated person." }, "plannedEmployerFunding": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Exact employer funding frozen on full-period billing lines. This may be zero before the first qualifying bill." }, "availableMemberMoney": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "nullable": true }, "netOwnCashMax": { "$ref": "#/components/schemas/AmountSchema" }, "planPaysAfter": { "$ref": "#/components/schemas/AmountSchema" }, "hsaAccount": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "PENDING", "OPEN", "RESTRICTED", "FAILED", "CLOSED" ] }, "balance": { "$ref": "#/components/schemas/AmountSchema" }, "availableBalance": { "$ref": "#/components/schemas/AmountSchema" }, "openedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "status", "balance", "availableBalance", "openedAt" ], "description": "The member's custodial HSA account, once one exists" }, "seed": { "type": [ "object", "null" ], "properties": { "due": { "$ref": "#/components/schemas/AmountSchema" }, "deposited": { "$ref": "#/components/schemas/AmountSchema" }, "outstanding": { "$ref": "#/components/schemas/AmountSchema" } }, "required": [ "due", "deposited", "outstanding" ], "description": "Employer HSA seed schedule: due to date vs deposited" }, "cadence": { "type": [ "string", "null" ], "enum": [ "annual", "quarterly", "monthly", "other", null ], "description": "Employer funding cadence for this member" }, "nextDepositDate": { "type": [ "string", "null" ], "format": "date", "description": "Date-only contractual due date; may be in the past when nextDepositStatus is late" }, "nextDepositAmount": { "description": "Outstanding amount expected in the next employer deposit", "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "nullable": true }, "nextDepositStatus": { "type": [ "string", "null" ], "enum": [ "scheduled", "processing", "late", null ], "description": "Whether the next contractual deposit date has passed" }, "remainingSchedule": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "period": { "type": "integer", "exclusiveMinimum": 0 }, "date": { "type": "string", "format": "date" }, "amount": { "$ref": "#/components/schemas/AmountSchema" }, "status": { "type": "string", "enum": [ "scheduled", "processing", "late" ] } }, "required": [ "period", "date", "amount", "status" ] }, "description": "Remaining installments in the first funding year" } }, "required": [ "fundingRole", "accountType", "status", "plannedEmployerFunding", "availableMemberMoney", "netOwnCashMax", "planPaysAfter", "hsaAccount", "seed" ] }, "MemberFundingTransactionSchema": { "type": "object", "properties": { "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "EMPLOYER_CONTRIBUTION", "MEMBER_CONTRIBUTION", "CARD_PAYMENT", "CLAIM_PAYMENT", "REIMBURSEMENT", "INTEREST", "CASHBACK", "FEE", "ADJUSTMENT", "REVERSAL" ] }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "description": { "type": "string" }, "claimId": { "type": [ "string", "null" ] }, "cardActivityId": { "type": [ "string", "null" ] }, "runningBalance": { "type": "integer" } }, "required": [ "id", "occurredAt", "postedAt", "kind", "amount", "currency", "description", "claimId", "cardActivityId", "runningBalance" ] }, "MemberIdSchema": { "type": "string", "pattern": "^member_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MemberInvoiceIdSchema": { "type": "string", "pattern": "^member_invoice_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MemberInvoiceLineItemIdSchema": { "type": "string", "pattern": "^member_invoice_line_item_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MemberMedicationIdSchema": { "type": "string", "pattern": "^member_medication_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MemberMedicationSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "member_medication" ] }, "id": { "$ref": "#/components/schemas/MemberMedicationIdSchema" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "updated_at": { "type": "integer" }, "ndc": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "strength": { "type": [ "string", "null" ] }, "form": { "type": [ "string", "null" ] }, "prescriberName": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MemberMedicationStatusSchema" }, "pharmacyPreference": { "$ref": "#/components/schemas/PharmacyPreferenceSchema" }, "addedAt": { "type": "string", "format": "date-time" }, "lastFilledAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "created", "livemode", "metadata", "updated_at", "ndc", "displayName", "strength", "form", "prescriberName", "status", "pharmacyPreference", "addedAt", "lastFilledAt", "createdAt", "updatedAt" ] }, "MemberMedicationsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberMedicationSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] }, "preferredPharmacy": { "$ref": "#/components/schemas/PreferredPharmacySchema" }, "serverTime": { "type": "string", "format": "date-time" } }, "required": [ "object", "data", "has_more", "url", "preferredPharmacy", "serverTime" ] }, "MemberMedicationStatusSchema": { "type": "string", "enum": [ "active", "archived" ] }, "MemberPreAuthorizationSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "pre_authorization" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^pre_authorization_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "status": { "$ref": "#/components/schemas/PreAuthorizationStatusSchema" }, "category": { "$ref": "#/components/schemas/ServiceCategoryReadSchema" }, "modality": { "allOf": [ { "$ref": "#/components/schemas/ClaimModalityApiSchema" } ], "nullable": true }, "amount": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "isUsed": { "type": "boolean" }, "usedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "isOpen": { "type": "boolean", "description": "True while this request can still be approved and used: PENDING, unexpired, unconsumed" } }, "required": [ "object", "id", "created", "livemode", "metadata", "status", "category", "modality", "amount", "description", "isUsed", "usedAt", "expiresAt", "reviewedAt", "createdAt", "updatedAt", "isOpen" ], "additionalProperties": true }, "MerchantRuleCreatorSchema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email" ] }, "MerchantRuleIdSchema": { "type": "string", "pattern": "^merchant_rule_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "MerchantRuleListResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantRuleSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] }, "MerchantRuleParamsSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/MerchantRuleIdSchema" } ], "description": "Merchant rule ID" } }, "required": [ "id" ], "description": "Path parameters for merchant rule admin actions" }, "MerchantRuleSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "merchant_rule" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^merchant_rule_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "merchant_pattern": { "type": [ "string", "null" ] }, "merchant_category_code": { "type": [ "string", "null" ] }, "service_category": { "type": [ "string", "null" ] }, "modality": { "allOf": [ { "$ref": "#/components/schemas/ClaimModalitySchema" } ], "nullable": true }, "billing_type": { "allOf": [ { "$ref": "#/components/schemas/ClaimBillingTypeApiSchema" } ], "nullable": true }, "billing_cadence": { "allOf": [ { "$ref": "#/components/schemas/BillingCadenceApiSchema" } ], "nullable": true }, "membership_program": { "type": [ "string", "null" ] }, "amount_min": { "type": [ "integer", "null" ] }, "amount_max": { "type": [ "integer", "null" ] }, "max_amount": { "type": [ "integer", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_by": { "type": "string" }, "updated_at": { "type": "integer" }, "merchantPattern": { "type": [ "string", "null" ] }, "merchantCategoryCode": { "type": [ "string", "null" ] }, "serviceCategory": { "type": [ "string", "null" ] }, "billingType": { "allOf": [ { "$ref": "#/components/schemas/ClaimBillingTypeApiSchema" } ], "nullable": true }, "billingCadence": { "allOf": [ { "$ref": "#/components/schemas/BillingCadenceApiSchema" } ], "nullable": true }, "membershipProgram": { "type": [ "string", "null" ] }, "amountMin": { "type": [ "integer", "null" ] }, "amountMax": { "type": [ "integer", "null" ] }, "maxAmount": { "type": [ "integer", "null" ] }, "organizationId": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "creator": { "$ref": "#/components/schemas/MerchantRuleCreatorSchema" } }, "required": [ "object", "id", "created", "livemode", "metadata", "merchant_pattern", "merchant_category_code", "service_category", "modality", "billing_type", "billing_cadence", "membership_program", "amount_min", "amount_max", "max_amount", "organization_id", "is_active", "created_by", "updated_at", "merchantPattern", "merchantCategoryCode", "serviceCategory", "billingType", "billingCadence", "membershipProgram", "amountMin", "amountMax", "maxAmount", "organizationId", "reason", "isActive", "createdBy", "createdAt", "updatedAt", "creator" ] }, "MobileConfigResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mobile_config" ] }, "minimumAppVersion": { "type": "string", "description": "Builds below this version must block usage and prompt an update" }, "recommendedAppVersion": { "type": "string", "description": "Builds below this version should show a dismissible prompt" }, "iosDownloadUrl": { "type": [ "string", "null" ], "description": "Where the update button sends iOS users" } }, "required": [ "object", "minimumAppVersion", "recommendedAppVersion", "iosDownloadUrl" ], "description": "Mobile app version gate configuration" }, "ModelAuditValueSchema": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "ModelCensusAuditIssueSchema": { "type": "object", "properties": { "rowIndex": { "type": "integer", "minimum": 0 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "rowIndex", "reason" ], "additionalProperties": false }, "ModelCensusChangeSchema": { "type": "object", "properties": { "rowIndex": { "type": "integer", "minimum": 0 }, "field": { "type": "string", "enum": [ "ref", "firstName", "lastName", "dob", "zip", "sex", "email", "phone", "enrollmentTier" ] }, "previousValue": { "type": [ "string", "null" ] }, "nextValue": { "type": [ "string", "null" ] }, "reason": { "type": "string", "enum": [ "trimmed", "normalized", "defaulted" ] } }, "required": [ "rowIndex", "field", "previousValue", "nextValue", "reason" ], "additionalProperties": false }, "ModelCensusCorrectionSchema": { "type": "object", "properties": { "census": { "$ref": "#/components/schemas/CensusExtractionSchema" }, "sourceEmployeeCount": { "type": "integer", "minimum": 0 }, "rawRows": { "type": "array", "items": { "$ref": "#/components/schemas/ModelRawRowSchema" } }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ModelCensusChangeSchema" } }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ModelCensusAuditIssueSchema" } }, "reconstructedZipRows": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "census", "sourceEmployeeCount", "rawRows", "changes", "issues", "reconstructedZipRows" ], "additionalProperties": false }, "ModelRawRowSchema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "value": { "$ref": "#/components/schemas/ModelAuditValueSchema" } }, "required": [ "name", "value" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "fields" ], "additionalProperties": false }, "MoneyBreakdownSchema": { "type": "object", "properties": { "insuranceSubtotalCents": { "type": "integer" }, "hsaSeedCents": { "type": "integer" }, "addOnsCents": { "type": "integer" }, "totalCents": { "type": "integer" } }, "required": [ "insuranceSubtotalCents", "hsaSeedCents", "addOnsCents", "totalCents" ] }, "NdcSchema": { "type": "string", "pattern": "^[0-9]{10,11}$", "description": "10 or 11 digit National Drug Code" }, "NormalizedCensusSchema": { "type": "object", "properties": { "companyName": { "type": [ "string", "null" ] }, "effectiveDate": { "type": "string", "format": "date" }, "employees": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "dob": { "type": [ "string", "null" ] }, "zip": { "type": "string" }, "sex": { "type": [ "string", "null" ], "enum": [ "M", "F", null ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "enrollmentTier": { "$ref": "#/components/schemas/EnrollmentTierSchema" } }, "required": [ "ref", "firstName", "lastName", "dob", "zip", "sex", "email", "phone", "enrollmentTier" ] } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "string" }, "missingFields": { "type": "array", "items": { "type": "string", "enum": [ "zip", "enrollmentTier", "effectiveDate" ] } }, "note": { "type": [ "string", "null" ] } }, "required": [ "row", "missingFields", "note" ] } } }, "required": [ "companyName", "effectiveDate", "employees", "issues" ] }, "NotificationLogIdSchema": { "type": "string", "pattern": "^notification_log_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "NotificationPreferenceIdSchema": { "type": "string", "pattern": "^notification_preference_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "nullableNumber": { "type": [ "number", "null" ] }, "nullableText": { "type": [ "string", "null" ], "minLength": 1 }, "OAuthAccessTokenIdSchema": { "type": "string", "pattern": "^oauth_access_token_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OAuthAuthorizationCodeIdSchema": { "type": "string", "pattern": "^oauth_authorization_code_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OAuthClientIdSchema": { "type": "string", "pattern": "^oauth_client_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OAuthDeviceCodeIdSchema": { "type": "string", "pattern": "^oauth_device_code_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OAuthRefreshTokenIdSchema": { "type": "string", "pattern": "^oauth_refresh_token_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OnboardingChecklistCanonicalItemSchema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/OnboardingChecklistKeySchema" }, "state": { "$ref": "#/components/schemas/OnboardingChecklistStateSchema" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "key", "state", "completed_at" ], "description": "One organization-scoped onboarding checklist item" }, "OnboardingChecklistItemSchema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/OnboardingChecklistKeySchema" }, "state": { "$ref": "#/components/schemas/OnboardingChecklistStateSchema" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "key", "state", "completedAt" ], "description": "One organization-scoped onboarding checklist item" }, "OnboardingChecklistKeySchema": { "type": "string", "enum": [ "STORY_COVERED", "STORY_MONEY", "STORY_NUMBERS", "STORY_ZERO_LANE", "STORY_RULES", "PROFILE_REVIEW", "ADDRESS", "PHONE_NUMBER", "HSA_ATTESTATION", "ACCOUNT_RESULT", "CARD_SETUP", "DEPENDENTS", "MEDS_AND_CONDITIONS", "MEDS_CONFIRM", "NOTIFICATIONS", "DONE" ] }, "OnboardingChecklistPatchItemSchema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/OnboardingChecklistKeySchema" }, "state": { "$ref": "#/components/schemas/OnboardingChecklistStateSchema" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "key", "state" ], "description": "One onboarding checklist item update" }, "OnboardingChecklistPatchSchema": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingChecklistPatchItemSchema" }, "minItems": 1, "maxItems": 16 }, "OnboardingChecklistStateSchema": { "type": "string", "enum": [ "not_started", "done", "skipped", "not_applicable" ] }, "OnboardingStepSchema": { "type": "string", "enum": [ "PROFILE", "DEPENDENTS", "MEDICAL_HISTORY", "COMPLETE" ], "description": "Current onboarding step for the user" }, "OrgAdvanceIdSchema": { "type": "string", "pattern": "^org_advance_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OrganizationContextSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique organization identifier" }, "name": { "type": "string", "description": "Organization display name" }, "slug": { "type": [ "string", "null" ], "description": "Organization slug" }, "logo": { "type": [ "string", "null" ], "description": "Organization logo URL" }, "addressLine1": { "type": [ "string", "null" ], "description": "Employer street address line 1" }, "addressLine2": { "type": [ "string", "null" ], "description": "Employer street address line 2" }, "city": { "type": [ "string", "null" ], "description": "Employer address city" }, "state": { "type": [ "string", "null" ], "description": "Employer address state" }, "postalCode": { "type": [ "string", "null" ], "description": "Employer address postal code" }, "country": { "type": [ "string", "null" ], "description": "Employer address country code" } }, "required": [ "id", "name", "slug", "logo" ], "description": "Organization context for the authenticated user" }, "OrganizationIdSchema": { "type": "string", "pattern": "^organization_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "OrgFundBalanceIdSchema": { "type": "string", "pattern": "^org_fund_balance_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "parseableDateStringSchema": { "type": "string" }, "PharmacyAddressSchema": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" } }, "required": [ "line1", "line2", "city", "region", "postalCode" ] }, "PharmacyCapabilitiesSchema": { "type": "object", "properties": { "firstFillGuidance": { "type": "boolean" }, "externalRefillHandoff": { "type": "boolean" }, "priceLookup": { "type": "boolean" }, "orderCreation": { "type": "boolean" }, "orderStatus": { "type": "boolean" } }, "required": [ "firstFillGuidance", "externalRefillHandoff", "priceLookup", "orderCreation", "orderStatus" ] }, "PharmacyPreferenceSchema": { "type": "string", "enum": [ "amazon_pharmacy" ] }, "pharmacySchema": { "type": "object", "properties": { "chronicPreventive": { "type": "string", "enum": [ "zero_dollar_pre_deductible" ] }, "generic": { "type": "string", "enum": [ "zero_dollar_post_deductible" ] }, "brand": { "type": "string", "enum": [ "zero_dollar_post_deductible" ] }, "specialty": { "type": "string", "enum": [ "prior_auth_navigation" ] }, "glp1": { "type": "string", "enum": [ "t2d_gate" ] } }, "required": [ "chronicPreventive", "generic", "brand", "specialty", "glp1" ], "additionalProperties": false }, "PlanAddOnsSchema": { "type": "object", "properties": { "dentalVision": { "type": "boolean" }, "carrot": { "type": "boolean" }, "wellnessPack": { "type": "boolean" }, "lifestylePerk": { "type": "boolean" } }, "required": [ "dentalVision", "carrot", "wellnessPack", "lifestylePerk" ] }, "PlanBalancesSchema": { "type": "object", "properties": { "deductible": { "$ref": "#/components/schemas/BalanceBucketSchema" }, "outOfPocketMax": { "$ref": "#/components/schemas/BalanceBucketSchema" }, "outOfPocketMaxIndividual": { "allOf": [ { "$ref": "#/components/schemas/BalanceBucketSchema" } ] }, "fitnessStipend": { "$ref": "#/components/schemas/BalanceBucketSchema" }, "wearableStipend": { "$ref": "#/components/schemas/BalanceBucketSchema" } }, "required": [ "deductible", "outOfPocketMax", "fitnessStipend", "wearableStipend" ] }, "PlanConfigAddOnsSchema": { "type": "object", "properties": { "dentalVision": { "type": "boolean" }, "carrot": { "type": "boolean" }, "wellnessPack": { "type": "boolean" }, "lifestylePerk": { "type": "boolean" } }, "required": [ "dentalVision", "carrot", "wellnessPack", "lifestylePerk" ], "additionalProperties": false }, "planConfigSchema": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "designVersion": { "type": "string", "enum": [ "rivendell-one-2026-r7" ] }, "channel": { "type": "string", "enum": [ "direct", "brokered" ] }, "brokerCommissionPepmCents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "foundingCohort": { "type": "boolean" }, "seedPercent": { "type": "integer", "enum": [ 0, 100 ] }, "surplusPolicy": { "type": "string", "enum": [ "experience_account", "return_at_settlement" ] }, "addOns": { "$ref": "#/components/schemas/PlanConfigAddOnsSchema" }, "approvalRefs": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "schemaVersion", "designVersion", "channel", "foundingCohort", "seedPercent", "surplusPolicy", "addOns", "approvalRefs" ], "additionalProperties": false }, "planDesignRowSchema": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "rivendell-one-2026-r7" ] }, "status": { "type": "string", "enum": [ "active" ] }, "rateCard": { "$ref": "#/components/schemas/rateCardSchema" }, "hsaSeed": { "$ref": "#/components/schemas/hsaSeedSchema" }, "addOnPricing": { "$ref": "#/components/schemas/addOnPricingSchema" }, "presenterFacts": { "$ref": "#/components/schemas/presenterFactsSchema" }, "benefitGrid": { "$ref": "#/components/schemas/benefitGridSchema" } }, "required": [ "key", "status", "rateCard", "hsaSeed", "addOnPricing", "presenterFacts", "benefitGrid" ], "additionalProperties": false }, "PlanDetailsSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "health_plan" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^health_plan_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "updated_at": { "type": "integer" }, "name": { "type": "string", "description": "Plan name" }, "designVersion": { "allOf": [ { "$ref": "#/components/schemas/CurrentPlanDesignKeySchema" } ], "description": "The current plan design key" }, "deductible": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Deductible limit for the enrollment" }, "outOfPocketMax": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Out-of-pocket max for the enrollment" }, "coinsuranceRate": { "type": "number", "description": "Coinsurance rate for the plan (percentage)" }, "dentalCovered": { "type": "boolean" }, "visionCovered": { "type": "boolean" }, "primaryCareCovered": { "type": "boolean" }, "urgentCareCovered": { "type": "boolean" }, "virtualUrgentCareCoveredAtZeroDollars": { "type": "boolean" }, "inPersonUrgentCareSubjectToDeductible": { "type": "boolean" }, "bloodPanelsCovered": { "type": "boolean" }, "fitnessStipend": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Monthly fitness stipend" }, "wearableStipend": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Annual wearable reimbursement" }, "addOns": { "$ref": "#/components/schemas/PlanAddOnsSchema" }, "dependents": { "type": "array", "items": { "$ref": "#/components/schemas/DependentSchema" } } }, "required": [ "object", "id", "created", "livemode", "metadata", "updated_at", "name", "designVersion", "deductible", "outOfPocketMax", "coinsuranceRate", "dentalCovered", "visionCovered", "primaryCareCovered", "urgentCareCovered", "virtualUrgentCareCoveredAtZeroDollars", "inPersonUrgentCareSubjectToDeductible", "bloodPanelsCovered", "fitnessStipend", "wearableStipend", "addOns", "dependents" ], "additionalProperties": true }, "PlanEnrollmentSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "enrollment" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^enrollment_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "updated_at": { "type": "integer" }, "startDate": { "type": "string", "format": "date-time", "description": "Enrollment start date" }, "active": { "type": "boolean", "description": "Whether the enrollment is active" } }, "required": [ "object", "id", "created", "livemode", "metadata", "updated_at", "startDate", "active" ], "additionalProperties": true }, "planRegionalFactorsSchema": { "type": "object", "properties": { "anchor": { "type": "string", "minLength": 1 }, "fallbackFactor": { "type": "number", "minimum": 0.5, "maximum": 1.1 }, "metroFactors": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0.5, "maximum": 1.1 }, "propertyNames": { "type": "string", "minLength": 1 } }, "zip3ToMetro": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 }, "propertyNames": { "type": "string", "pattern": "^\\d{3}$" } } }, "required": [ "anchor", "fallbackFactor", "metroFactors", "zip3ToMetro" ], "additionalProperties": false }, "PlanResponseSchema": { "type": "object", "properties": { "enrollment": { "$ref": "#/components/schemas/PlanEnrollmentSchema" }, "plan": { "$ref": "#/components/schemas/PlanDetailsSchema" }, "funding": { "$ref": "#/components/schemas/MemberFundingSchema" }, "balances": { "$ref": "#/components/schemas/PlanBalancesSchema" }, "yearSummary": { "allOf": [ { "$ref": "#/components/schemas/PlanYearSummarySchema" } ] } }, "required": [ "enrollment", "plan", "funding", "balances" ] }, "PlanYearSummarySchema": { "type": "object", "properties": { "planYearStartsAt": { "type": "string", "format": "date-time" }, "planYearEndsAt": { "type": "string", "format": "date-time" }, "asOf": { "type": "string", "format": "date-time" }, "coveredVisitCount": { "type": "integer", "minimum": 0 }, "zeroMemberShareVisitCount": { "type": "integer", "minimum": 0 }, "submittedTotal": { "type": "integer", "minimum": 0 }, "eligibleTotal": { "type": "integer", "minimum": 0 }, "planPaidTotal": { "type": "integer", "minimum": 0 }, "memberResponsibilityTotal": { "type": "integer", "minimum": 0 }, "cardOriginatedBillCount": { "type": "integer", "minimum": 0 } }, "required": [ "planYearStartsAt", "planYearEndsAt", "asOf", "coveredVisitCount", "zeroMemberShareVisitCount", "submittedTotal", "eligibleTotal", "planPaidTotal", "memberResponsibilityTotal", "cardOriginatedBillCount" ] }, "PreAuthorizationIdSchema": { "type": "string", "pattern": "^pre_authorization_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "PreAuthorizationParamsSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationIdSchema" } ], "description": "Pre-authorization ID" } }, "required": [ "id" ], "description": "Path parameters for pre-authorization admin actions" }, "PreAuthorizationSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "pre_authorization" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^pre_authorization_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "category": { "$ref": "#/components/schemas/ServiceCategoryReadSchema" }, "amount": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "isUsed": { "type": "boolean" }, "usedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "merchantDescriptor": { "type": [ "string", "null" ] }, "merchantCategoryCode": { "type": [ "string", "null" ] }, "reviewedBy": { "type": [ "string", "null" ] }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "created", "livemode", "metadata", "organizationId", "userId", "status", "category", "amount", "description", "isUsed", "usedAt", "expiresAt", "merchantDescriptor", "merchantCategoryCode", "reviewedBy", "reviewedAt", "createdAt", "updatedAt" ], "additionalProperties": true }, "PreAuthorizationsListQuerySchema": { "type": "object", "properties": { "status": { "type": "string", "description": "Comma-separated statuses (e.g. PENDING,APPROVED)" }, "open": { "type": "string", "enum": [ "true", "false" ], "description": "open=true returns only actionable requests: PENDING, unexpired, unconsumed" }, "cardActivityId": { "type": "string", "description": "A card-activity item id from GET /card-activity. Returns the pre-authorization auto-created for that decline (empty list when none exists) — the reliable 'already requested' check. Other filters are ignored." }, "limit": { "description": "Max number of pre-authorizations to return", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "offset": { "description": "Offset for pagination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "PreAuthorizationsListResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberPreAuthorizationSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ], "additionalProperties": true }, "PreAuthorizationStatusFilterSchema": { "type": "array", "items": { "$ref": "#/components/schemas/PreAuthorizationStatusSchema" } }, "PreAuthorizationStatusSchema": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "CANCELED" ] }, "PreferredPharmacySchema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/PharmacyPreferenceSchema" }, "displayName": { "type": "string" }, "ePrescribingName": { "type": [ "string", "null" ] }, "ncpdpId": { "type": [ "string", "null" ] }, "address": { "allOf": [ { "$ref": "#/components/schemas/PharmacyAddressSchema" } ], "nullable": true }, "externalRefillUrl": { "type": [ "string", "null" ], "format": "uri" }, "capabilities": { "$ref": "#/components/schemas/PharmacyCapabilitiesSchema" } }, "required": [ "key", "displayName", "ePrescribingName", "ncpdpId", "address", "externalRefillUrl", "capabilities" ] }, "PremiumDistributionIdSchema": { "type": "string", "pattern": "^premium_distribution_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "PremiumPaymentIdSchema": { "type": "string", "pattern": "^premium_payment_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "presenterFactsSchema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1 }, "planType": { "type": "string", "minLength": 1 }, "memberPresentation": { "type": "object", "properties": { "versionLabel": { "type": "string", "minLength": 1 }, "planYear": { "type": "integer" }, "readinessQualifier": { "type": "string", "minLength": 1 }, "pricing": { "type": "object", "properties": { "standardInsuranceMonthlyCents": { "$ref": "#/components/schemas/centsSchema" }, "foundingInsuranceMonthlyCents": { "$ref": "#/components/schemas/centsSchema" }, "basis": { "type": "string", "minLength": 1 } }, "required": [ "standardInsuranceMonthlyCents", "foundingInsuranceMonthlyCents", "basis" ], "additionalProperties": false }, "costSharing": { "type": "object", "properties": { "deductibleIndividualCents": { "$ref": "#/components/schemas/centsSchema" }, "deductibleFamilyCents": { "$ref": "#/components/schemas/centsSchema" }, "outOfPocketMaxIndividualCents": { "$ref": "#/components/schemas/centsSchema" }, "outOfPocketMaxFamilyCents": { "$ref": "#/components/schemas/centsSchema" }, "coinsurancePercent": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "deductibleIndividualCents", "deductibleFamilyCents", "outOfPocketMaxIndividualCents", "outOfPocketMaxFamilyCents", "coinsurancePercent" ], "additionalProperties": false }, "hsa": { "type": "object", "properties": { "individualAnnualSeedCents": { "$ref": "#/components/schemas/centsSchema" }, "familyAnnualSeedCents": { "$ref": "#/components/schemas/centsSchema" }, "memberKeepsUnusedFunds": { "type": "boolean" } }, "required": [ "individualAnnualSeedCents", "familyAnnualSeedCents", "memberKeepsUnusedFunds" ], "additionalProperties": false }, "coreBenefits": { "type": "array", "items": { "$ref": "#/components/schemas/memberBenefitFactSchema" }, "minItems": 1 }, "addOns": { "type": "array", "items": { "$ref": "#/components/schemas/memberAddOnFactSchema" } }, "howItWorks": { "type": "array", "items": { "$ref": "#/components/schemas/memberBenefitFactSchema" } }, "faqs": { "type": "array", "items": { "$ref": "#/components/schemas/memberFaqFactSchema" } } }, "required": [ "versionLabel", "planYear", "readinessQualifier", "pricing", "costSharing", "hsa", "coreBenefits", "addOns", "howItWorks", "faqs" ], "additionalProperties": false } }, "required": [ "displayName", "planType", "memberPresentation" ], "additionalProperties": false }, "PreviewCoverageRequestSchema": { "type": "object", "properties": { "category": { "type": "string" } } }, "PreviewCoverageResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "coverage": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } } }, "required": [ "success", "coverage" ] }, "ProcedureRequestResponseSchema": { "$ref": "#/components/schemas/AppointmentSummarySchema" }, "ProcedureSupportingMaterialStatusSchema": { "type": "string", "enum": [ "available", "not_available", "not_sure", "not_applicable" ] }, "ProcedureTimingFlexibilitySchema": { "type": "string", "enum": [ "as_soon_as_possible", "within_month", "flexible" ] }, "ProviderDetailsInputSchema": { "type": "object", "properties": { "doctorId": { "allOf": [ { "$ref": "#/components/schemas/DoctorIdSchema" } ], "description": "Rivendell doctor ID" }, "serviceName": { "type": "string", "minLength": 1 }, "cptCode": { "type": "string", "minLength": 1 }, "includeStaleRates": { "type": "boolean", "default": false } }, "required": [ "doctorId", "includeStaleRates" ] }, "PushDeviceIdSchema": { "type": "string", "pattern": "^push_device_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "PushDeviceSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the registered device" }, "userId": { "type": "string", "description": "Owner of the registered device" }, "deviceToken": { "type": "string", "description": "Stored push token for the device" }, "platform": { "allOf": [ { "$ref": "#/components/schemas/PushPlatformSchema" } ], "description": "Mobile platform" }, "deviceId": { "type": [ "string", "null" ], "description": "Stable device identifier when provided by the app" }, "appVersion": { "type": [ "string", "null" ], "description": "Mobile app version string" }, "deviceModel": { "type": [ "string", "null" ], "description": "Human readable device model name" }, "osVersion": { "type": [ "string", "null" ], "description": "Operating system version" }, "locale": { "type": [ "string", "null" ], "description": "Locale reported by the device" }, "timeZone": { "type": [ "string", "null" ], "description": "IANA time zone identifier reported by the device" }, "lastRegisteredAt": { "type": "string", "format": "date-time", "description": "When this token was last registered by the user" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this token was revoked, if applicable" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record was last updated" } }, "required": [ "id", "userId", "deviceToken", "platform", "deviceId", "appVersion", "deviceModel", "osVersion", "locale", "timeZone", "lastRegisteredAt", "revokedAt", "createdAt", "updatedAt" ], "description": "Registered push notification device record" }, "PushPlatformSchema": { "type": "string", "enum": [ "ios", "android" ], "description": "Mobile platform that issued the device token" }, "PushProvisionErrorSchema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages" } }, "required": [ "error" ], "description": "Error response payload" }, "PushProvisionRequestSchema": { "type": "object", "properties": { "certificates": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Base64-encoded leaf and intermediate certificates from Apple" }, "nonce": { "type": "string", "minLength": 1, "description": "Base64-encoded nonce from Apple" }, "nonce_signature": { "type": "string", "minLength": 1, "description": "Base64-encoded nonce signature from Apple" } }, "required": [ "certificates", "nonce", "nonce_signature" ], "description": "Request body for Apple Pay push provisioning" }, "PushProvisionResponseSchema": { "type": "object", "properties": { "activation_data": { "type": "string", "description": "Base64-encoded activation data for PassKit" }, "encrypted_pass_data": { "type": "string", "description": "Base64-encoded encrypted pass data for PassKit" }, "ephemeral_public_key": { "type": "string", "description": "Base64-encoded ephemeral public key for PassKit" } }, "required": [ "activation_data", "encrypted_pass_data", "ephemeral_public_key" ], "description": "Apple Pay push provisioning response payload" }, "QuoteCensusInputSchema": { "type": "object", "properties": { "effectiveDate": { "type": "string", "format": "date", "description": "Employer coverage start date in YYYY-MM-DD format." }, "csv": { "type": "string", "minLength": 1, "description": "Raw census CSV or TSV. Clean files use deterministic parsing up to 5,000 employees; malformed files can use model correction up to 500 source rows." }, "employees": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "minLength": 1, "description": "Canonical coverage tier or free text such as EE Only, Family, or EE + Spouse." }, "zip": { "type": [ "string", "null" ], "description": "US ZIP code." }, "ref": { "type": [ "string", "null" ], "description": "Caller's row ID." } }, "required": [ "tier" ] }, "minItems": 1, "description": "Pre-parsed rows, when the caller already has structured data." }, "benchmarkAnnualCents": { "type": "integer", "exclusiveMinimum": 0, "description": "Incumbent annual cost in cents to compare against." }, "foundingCohort": { "type": "boolean", "description": "Price only this founding-cohort setting. Omit to receive the full grid." }, "seedPercent": { "type": "integer", "enum": [ 0, 100 ], "description": "Price only this employer HSA funding level. Omit to receive the full grid." }, "channel": { "type": "string", "enum": [ "direct", "brokered" ], "default": "brokered" }, "correction": { "type": "string", "enum": [ "auto", "always", "disabled" ], "default": "auto", "description": "Auto uses Claude only when deterministic parsing cannot produce a complete census. Always forces canonical model extraction for files of at most 500 source rows. Disabled never sends census data to a model." } }, "required": [ "effectiveDate" ] }, "rateCardSchema": { "type": "object", "properties": { "claimsFundCents": { "$ref": "#/components/schemas/centsSchema" }, "stopLossCents": { "$ref": "#/components/schemas/centsSchema" }, "operationalReserveCents": { "$ref": "#/components/schemas/centsSchema" }, "corridorReserveCents": { "$ref": "#/components/schemas/centsSchema" }, "subscriptionsCents": { "$ref": "#/components/schemas/centsSchema" }, "platformFeeStandardCents": { "$ref": "#/components/schemas/centsSchema" }, "platformFeeFoundingCents": { "$ref": "#/components/schemas/centsSchema" }, "distributionCents": { "$ref": "#/components/schemas/centsSchema" }, "regionalFactors": { "$ref": "#/components/schemas/planRegionalFactorsSchema" }, "rateBasis": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "pricedThrough": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "label", "pricedThrough" ], "additionalProperties": false } }, "required": [ "claimsFundCents", "stopLossCents", "operationalReserveCents", "corridorReserveCents", "subscriptionsCents", "platformFeeStandardCents", "platformFeeFoundingCents", "distributionCents", "regionalFactors", "rateBasis" ], "additionalProperties": false }, "RateSchema": { "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountSchema" } ], "description": "Full provider charge, paid with the Rivendell card at the visit" }, "source": { "allOf": [ { "$ref": "#/components/schemas/RateSourceSchema" } ], "description": "Confidence level: expected (intake estimate), confirmed (booking-confirmed), claim (adjudicated)" } }, "required": [ "amount", "source" ] }, "RateSourceSchema": { "type": "string", "enum": [ "expected", "confirmed", "claim" ] }, "ReadjudicateClaimRequestSchema": { "type": "object", "properties": { "providerRefundFinal": { "type": "boolean", "enum": [ true ] }, "planPaidCents": { "type": "integer", "minimum": 0 }, "memberResponsibilityCents": { "type": "integer", "minimum": 0 }, "deductibleAppliedCents": { "type": "integer", "minimum": 0 }, "coinsuranceAppliedCents": { "type": "integer", "minimum": 0 }, "explanation": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "providerRefundFinal", "planPaidCents", "memberResponsibilityCents", "deductibleAppliedCents", "coinsuranceAppliedCents", "explanation" ] }, "ReadjudicateClaimResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "claimId": { "type": "string" }, "adjudicationSnapshotId": { "type": "string" }, "adjudicationVersion": { "type": "integer", "exclusiveMinimum": 0 }, "refundExecutionPending": { "type": "boolean" }, "proposalId": { "type": [ "string", "null" ] } }, "required": [ "success", "claimId", "adjudicationSnapshotId", "adjudicationVersion", "refundExecutionPending", "proposalId" ] }, "RecoveryDaySchema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "day": { "type": "string" }, "score": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "WHOOP recovery score or Oura readiness score, both 0-100" }, "hrvMilliseconds": { "$ref": "#/components/schemas/nullableNumber" }, "restingHeartRate": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Resting heart rate for the day. WHOOP reports this; Oura does not." }, "lowestHeartRate": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Lowest heart rate during sleep. Oura reports this; WHOOP does not." }, "skinTemperatureCelsius": { "$ref": "#/components/schemas/nullableNumber" }, "temperatureDeviationCelsius": { "$ref": "#/components/schemas/nullableNumber" }, "spo2Percentage": { "$ref": "#/components/schemas/nullableNumber" }, "isCalibrating": { "type": [ "boolean", "null" ] }, "raw": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" }, "description": "The untouched provider payload. Present only when includeRaw=true." } }, "required": [ "provider", "day", "score", "hrvMilliseconds", "restingHeartRate", "lowestHeartRate", "skinTemperatureCelsius", "temperatureDeviationCelsius", "spo2Percentage", "isCalibrating" ] }, "RecoveryResponseSchema": { "type": "object", "properties": { "range": { "$ref": "#/components/schemas/WearableRangeSchema" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/RecoveryDaySchema" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/WearableProviderOutcomeSchema" } }, "noConnections": { "type": "boolean", "description": "No wearable is linked to this account at all." }, "continueWith": { "description": "Present when the upstream page budget ran out before the window did. Pass these dates back to fetch the older records that were cut.", "allOf": [ { "$ref": "#/components/schemas/WearableRangeSchema" } ], "nullable": true } }, "required": [ "range", "days", "providers", "noConnections", "continueWith" ] }, "referenceRangeSchema": { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" }, "unit": { "type": "string" } }, "additionalProperties": false }, "RegisterPushDeviceRequestSchema": { "type": "object", "properties": { "deviceToken": { "type": "string", "minLength": 1, "description": "APNs/FCM/Expo push token for the device" }, "platform": { "$ref": "#/components/schemas/PushPlatformSchema" }, "deviceId": { "type": "string", "minLength": 1, "description": "Stable device identifier used to revoke old tokens" }, "appVersion": { "type": "string", "minLength": 1, "description": "Mobile app version string" }, "deviceModel": { "type": "string", "minLength": 1, "description": "Human readable device model name" }, "osVersion": { "type": "string", "minLength": 1, "description": "Operating system version" }, "locale": { "type": "string", "minLength": 1, "description": "Locale reported by the device" }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA time zone identifier reported by the device" } }, "required": [ "deviceToken", "platform" ], "description": "Payload for registering a push notification device token" }, "RegisterPushDeviceResponseSchema": { "type": "object", "properties": { "device": { "allOf": [ { "$ref": "#/components/schemas/PushDeviceSchema" } ], "description": "The stored push device metadata" } }, "required": [ "device" ], "description": "Successful push device registration response" }, "RejectPreAuthorizationResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "preAuthorizationId": { "type": "string" }, "preAuthorization": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationSchema" } ] }, "error": { "type": "string" } }, "required": [ "success" ] }, "RelationshipSchema": { "type": "string", "enum": [ "SPOUSE", "CHILD" ], "description": "Dependent relationship to employee" }, "RequestCashPayQuoteInputSchema": { "type": "object", "properties": { "doctorId": { "allOf": [ { "$ref": "#/components/schemas/DoctorIdSchema" } ], "description": "Rivendell doctor ID" }, "serviceName": { "type": "string", "minLength": 1 }, "cptCode": { "type": "string", "minLength": 1 }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "doctorId", "serviceName" ] }, "RequiredMobileAppBuildSchema": { "type": "string", "minLength": 1, "maxLength": 100 }, "ResidentialAddressRequestSchema": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 200 }, "line2": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "postalCode": { "type": "string", "pattern": "^\\d{5}(?:-\\d{4})?$" }, "country": { "type": "string", "enum": [ "US" ] } }, "required": [ "line1", "city", "state", "postalCode", "country" ], "additionalProperties": false, "description": "Complete US residential address" }, "ResidentialAddressResponseAddressSchema": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "enum": [ "US" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "description": "Normalized residential address used for card billing" }, "ResidentialAddressStatusResponseSchema": { "type": "object", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/ResidentialAddressResponseAddressSchema" } ], "nullable": true }, "card_sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "synced", "pending" ] }, "pending_cards": { "type": "integer", "minimum": 0 } }, "required": [ "status", "pending_cards" ] } }, "required": [ "address", "card_sync" ], "description": "Current residential address and card synchronization status" }, "ResidentialAddressUpdateResponseSchema": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/ResidentialAddressResponseAddressSchema" }, "card_sync": { "$ref": "#/components/schemas/CardAddressSyncSchema" } }, "required": [ "address", "card_sync" ], "description": "Updated address and card synchronization result" }, "ResourceSummarySchema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "claims", "benefits", "cards", "medications", "providers", "appointments", "wearables" ] }, "object": { "type": "string" }, "summary": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "string" } }, "sandbox_endpoints": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "object", "summary", "endpoints", "sandbox_endpoints" ] }, "ResubstantiateClaimResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "substantiated": { "type": "boolean" }, "reason": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success", "substantiated" ] }, "ResubstantiateOrgRequestSchema": { "type": "object", "properties": { "organizationId": { "$ref": "#/components/schemas/OrganizationIdSchema" } }, "required": [ "organizationId" ] }, "ResubstantiateOrgResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "checked": { "type": "integer" }, "substantiated": { "type": "integer" } }, "required": [ "success", "checked", "substantiated" ] }, "ReviewInsightSchema": { "type": "object", "properties": { "doctorId": { "type": "string" }, "reviewSummary": { "type": [ "string", "null" ] }, "reviewAttributes": { "type": "array", "items": { "type": "string" } }, "reviewSummaryStatus": { "$ref": "#/components/schemas/ReviewInsightStatusSchema" }, "reviewCount": { "type": [ "integer", "null" ] }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "doctorId", "reviewSummary", "reviewAttributes", "reviewSummaryStatus", "reviewCount", "generatedAt", "updatedAt" ] }, "ReviewInsightsQuerySchema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "$ref": "#/components/schemas/DoctorIdSchema" }, "minItems": 1, "maxItems": 20, "description": "Doctor IDs to fetch insights for." } }, "required": [ "ids" ] }, "ReviewInsightsResponseSchema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewInsightSchema" } } }, "required": [ "results" ] }, "ReviewInsightsSchema": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 800, "description": "2-3 short sentences summarizing the overall review themes." }, "attributes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "3-4 short adjectives (single word or two words max)." } }, "required": [ "summary", "attributes" ] }, "ReviewInsightStatusSchema": { "type": "string", "enum": [ "ready", "pending", "empty", "failed" ] }, "SandboxBenefitsResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "benefits_summary" ] }, "livemode": { "type": "boolean", "enum": [ false ] }, "created": { "type": "integer" }, "enrollment": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "enrollment" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^enrollment_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean", "enum": [ false ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "active": { "type": "boolean", "enum": [ true ] }, "start_date": { "type": "integer" } }, "required": [ "object", "id", "created", "livemode", "metadata", "active", "start_date" ] }, "plan": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "health_plan" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^health_plan_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean", "enum": [ false ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "coinsurance_rate": { "type": "number" }, "deductible": { "$ref": "#/components/schemas/AmountSchema" }, "out_of_pocket_max": { "$ref": "#/components/schemas/AmountSchema" } }, "required": [ "object", "id", "created", "livemode", "metadata", "name", "coinsurance_rate", "deductible", "out_of_pocket_max" ] }, "balances": { "type": "object", "properties": { "deductible": { "$ref": "#/components/schemas/BalanceBucketSchema" }, "out_of_pocket_max": { "$ref": "#/components/schemas/BalanceBucketSchema" }, "fitness_stipend": { "$ref": "#/components/schemas/BalanceBucketSchema" }, "wearable_stipend": { "$ref": "#/components/schemas/BalanceBucketSchema" } }, "required": [ "deductible", "out_of_pocket_max", "fitness_stipend", "wearable_stipend" ] } }, "required": [ "object", "livemode", "created", "enrollment", "plan", "balances" ] }, "SandboxClaimSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "claim" ] }, "id": { "type": "string", "description": "Prefixed typed identifier in the form `{prefix}_{body}` where prefix is the snake_case resource name (e.g. `claim_`, `bank_account_`, `pre_authorization_`) and body is 24 chars of base32 lowercase for newly created resources. Resources created before the prefix rollout (or via Better Auth) keep their legacy 24/25/32-char CUID/Better-Auth bodies, prefixed in place — both shapes match the published `pattern`.", "pattern": "^claim_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean", "enum": [ false ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "member_id": { "type": "string" }, "source": { "type": "string", "enum": [ "REIMBURSEMENT" ] }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING_SUBSTANTIATION", "SUBMITTED", "IN_REVIEW", "APPROVED", "REJECTED", "PAID" ] }, "category": { "$ref": "#/components/schemas/ServiceCategoryReadSchema" }, "submitted_amount": { "type": "integer" }, "approved_amount": { "type": [ "integer", "null" ] }, "member_owes": { "type": [ "integer", "null" ] }, "deductible_applied": { "type": [ "integer", "null" ] }, "coinsurance_applied": { "type": [ "integer", "null" ] }, "service_date": { "type": "integer" }, "merchant_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "receipt_url": { "type": [ "string", "null" ] }, "uploaded_at": { "type": [ "integer", "null" ] } }, "required": [ "object", "id", "created", "livemode", "metadata", "member_id", "source", "status", "category", "submitted_amount", "approved_amount", "member_owes", "deductible_applied", "coinsurance_applied", "service_date", "merchant_name", "description", "receipt_url", "uploaded_at" ] }, "SandboxClaimsListResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxClaimSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "SandboxCreateClaimRequestSchema": { "type": "object", "properties": { "member_id": { "type": "string", "minLength": 1, "default": "mem_test_001", "description": "Sandbox-only member identifier. This does not need to exist." }, "service_category": { "$ref": "#/components/schemas/ActiveServiceCategorySchema", "default": "GENERAL_MEDICAL" }, "submitted_amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "service_date": { "type": "string", "format": "date-time", "description": "Date the service was provided" }, "merchant_name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } }, "required": [ "member_id", "service_category", "submitted_amount", "service_date" ] }, "SandboxCreateClaimResponseSchema": { "$ref": "#/components/schemas/SandboxClaimSchema" }, "SandboxErrorResponseSchema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "param": { "type": "string" }, "code": { "type": "string" }, "recovery_hint": { "$ref": "#/components/schemas/SandboxRecoveryHintSchema" } }, "required": [ "type", "title", "status", "detail", "recovery_hint" ] }, "SandboxErrorSimulationRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "default": "validation_error" }, "title": { "type": "string", "minLength": 1 }, "detail": { "type": "string", "minLength": 1 }, "param": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1 }, "recovery_hint": { "$ref": "#/components/schemas/SandboxRecoveryHintSchema", "default": "CHECK_INPUT" } }, "required": [ "type", "recovery_hint" ] }, "SandboxMedicationSearchQuerySchema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Medication search query" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "q" ] }, "SandboxMedicationSearchResponseSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxMedicationSearchResultSchema" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "url" ] }, "SandboxMedicationSearchResultSchema": { "type": "object", "properties": { "id": { "type": "string" }, "ndc": { "type": "string" }, "medication_name": { "type": "string" }, "brand_name": { "type": [ "string", "null" ] }, "strength": { "type": "string" }, "form": { "type": [ "string", "null" ] }, "formatted_price": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "display_name": { "type": "string" }, "livemode": { "type": "boolean", "enum": [ false ] } }, "required": [ "id", "ndc", "medication_name", "brand_name", "strength", "form", "formatted_price", "url", "display_name", "livemode" ] }, "SandboxRecoveryHintSchema": { "type": "string", "enum": [ "RETRY_LATER", "CHECK_INPUT", "TRY_ALTERNATIVE", "REQUIRES_USER_ACTION", "UNRECOVERABLE" ] }, "ScheduleDoctorsRequestSchema": { "type": "object", "properties": { "doctors": { "type": "array", "items": { "$ref": "#/components/schemas/DoctorSelectionSchema" }, "minItems": 1 }, "availability": { "$ref": "#/components/schemas/AvailabilitySchema" }, "location": { "type": "object", "properties": { "zipCode": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "zipCode" ] }, "specialty": { "type": "string", "description": "Doctor field or specialty (e.g., 'dentist', 'cardiologist')" }, "careType": { "type": "string", "description": "Type of care or consultation (e.g., 'skin problem', 'hair loss')" }, "symptoms": { "type": "array", "items": { "type": "string" }, "description": "List of patient symptoms (e.g., ['acne', 'tooth pain'])" }, "notes": { "type": "string", "maxLength": 2000, "description": "Additional free-text notes alongside symptoms" }, "urgency": { "type": "string", "enum": [ "routine", "soon", "immediate" ], "description": "Level of urgency" }, "visitType": { "type": "string", "enum": [ "virtual", "inperson", "any" ], "description": "Preferred visit type" } }, "required": [ "doctors", "availability", "location", "specialty", "symptoms", "urgency", "visitType" ] }, "SearchMedicationsInputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "offset": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "query", "limit", "offset" ] }, "SendDependentInviteInputSchema": { "type": "object", "properties": { "dependentId": { "allOf": [ { "$ref": "#/components/schemas/DependentIdSchema" } ], "description": "Rivendell dependent census entry ID" } }, "required": [ "dependentId" ] }, "SendOtpRequestSchema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "pattern": "^\\+1\\d{10}$", "description": "Phone number in E.164 format (+1XXXXXXXXXX)" } }, "required": [ "phoneNumber" ], "description": "Request to send an OTP code via SMS" }, "SendOtpResponseSchema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Whether the OTP was sent successfully" } }, "required": [ "status" ], "description": "OTP send result" }, "serverSchema": { "type": "object", "properties": { "DATABASE_URL": { "type": "string", "format": "uri" }, "DB_AUTH_MODE": { "type": "string", "enum": [ "iam", "password" ] }, "GCP_WORKLOAD_IDENTITY_AUDIENCE": { "type": "string" }, "GCP_SERVICE_ACCOUNT_EMAIL": { "type": "string" }, "CLOUD_SQL_INSTANCE_CONNECTION_NAME": { "type": "string" }, "CLOUDFLARE_ACCOUNT_ID": { "type": "string", "minLength": 1 }, "R2_PUBLIC_ACCESS_KEY_ID": { "type": "string", "minLength": 1 }, "R2_PUBLIC_SECRET_ACCESS_KEY": { "type": "string", "minLength": 1 }, "R2_PRIVATE_ACCESS_KEY_ID": { "type": "string", "minLength": 1 }, "R2_PRIVATE_SECRET_ACCESS_KEY": { "type": "string", "minLength": 1 }, "R2_PUBLIC_BUCKET_NAME": { "type": "string", "minLength": 1 }, "R2_PRIVATE_BUCKET_NAME": { "type": "string", "minLength": 1 }, "BETTER_AUTH_SECRET": { "type": "string", "minLength": 32 }, "GOOGLE_CLIENT_SECRET": { "type": "string", "minLength": 1 }, "GOOGLE_IOS_CLIENT_ID": { "type": "string", "minLength": 1 }, "GOOGLE_MAPS_API_KEY": { "type": "string" }, "OPENAI_API_KEY": { "type": "string" }, "ANTHROPIC_API_KEY": { "type": "string" }, "REDUCTO_API_KEY": { "type": "string" }, "GOOGLE_CLOUD_PROJECT": { "type": "string" }, "BACKGROUND_TASK_QUEUE": { "type": "string" }, "BACKGROUND_TASK_RUNNER_URL": { "type": "string" }, "BACKGROUND_TASK_AUDIENCE": { "type": "string" }, "BACKGROUND_TASK_LOCATION": { "type": "string" }, "STRIPE_SECRET_KEY": { "type": "string" }, "STRIPE_WEBHOOK_SECRET": { "type": "string" }, "OURA_OAUTH_CLIENT_ID": { "type": "string" }, "OURA_OAUTH_CLIENT_SECRET": { "type": "string" }, "WHOOP_OAUTH_CLIENT_ID": { "type": "string" }, "WHOOP_OAUTH_CLIENT_SECRET": { "type": "string" }, "RESEND_API_KEY": { "type": "string" }, "APNS_KEY_ID": { "type": "string" }, "APNS_TEAM_ID": { "type": "string" }, "APNS_PRIVATE_KEY": { "type": "string" }, "APNS_BUNDLE_ID": { "type": "string" }, "APNS_ENV": { "type": "string", "enum": [ "sandbox", "production" ] }, "POSTHOG_KEY": { "type": "string" }, "INCREASE_API_KEY": { "type": "string" }, "INCREASE_PROGRAM_ID": { "type": "string" }, "INCREASE_RIVENDELL_ENTITY_ID": { "type": "string" }, "INCREASE_HSA_PROGRAM_ID": { "type": "string" }, "INCREASE_HSA_CUSTODIAN_ENTITY_ID": { "type": "string" }, "INCREASE_OPERATING_ACCOUNT_ID": { "type": "string" }, "INCREASE_MERCURY_EXTERNAL_ACCOUNT_ID": { "type": "string" }, "INCREASE_CORRIDOR_RESERVE_ACCOUNT_ID": { "type": "string" }, "INCREASE_DIGITAL_CARD_PROFILE_ID": { "type": "string" }, "INCREASE_WEBHOOK_SECRET": { "type": "string" }, "INCREASE_ENV": { "type": "string", "enum": [ "sandbox", "production" ], "default": "sandbox" }, "CLAIM_PAYMENT_EXECUTION_ENABLED": { "type": "string", "enum": [ "true", "false" ], "default": "true" }, "NODE_ENV": { "type": "string", "enum": [ "development", "test", "production" ], "default": "development" }, "OPS_NOTIFICATIONS_EMAIL": { "type": "string", "format": "email", "default": "ops@rivendell.health" }, "SLACK_OPS_WEBHOOK": { "type": "string", "format": "uri" }, "QUO_API_KEY": { "type": "string" }, "QUO_PHONE_NUMBER": { "type": "string" }, "MCP_ALLOWED_ORIGINS": { "type": "string" } }, "required": [ "CLOUDFLARE_ACCOUNT_ID", "R2_PUBLIC_ACCESS_KEY_ID", "R2_PUBLIC_SECRET_ACCESS_KEY", "R2_PRIVATE_ACCESS_KEY_ID", "R2_PRIVATE_SECRET_ACCESS_KEY", "R2_PUBLIC_BUCKET_NAME", "R2_PRIVATE_BUCKET_NAME", "BETTER_AUTH_SECRET", "GOOGLE_CLIENT_SECRET", "STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET", "CLAIM_PAYMENT_EXECUTION_ENABLED", "NODE_ENV", "OPS_NOTIFICATIONS_EMAIL" ] }, "ServiceCategoryReadSchema": { "type": "string", "description": "Service category of a stored claim or pre-authorization (includes historical categories on old rows)" }, "SessionIdSchema": { "type": "string", "pattern": "^session_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "SetPrimaryBankAccountRequestSchema": { "type": "object", "properties": { "bankAccountId": { "$ref": "#/components/schemas/BankAccountIdSchema" }, "ownerType": { "type": "string", "enum": [ "USER", "ORGANIZATION" ] } }, "required": [ "bankAccountId", "ownerType" ] }, "SetPrimaryBankAccountResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ] }, "SetPrimaryPayoutAccountInputSchema": { "type": "object", "properties": { "bankAccountId": { "allOf": [ { "$ref": "#/components/schemas/BankAccountIdSchema" } ], "description": "Rivendell bank account ID" } }, "required": [ "bankAccountId" ] }, "SexSchema": { "type": "string", "enum": [ "M", "F" ], "description": "Biological sex recorded for the employee" }, "signedPlanAllocationSchema": { "type": "object", "properties": { "claimsFundCents": { "$ref": "#/components/schemas/centsSchema" }, "stopLossCents": { "$ref": "#/components/schemas/centsSchema" }, "operationalReserveCents": { "$ref": "#/components/schemas/centsSchema" }, "corridorReserveCents": { "$ref": "#/components/schemas/centsSchema" }, "subscriptionsCents": { "$ref": "#/components/schemas/centsSchema" }, "platformFeeCents": { "$ref": "#/components/schemas/centsSchema" }, "distributionCents": { "$ref": "#/components/schemas/centsSchema" }, "insuranceSubtotalCents": { "$ref": "#/components/schemas/centsSchema" }, "hsaSeedCents": { "$ref": "#/components/schemas/centsSchema" }, "dentalVisionCents": { "$ref": "#/components/schemas/centsSchema" }, "carrotCents": { "$ref": "#/components/schemas/centsSchema" }, "wellnessPackCents": { "$ref": "#/components/schemas/centsSchema" }, "lifestylePerkCents": { "$ref": "#/components/schemas/centsSchema" }, "addOnsCents": { "$ref": "#/components/schemas/centsSchema" }, "totalEmployerOutlayCents": { "$ref": "#/components/schemas/centsSchema" } }, "required": [ "claimsFundCents", "stopLossCents", "operationalReserveCents", "corridorReserveCents", "subscriptionsCents", "platformFeeCents", "distributionCents", "insuranceSubtotalCents", "hsaSeedCents", "dentalVisionCents", "carrotCents", "wellnessPackCents", "lifestylePerkCents", "addOnsCents", "totalEmployerOutlayCents" ], "additionalProperties": false }, "signedPlanQuoteSchema": { "type": "object", "properties": { "designVersion": { "type": "string", "enum": [ "rivendell-one-2026-r7" ] }, "distributionRecipient": { "type": "string", "enum": [ "broker_of_record", "rivendell" ] }, "employees": { "type": "array", "items": { "type": "object", "properties": { "tier": { "$ref": "#/components/schemas/SignedRevisionEnrollmentTierSchema" }, "location": { "type": [ "string", "null" ] }, "regionalMultiplier": { "type": "number", "exclusiveMinimum": 0 }, "insuranceSubtotalCents": { "$ref": "#/components/schemas/centsSchema" }, "hsaSeedCents": { "$ref": "#/components/schemas/centsSchema" }, "addOnsCents": { "$ref": "#/components/schemas/centsSchema" }, "totalEmployerOutlayCents": { "$ref": "#/components/schemas/centsSchema" } }, "required": [ "tier", "location", "regionalMultiplier", "insuranceSubtotalCents", "hsaSeedCents", "addOnsCents", "totalEmployerOutlayCents" ], "additionalProperties": false } }, "insuranceSubtotalCents": { "$ref": "#/components/schemas/centsSchema" }, "hsaSeedCents": { "$ref": "#/components/schemas/centsSchema" }, "addOnsCents": { "$ref": "#/components/schemas/centsSchema" }, "totalEmployerOutlayCents": { "$ref": "#/components/schemas/centsSchema" }, "allocation": { "$ref": "#/components/schemas/signedPlanAllocationSchema" } }, "required": [ "designVersion", "distributionRecipient", "employees", "insuranceSubtotalCents", "hsaSeedCents", "addOnsCents", "totalEmployerOutlayCents", "allocation" ], "additionalProperties": false }, "signedPlanRevisionSchema": { "type": "object", "properties": { "designVersion": { "type": "string", "enum": [ "rivendell-one-2026-r7" ] }, "designConfig": { "$ref": "#/components/schemas/planConfigSchema" }, "design": { "$ref": "#/components/schemas/planDesignRowSchema" }, "employeeContribution": { "type": "integer", "minimum": 0, "maximum": 100 }, "dependentContribution": { "type": "integer", "minimum": 0, "maximum": 100 }, "quote": { "$ref": "#/components/schemas/signedPlanQuoteSchema" }, "censusHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signedAt": { "type": "string", "format": "date-time" } }, "required": [ "designVersion", "designConfig", "design", "employeeContribution", "dependentContribution", "quote", "censusHash", "signedAt" ], "additionalProperties": false }, "SignedRevisionEnrollmentTierSchema": { "type": "string", "enum": [ "EMPLOYEE_ONLY", "EMPLOYEE_SPOUSE", "EMPLOYEE_CHILD", "EMPLOYEE_FAMILY" ] }, "SignInEmailResponseSchema": { "type": "object", "properties": { "signInEmail": { "type": "string", "format": "email" }, "signInEmailVerified": { "type": "boolean" } }, "required": [ "signInEmail", "signInEmailVerified" ], "description": "Sign-in email status" }, "SleepNightSchema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "day": { "type": "string", "description": "Local calendar date the sleep period ended" }, "id": { "type": "string" }, "isNap": { "type": "boolean" }, "bedtimeStart": { "type": [ "string", "null" ] }, "bedtimeEnd": { "type": [ "string", "null" ] }, "timeInBedMinutes": { "$ref": "#/components/schemas/nullableNumber" }, "totalSleepMinutes": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Time asleep: light + deep + REM. Not time in bed minus awake, which would count WHOOP's no-data time as sleep." }, "remMinutes": { "$ref": "#/components/schemas/nullableNumber" }, "deepMinutes": { "$ref": "#/components/schemas/nullableNumber" }, "lightMinutes": { "$ref": "#/components/schemas/nullableNumber" }, "awakeMinutes": { "$ref": "#/components/schemas/nullableNumber" }, "noDataMinutes": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "WHOOP only: time the strap recorded nothing. Excluded from totalSleepMinutes." }, "efficiencyPercent": { "$ref": "#/components/schemas/nullableNumber" }, "score": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Oura sleep score or WHOOP sleep performance percentage, both 0-100" }, "averageHrv": { "$ref": "#/components/schemas/nullableNumber" }, "lowestHeartRate": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Lowest heart rate during the sleep period. Oura reports this; WHOOP does not." }, "restingHeartRate": { "allOf": [ { "$ref": "#/components/schemas/nullableNumber" } ], "description": "Resting heart rate for the day. WHOOP reports this on recovery. A different measurement from lowestHeartRate." }, "respiratoryRate": { "$ref": "#/components/schemas/nullableNumber" }, "raw": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" }, "description": "The untouched provider payload. Present only when includeRaw=true." } }, "required": [ "provider", "day", "id", "isNap", "bedtimeStart", "bedtimeEnd", "timeInBedMinutes", "totalSleepMinutes", "remMinutes", "deepMinutes", "lightMinutes", "awakeMinutes", "noDataMinutes", "efficiencyPercent", "score", "averageHrv", "lowestHeartRate", "restingHeartRate", "respiratoryRate" ] }, "SleepResponseSchema": { "type": "object", "properties": { "range": { "$ref": "#/components/schemas/WearableRangeSchema" }, "nights": { "type": "array", "items": { "$ref": "#/components/schemas/SleepNightSchema" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/WearableProviderOutcomeSchema" } }, "noConnections": { "type": "boolean", "description": "No wearable is linked to this account at all." }, "continueWith": { "description": "Present when the upstream page budget ran out before the window did. Pass these dates back to fetch the older records that were cut.", "allOf": [ { "$ref": "#/components/schemas/WearableRangeSchema" } ], "nullable": true } }, "required": [ "range", "nights", "providers", "noConnections", "continueWith" ] }, "StoredAdjudicationSchema": { "type": "object", "properties": { "outcome": { "type": "string" }, "rule": { "type": "string" }, "treatment": { "type": "string" }, "note": { "type": "string" } }, "required": [ "outcome", "rule", "treatment" ] }, "SubmitReimbursementClaimInputSchema": { "type": "object", "properties": { "serviceCategory": { "$ref": "#/components/schemas/ActiveServiceCategorySchema" }, "modality": { "allOf": [ { "$ref": "#/components/schemas/ClaimModalityApiSchema" } ] }, "submittedAmountCents": { "type": "integer", "exclusiveMinimum": 0 }, "serviceDate": { "type": "string", "format": "date", "description": "Date the service was provided (YYYY-MM-DD)" }, "merchantName": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } }, "required": [ "serviceCategory", "submittedAmountCents", "serviceDate" ] }, "SubscriptionIdSchema": { "type": "string", "pattern": "^subscription_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "TestResultIdSchema": { "type": "string", "pattern": "^test_result_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "TestTypeSchema": { "type": "string", "enum": [ "BLOOD_PANEL", "DEXA_SCAN", "MRI_SCAN", "VO2_MAX", "CT_SCAN", "ULTRASOUND" ] }, "TransactionIdSchema": { "type": "string", "pattern": "^transaction_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "TransactionStatusSchema": { "type": "string", "enum": [ "AUTHORIZED", "SETTLED", "REVERSED", "DECLINED" ] }, "UnitSystemSchema": { "type": "string", "enum": [ "METRIC", "IMPERIAL" ], "description": "Preferred measurement unit system" }, "UpdateCategoryRequestSchema": { "type": "object", "properties": { "category": { "type": "string" }, "chronicPreventiveEvidence": { "type": "string", "minLength": 2 } }, "required": [ "category" ] }, "UpdateCategoryResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "claim": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "fundBucket": { "type": "string" } }, "required": [ "id", "category", "fundBucket" ] } }, "required": [ "success", "claim" ] }, "UpdateClaimPaymentAuthorizationRequestSchema": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/ClaimPaymentAuthorizationModeSchema" }, "consentAccepted": { "type": "boolean", "enum": [ true ] }, "termsVersion": { "type": "string" } }, "required": [ "mode", "consentAccepted", "termsVersion" ] }, "UpdateDependentEmailInputSchema": { "type": "object", "properties": { "dependentId": { "allOf": [ { "$ref": "#/components/schemas/DependentIdSchema" } ], "description": "Rivendell dependent census entry ID" }, "email": { "type": [ "string", "null" ], "format": "email" } }, "required": [ "dependentId", "email" ] }, "UpdateDependentResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "description": "Dependent update response payload" }, "UpdateDependentSchema": { "type": "object", "properties": { "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "string", "enum": [ "" ] } ], "description": "Updated dependent email address" } }, "description": "Dependent update payload" }, "UpdateMemberMedicationRequestSchema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/MemberMedicationIdSchema" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "strength": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "form": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "prescriberName": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "status": { "allOf": [ { "$ref": "#/components/schemas/MemberMedicationStatusSchema" } ] }, "pharmacyPreference": { "allOf": [ { "$ref": "#/components/schemas/PharmacyPreferenceSchema" } ] }, "lastFilledAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id" ], "description": "Member-owned medication fields to update." }, "UpdateMerchantRuleResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "merchantRule": { "$ref": "#/components/schemas/MerchantRuleSchema" } }, "required": [ "success", "merchantRule" ] }, "UpdateMerchantRuleSchema": { "type": "object", "properties": { "isActive": { "type": "boolean" }, "billingType": { "allOf": [ { "$ref": "#/components/schemas/ClaimBillingTypeApiSchema" } ], "nullable": true }, "billingCadence": { "allOf": [ { "$ref": "#/components/schemas/BillingCadenceApiSchema" } ], "nullable": true }, "membershipProgram": { "type": [ "string", "null" ], "minLength": 1 }, "amountMin": { "type": [ "integer", "null" ], "minimum": 0 }, "amountMax": { "type": [ "integer", "null" ], "minimum": 0 }, "maxAmount": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "reason": { "type": [ "string", "null" ], "maxLength": 500 }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } } }, "UpdateTransactionSchema": { "type": "object", "properties": { "externalId": { "type": "string" }, "status": { "type": "string" }, "authorizedAmount": { "type": "integer" }, "settledAmount": { "type": "integer" }, "reversedAmount": { "type": "integer" }, "incrementedAmount": { "type": "integer" }, "fuelConfirmedAmount": { "type": "integer" }, "refundAuthorizedAmount": { "type": "integer" }, "refundedAmount": { "type": "integer" }, "merchantName": { "type": "string" }, "merchantCategoryCode": { "type": "string" }, "merchantCity": { "type": "string" }, "merchantState": { "type": "string" }, "merchantCountry": { "type": "string" } }, "required": [ "externalId", "status" ] }, "UploadPurposeSchema": { "type": "string" }, "UploadReceiptRequestSchema": { "type": "object", "properties": { "receiptKey": { "type": "string", "minLength": 1, "description": "R2 file key for the receipt" } }, "required": [ "receiptKey" ] }, "UploadReceiptResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ] }, "UserIdSchema": { "type": "string", "pattern": "^user_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "UserParamsSchema": { "type": "object", "properties": { "userId": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Unique identifier for the authenticated user" } }, "required": [ "userId" ], "description": "Path parameters for user endpoints" }, "UserProfileDetailsSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the user profile record" }, "userId": { "type": "string", "description": "Identifier linking the profile to its owning user" }, "firstName": { "type": [ "string", "null" ], "description": "Employee first name" }, "lastName": { "type": [ "string", "null" ], "description": "Employee last name" }, "dob": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of birth" }, "sex": { "allOf": [ { "$ref": "#/components/schemas/SexSchema" } ], "nullable": true }, "addressLine1": { "type": [ "string", "null" ], "description": "Residential address first line" }, "addressLine2": { "type": [ "string", "null" ], "description": "Residential address second line" }, "city": { "type": [ "string", "null" ], "description": "City for residential address" }, "state": { "type": [ "string", "null" ], "description": "State abbreviation" }, "zip": { "type": [ "string", "null" ], "description": "Postal ZIP code" }, "country": { "type": [ "string", "null" ], "description": "Country code" }, "timeZone": { "type": [ "string", "null" ], "description": "Preferred time zone identifier" }, "unitSystem": { "description": "Preferred measurement unit system", "allOf": [ { "$ref": "#/components/schemas/UnitSystemSchema" } ], "nullable": true }, "enrollmentTier": { "description": "Employee enrollment tier for health plan coverage", "allOf": [ { "$ref": "#/components/schemas/EnrollmentTierSchema" } ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the profile record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the profile record's latest update" } }, "required": [ "id", "userId", "firstName", "lastName", "dob", "sex", "addressLine1", "addressLine2", "city", "state", "zip", "country", "timeZone", "unitSystem", "enrollmentTier", "createdAt", "updatedAt" ], "description": "Detailed profile data for a member" }, "UserProfileIdSchema": { "type": "string", "pattern": "^user_profile_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "UserProfileParamsSchema": { "type": "object", "properties": { "userId": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Unique identifier for the authenticated user" } }, "required": [ "userId" ], "description": "Path parameters for the user profile endpoint" }, "UserProfileResponseSchema": { "type": "object", "properties": { "profile": { "allOf": [ { "$ref": "#/components/schemas/UserProfileSchema" } ], "nullable": true } }, "required": [ "profile" ], "description": "Successful profile response payload" }, "UserProfileSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": [ "string", "null" ], "description": "Display name for the user" }, "email": { "type": "string", "format": "email", "description": "Primary email address" }, "image": { "type": [ "string", "null" ], "description": "Profile image URL" }, "role": { "type": [ "string", "null" ], "description": "Role assigned within the organization" }, "phoneNumber": { "type": [ "string", "null" ], "description": "Verified phone number in E.164 format" }, "profile": { "allOf": [ { "$ref": "#/components/schemas/UserProfileDetailsSchema" } ], "nullable": true } }, "required": [ "id", "name", "email", "image", "role", "phoneNumber", "profile" ], "description": "User profile record" }, "UserProfileUpdateSchema": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "minLength": 1, "description": "Employee first name" }, "lastName": { "type": [ "string", "null" ], "minLength": 1, "description": "Employee last name" }, "dob": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of birth" }, "sex": { "allOf": [ { "$ref": "#/components/schemas/SexSchema" } ], "nullable": true }, "timeZone": { "type": [ "string", "null" ], "minLength": 1, "description": "Preferred time zone identifier" }, "unitSystem": { "description": "Preferred measurement unit system", "allOf": [ { "$ref": "#/components/schemas/UnitSystemSchema" } ], "nullable": true }, "enrollmentTier": { "description": "Employee enrollment tier for health plan coverage", "allOf": [ { "$ref": "#/components/schemas/EnrollmentTierSchema" } ], "nullable": true } }, "additionalProperties": false, "description": "Payload for updating a user profile" }, "UserResponseSchema": { "type": "object", "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/UserSchema" } ], "description": "Complete user record with profile data" } }, "required": [ "user" ], "description": "Full user response payload" }, "UserSchema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "description": "Unique user identifier", "pattern": "^user_[A-Za-z0-9]{24,32}$" }, "created": { "type": "integer" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "Display name for the user" }, "email": { "type": "string", "format": "email", "description": "Primary email address" }, "email_verified": { "type": "boolean", "description": "Whether the user's email address has been verified" }, "emailVerified": { "type": "boolean", "description": "Whether the user's email address has been verified" }, "image": { "type": [ "string", "null" ], "description": "Profile image URL" }, "role": { "type": [ "string", "null" ], "description": "Role assigned within the organization" }, "phoneNumber": { "type": [ "string", "null" ], "description": "Verified phone number in E.164 format" }, "phone_number": { "type": [ "string", "null" ], "description": "Verified phone number in E.164 format" }, "user_type": { "allOf": [ { "$ref": "#/components/schemas/UserTypeSchema" } ], "description": "Resolved user type for the session" }, "userType": { "allOf": [ { "$ref": "#/components/schemas/UserTypeSchema" } ], "description": "Resolved user type for the session" }, "organization": { "description": "Active organization for the session (null when none)", "allOf": [ { "$ref": "#/components/schemas/OrganizationContextSchema" } ], "nullable": true }, "onboarding_step": { "allOf": [ { "$ref": "#/components/schemas/OnboardingStepSchema" } ], "description": "Current onboarding step for the user" }, "onboardingStep": { "allOf": [ { "$ref": "#/components/schemas/OnboardingStepSchema" } ], "description": "Current onboarding step for the user" }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp for onboarding completion" }, "onboardingCompletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp for onboarding completion" }, "onboarding_checklist": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingChecklistCanonicalItemSchema" }, "minItems": 16, "maxItems": 16, "description": "Organization-scoped onboarding checklist" }, "onboardingChecklist": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingChecklistItemSchema" }, "minItems": 16, "maxItems": 16, "description": "Organization-scoped onboarding checklist" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the user record was created" }, "updated_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the user record was last updated" }, "profile": { "description": "Detailed profile data for the member", "allOf": [ { "$ref": "#/components/schemas/UserProfileDetailsSchema" } ], "nullable": true } }, "required": [ "object", "id", "created", "livemode", "metadata", "name", "email", "email_verified", "emailVerified", "image", "role", "phoneNumber", "phone_number", "user_type", "userType", "organization", "onboarding_step", "onboardingStep", "onboarding_completed_at", "onboardingCompletedAt", "createdAt", "updated_at", "updatedAt", "profile" ], "description": "User record including profile details" }, "UserTypeSchema": { "type": "string", "enum": [ "MEMBER", "DEPENDENT_ADULT", "DEPENDENT_MINOR" ], "description": "Classification of the authenticated user" }, "UserUpdateSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name for the user" }, "image": { "type": [ "string", "null" ], "minLength": 1, "description": "Profile image URL" }, "onboardingStep": { "allOf": [ { "$ref": "#/components/schemas/OnboardingStepSchema" } ] }, "onboardingCompletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "First onboarding completion timestamp; later non-null retries preserve the first value, while clearing it returns a conflict" }, "onboardingChecklist": { "allOf": [ { "$ref": "#/components/schemas/OnboardingChecklistPatchSchema" } ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ApiMetadataSchema" } ] } }, "description": "Payload for updating user-level attributes" }, "VerificationIdSchema": { "type": "string", "pattern": "^verification_[A-Za-z0-9]{24,32}$", "maxLength": 255 }, "VerifyOtpRequestSchema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "pattern": "^\\+1\\d{10}$", "description": "Phone number in E.164 format (+1XXXXXXXXXX)" }, "code": { "type": "string", "minLength": 6, "maxLength": 6, "description": "6-digit OTP code" } }, "required": [ "phoneNumber", "code" ], "description": "Request to verify a phone number with an OTP code" }, "VerifyOtpResponseSchema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Whether verification succeeded" }, "phoneNumber": { "type": "string", "description": "The verified phone number" }, "phoneNumberVerified": { "type": "boolean", "description": "Whether the phone number is now verified" } }, "required": [ "status", "phoneNumber", "phoneNumberVerified" ], "description": "Phone number verification result" }, "WearableConnectionSchema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "connected": { "type": "boolean" }, "needsReconnect": { "type": "boolean", "description": "Linked, but the grant predates the current scope list. Reading data will fail until the member reconnects." }, "grantedScopes": { "type": "array", "items": { "type": "string" } }, "missingScopes": { "type": "array", "items": { "type": "string" } }, "requestedScopes": { "type": "array", "items": { "type": "string" } }, "scopesKnown": { "type": "boolean", "description": "False when the provider recorded no scope list. The grant may be complete; it cannot be verified." }, "connectUrl": { "type": "string" }, "reason": { "type": [ "string", "null" ], "enum": [ "not_connected", "not_configured", "provider_unauthorized", "unavailable", null ], "description": "`unavailable` means Rivendell could not answer, not that the member's grant is broken. Do not prompt a reconnect for it. `not_configured` means the provider is switched off for this deployment, so connecting is impossible until an operator adds credentials." }, "message": { "type": [ "string", "null" ] } }, "required": [ "provider", "connected", "needsReconnect", "grantedScopes", "missingScopes", "requestedScopes", "scopesKnown", "connectUrl", "reason", "message" ] }, "WearableConnectionsResponseSchema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/WearableConnectionSchema" } }, "anyConnected": { "type": "boolean" } }, "required": [ "connections", "anyConnected" ] }, "WearableProfileSchema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "heightMeters": { "$ref": "#/components/schemas/nullableNumber" }, "weightKilograms": { "$ref": "#/components/schemas/nullableNumber" }, "maxHeartRate": { "$ref": "#/components/schemas/nullableNumber" }, "age": { "$ref": "#/components/schemas/nullableNumber" }, "biologicalSex": { "type": [ "string", "null" ] } }, "required": [ "provider", "heightMeters", "weightKilograms", "maxHeartRate", "age", "biologicalSex" ] }, "WearableProfilesResponseSchema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/WearableProfileSchema" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/WearableProviderOutcomeSchema" } } }, "required": [ "profiles", "providers" ] }, "WearableProviderOutcomeSchema": { "type": "object", "discriminator": { "propertyName": "status" }, "oneOf": [ { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "status": { "type": "string", "enum": [ "ok" ] }, "recordCount": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean", "description": "The window held more pages than one request may walk. Narrow the range to see the rest." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/WearableWarningSchema" }, "description": "Partial failures inside a successful read. The listed fields are null because a secondary call failed, not because the device recorded nothing." } }, "required": [ "provider", "status", "recordCount", "truncated", "warnings" ] }, { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "status": { "type": "string", "enum": [ "unavailable" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "recoveryHint": { "type": "string", "enum": [ "RETRY_LATER", "REQUIRES_USER_ACTION", "UNRECOVERABLE" ] }, "missingScopes": { "type": "array", "items": { "type": "string" } }, "retryAfterSeconds": { "type": [ "integer", "null" ] }, "connectUrl": { "type": [ "string", "null" ] } }, "required": [ "provider", "status", "code", "message", "recoveryHint", "missingScopes", "retryAfterSeconds", "connectUrl" ] } ] }, "WearableProviderSchema": { "type": "string" }, "WearableRangeQueryShape": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected." }, "startDate": { "type": "string", "format": "date", "description": "Explicit range start (YYYY-MM-DD). Requires endDate." }, "endDate": { "type": "string", "format": "date", "description": "Explicit range end (YYYY-MM-DD). Requires startDate." }, "includeRaw": { "type": "string", "enum": [ "true", "false" ], "description": "Include the untouched provider payload on each record. Roughly triples the response." } } }, "WearableRangeSchema": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" } }, "required": [ "startDate", "endDate" ] }, "WearableWarningSchema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "affectedFields": { "type": "array", "items": { "type": "string" }, "description": "Normalized fields that are null because this call failed." }, "missingScopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "affectedFields", "missingScopes" ] }, "WorkoutSchema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/WearableProviderSchema" }, "id": { "type": "string" }, "day": { "type": "string" }, "sport": { "type": [ "string", "null" ] }, "start": { "type": "string" }, "end": { "type": "string" }, "durationMinutes": { "$ref": "#/components/schemas/nullableNumber" }, "calories": { "$ref": "#/components/schemas/nullableNumber" }, "distanceMeters": { "$ref": "#/components/schemas/nullableNumber" }, "strain": { "$ref": "#/components/schemas/nullableNumber" }, "averageHeartRate": { "$ref": "#/components/schemas/nullableNumber" }, "maxHeartRate": { "$ref": "#/components/schemas/nullableNumber" }, "intensity": { "type": [ "string", "null" ] }, "raw": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" }, "description": "The untouched provider payload. Present only when includeRaw=true." } }, "required": [ "provider", "id", "day", "sport", "start", "end", "durationMinutes", "calories", "distanceMeters", "strain", "averageHeartRate", "maxHeartRate", "intensity" ] }, "WorkoutsResponseSchema": { "type": "object", "properties": { "range": { "$ref": "#/components/schemas/WearableRangeSchema" }, "workouts": { "type": "array", "items": { "$ref": "#/components/schemas/WorkoutSchema" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/WearableProviderOutcomeSchema" } }, "noConnections": { "type": "boolean", "description": "No wearable is linked to this account at all." }, "continueWith": { "description": "Present when the upstream page budget ran out before the window did. Pass these dates back to fetch the older records that were cut.", "allOf": [ { "$ref": "#/components/schemas/WearableRangeSchema" } ], "nullable": true } }, "required": [ "range", "workouts", "providers", "noConnections", "continueWith" ] } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "Invalid request parameters" ] }, "code": { "type": "string", "examples": [ "400" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "Authentication required" ] }, "code": { "type": "string", "examples": [ "401" ] } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "Access denied" ] }, "code": { "type": "string", "examples": [ "403" ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "Resource not found" ] }, "code": { "type": "string", "examples": [ "404" ] } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "Resource already exists" ] }, "code": { "type": "string", "examples": [ "409" ] } } } } } }, "410": { "description": "Gone", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "This endpoint has been retired" ] }, "code": { "type": "string", "examples": [ "410" ] } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "Rate limit exceeded" ] }, "code": { "type": "string", "examples": [ "429" ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "An unexpected error occurred" ] }, "code": { "type": "string", "examples": [ "500" ] } } } } } } } }, "paths": { "/sign-in-email": { "get": { "operationId": "get-sign-in-email", "summary": "Get sign-in email status.", "description": "Returns the current user's sign-in email and verification status.", "tags": [ "account" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInEmailResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/account/deletion": { "post": { "operationId": "post-account-deletion", "summary": "Initiate account deletion.", "description": "Records an auditable account-deletion request, closes interactive and API access immediately, and preserves plan, HSA, financial, insurance, security, audit, and legal records that cannot be deleted with the login identity.", "tags": [ "account" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/accounts": { "post": { "operationId": "post-accounts", "summary": "Create a new Increase account for the user's active organization.", "description": "Creates a new bank account in Increase and links it to the user's active organization.", "tags": [ "accounts" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountErrorSchema" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountErrorSchema" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountErrorSchema" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountErrorSchema" } } } } } } }, "/admin/clinical-gates": { "post": { "operationId": "post-admin-clinical-gates", "summary": "POST /api/admin/clinical-gates", "description": "Global support-only endpoint for recording a member's T2D GLP-1 coverage gate.", "tags": [ "admin" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClinicalGateRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClinicalGateResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/merchant-rules": { "get": { "operationId": "get-admin-merchant-rules", "summary": "GET /api/admin/merchant-rules", "description": "List all merchant rules for admin management", "tags": [ "admin" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantRuleListResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-admin-merchant-rules", "summary": "POST /api/admin/merchant-rules", "description": "Create a global merchant rule for RTD auto-approval", "tags": [ "admin" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRuleSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRuleResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/pre-auths": { "post": { "operationId": "post-admin-pre-auths", "summary": "POST /api/admin/pre-auths", "description": "Admin-only endpoint to create pre-authorizations for MCCs/vendors or category-only approvals.", "tags": [ "admin" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePreAuthorizationRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePreAuthorizationResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/resubstantiate": { "post": { "operationId": "post-admin-claims-resubstantiate", "summary": "POST /api/admin/claims/resubstantiate", "description": "Re-check auto-substantiation for an org's pending card claims", "tags": [ "admin" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResubstantiateOrgRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResubstantiateOrgResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/merchant-rules/{id}": { "patch": { "operationId": "patch-admin-merchant-rules-{id}", "summary": "PATCH /api/admin/merchant-rules/[id]", "description": "Update a global merchant rule", "tags": [ "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/MerchantRuleIdSchema" } ], "description": "Merchant rule ID" }, "description": "Merchant rule ID", "example": "merchant_rule_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantRuleSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantRuleResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-admin-merchant-rules-{id}", "summary": "DELETE /api/admin/merchant-rules/[id]", "description": "Delete a global merchant rule", "tags": [ "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/MerchantRuleIdSchema" } ], "description": "Merchant rule ID" }, "description": "Merchant rule ID", "example": "merchant_rule_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMerchantRuleResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/clinical-gates/{id}/end": { "post": { "operationId": "post-admin-clinical-gates-{id}-end", "summary": "POST /api/admin/clinical-gates/[id]/end", "description": "", "tags": [ "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClinicalGateRecordIdSchema" } ], "description": "Clinical gate record ID" }, "description": "Clinical gate record ID", "example": "clinical_gate_record_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndClinicalGateRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndClinicalGateResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/pre-auths/{id}/approve": { "post": { "operationId": "post-admin-pre-auths-{id}-approve", "summary": "POST /api/admin/pre-auths/[id]/approve", "description": "", "tags": [ "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationIdSchema" } ], "description": "Pre-authorization ID" }, "description": "Pre-authorization ID", "example": "pre_authorization_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovePreAuthorizationRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovePreAuthorizationResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/pre-auths/{id}/cancel": { "post": { "operationId": "post-admin-pre-auths-{id}-cancel", "summary": "POST /api/admin/pre-auths/[id]/cancel", "description": "", "tags": [ "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationIdSchema" } ], "description": "Pre-authorization ID" }, "description": "Pre-authorization ID", "example": "pre_authorization_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPreAuthorizationResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPreAuthorizationResponseSchema" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/pre-auths/{id}/reject": { "post": { "operationId": "post-admin-pre-auths-{id}-reject", "summary": "POST /api/admin/pre-auths/[id]/reject", "description": "", "tags": [ "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/PreAuthorizationIdSchema" } ], "description": "Pre-authorization ID" }, "description": "Pre-authorization ID", "example": "pre_authorization_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectPreAuthorizationResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectPreAuthorizationResponseSchema" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/assistant/threads": { "get": { "operationId": "get-assistant-threads", "summary": "GET /api/assistant/threads", "description": "List the member's Ask Rivendell threads, most recently active first. Message bodies come from GET /api/assistant/threads/{threadId}; sending a message is POST /api/assistant/messages (SSE, outside this spec).", "tags": [ "assistant" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Max number of threads to return", "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "description": "Max number of threads to return", "example": 1 }, { "in": "query", "name": "offset", "required": false, "schema": { "description": "Offset for pagination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Offset for pagination", "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantThreadsListResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/assistant/threads/{threadId}": { "get": { "operationId": "get-assistant-threads-{threadId}", "summary": "GET /api/assistant/threads/[threadId]", "description": "The most recent 200 messages of one Ask Rivendell thread, oldest first. `role` is MEMBER, ASSISTANT, or HUMAN_AGENT — HUMAN_AGENT is reserved for future care-team replies and is not yet emitted; today support runs through support@rivendell.health.", "tags": [ "assistant" ], "parameters": [ { "in": "path", "name": "threadId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/AssistantThreadIdSchema" } ], "description": "Assistant thread ID" }, "description": "Assistant thread ID", "example": "assistant_thread_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantThreadDetailsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } }, "/banking/accounts": { "get": { "operationId": "get-banking-accounts", "summary": "GET /api/banking/accounts", "description": "Returns bank accounts linked to the authenticated user.", "tags": [ "banking" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountListResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-banking-accounts", "summary": "POST /api/banking/accounts", "description": "Links a personal bank account via manual entry.", "tags": [ "banking" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualBankAccountCreateSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualBankAccountCreateResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/banking/link": { "post": { "operationId": "post-banking-link", "summary": "POST /api/banking/link", "description": "Links a bank account via Stripe Financial Connections and stores it for the user or org.", "tags": [ "banking" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBankAccountRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBankAccountResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/banking/link-token": { "post": { "operationId": "post-banking-link-token", "summary": "POST /api/banking/link-token", "description": "Creates a Stripe Financial Connections Session for a user or organization bank link flow.", "tags": [ "banking" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankLinkTokenRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankLinkTokenResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/banking/set-primary": { "post": { "operationId": "post-banking-set-primary", "summary": "POST /api/banking/set-primary", "description": "Marks a bank account as the primary account for the specified owner.", "tags": [ "banking" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPrimaryBankAccountRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPrimaryBankAccountResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/banking/accounts/{bankAccountId}": { "delete": { "operationId": "delete-banking-accounts-{bankAccountId}", "summary": "DELETE /api/banking/accounts/[bankAccountId]", "description": "Deletes a linked personal bank account. If it was primary, another account becomes primary.", "tags": [ "banking" ], "parameters": [ { "in": "path", "name": "bankAccountId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/BankAccountIdSchema" } ], "description": "Bank account ID" }, "description": "Bank account ID", "example": "bank_account_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountDeleteResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/benefits/assistant": { "post": { "operationId": "post-benefits-assistant", "summary": "Public benefits chatbot for the shared Rivendell benefits explainer.", "description": "Answers questions about the standard Rivendell benefits experience using a public, non-personalized assistant.", "tags": [ "benefits" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenefitsAssistantRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenefitsAssistantResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/capabilities": { "get": { "operationId": "get-capabilities", "summary": "GET /api/capabilities", "description": "Public machine-readable discovery document for agents. Read this before long docs to find OpenAPI, llms.txt, MCP, auth modes, ID rules, list and error envelopes, idempotency, sandbox support, and resource summaries.", "tags": [ "capabilities" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCapabilitiesSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } } }, "/card-activity": { "get": { "operationId": "get-card-activity", "summary": "GET /api/card-activity", "description": "Returns the authenticated user's card authorization history with cursor-based pagination.", "tags": [ "cards" ], "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor for pagination" }, "description": "Opaque cursor for pagination", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Max number of items to return (default 20)", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "description": "Max number of items to return (default 20)", "example": 1 }, { "in": "query", "name": "decision", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/DecisionSchema" } ], "description": "Filter by decision (approve or decline)" }, "description": "Filter by decision (approve or decline)", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardActivityResponseSchema" }, "examples": { "list_card_activity": { "summary": "List card activity", "value": { "object": "list", "data": [ { "object": "transaction", "id": "transaction_aaaaaaaaaaaaaaaaaaaaaaaa", "created": 1775001600, "livemode": true, "metadata": {}, "merchant_name": "Market Street Pharmacy", "authorized_amount": 3200, "status": "SETTLED" } ], "has_more": false, "url": "/api/card-activity" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/cards": { "get": { "operationId": "get-cards", "summary": "List all cards for the authenticated user.", "description": "Returns all cards belonging to the authenticated user with fresh data from the card provider. Optionally filter by status.", "tags": [ "cards" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "CANCELED" ], "description": "Filter cards by status (ACTIVE, DISABLED, CANCELED)" }, "description": "Filter cards by status (ACTIVE, DISABLED, CANCELED)", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCardsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardErrorSchema" } } } } } }, "post": { "operationId": "post-cards", "summary": "Create a new card for the authenticated user.", "description": "Issues a claims card using the organization's banking account, or returns the authenticated member's existing non-canceled claims card for that organization.", "tags": [ "cards" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardErrorSchema" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardErrorSchema" } } } }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardErrorSchema" } } } } } } }, "/cards/{cardId}": { "get": { "operationId": "get-cards-{cardId}", "summary": "Fetch card details.", "description": "Returns the full card object for the specified card ID. Only returns cards owned by the authenticated user.", "tags": [ "cards" ], "parameters": [ { "in": "path", "name": "cardId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/IncreaseCardIdSchema" } ], "description": "Increase card identifier" }, "description": "Increase card identifier", "example": "card_aaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardErrorSchema" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardErrorSchema" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardErrorSchema" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardErrorSchema" } } } } } } }, "/cards/hsa": { "post": { "operationId": "post-cards-hsa", "summary": "Issue or retrieve the authenticated member's HSA card.", "description": "Returns one card funded directly by the member-owned HSA. No active organization or plan enrollment is required.", "tags": [ "cards" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsaCardResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/cards/{cardId}/details": { "get": { "operationId": "get-cards-{cardId}-details", "summary": "Fetch sensitive card details.", "description": "Returns sensitive card information including full card number, CVV, and PIN. Only returns details for cards owned by the authenticated user.", "tags": [ "cards" ], "parameters": [ { "in": "path", "name": "cardId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/IncreaseCardIdSchema" } ], "description": "Increase card identifier" }, "description": "Increase card identifier", "example": "card_aaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsErrorSchema" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsErrorSchema" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsErrorSchema" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsErrorSchema" } } } } } } }, "/cards/{cardId}/push-provision": { "post": { "operationId": "post-cards-{cardId}-push-provision", "summary": "Push-provision a card for Apple Pay (Add to Apple Wallet).", "description": "Relays Apple's provisioning payload to Increase and returns encrypted pass data for PassKit.", "tags": [ "cards" ], "parameters": [ { "in": "path", "name": "cardId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/IncreaseCardIdSchema" } ], "description": "Increase card identifier" }, "description": "Increase card identifier", "example": "card_aaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushProvisionRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushProvisionResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushProvisionErrorSchema" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushProvisionErrorSchema" } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushProvisionErrorSchema" } } } }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushProvisionErrorSchema" } } } } } } }, "/cards/{cardId}/status": { "patch": { "operationId": "patch-cards-{cardId}-status", "summary": "Update card status (freeze/unfreeze).", "description": "Updates the card status in Increase and syncs the local card record.", "tags": [ "cards" ], "parameters": [ { "in": "path", "name": "cardId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/IncreaseCardIdSchema" } ], "description": "Increase card identifier" }, "description": "Increase card identifier", "example": "card_aaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStatusUpdateRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStatusUpdateResponseSchema" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStatusUpdateErrorSchema" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStatusUpdateErrorSchema" } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStatusUpdateErrorSchema" } } } }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStatusUpdateErrorSchema" } } } } } } }, "/cards/{cardId}/step-up": { "post": { "operationId": "post-cards-{cardId}-step-up", "summary": "Mint a step-up grant for revealing sensitive card details.", "description": "Issues a short-lived (5 minute), single-use grant required by GET /cards/{cardId}/details. Call this immediately after local biometric confirmation; each grant authorizes exactly one details read, minting is rate limited, and every grant is audit-logged.", "tags": [ "cards" ], "parameters": [ { "in": "path", "name": "cardId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/IncreaseCardIdSchema" } ], "description": "Increase card identifier" }, "description": "Increase card identifier", "example": "card_aaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardStepUpResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/cards/hsa/transactions": { "get": { "operationId": "get-cards-hsa-transactions", "summary": "Compatibility alias for the member HSA transaction statement.", "description": "Returns the same reconciled HSA statement as GET /api/funding/transactions. New clients should use the canonical funding route.", "tags": [ "cards" ], "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor for pagination" }, "description": "Opaque cursor for pagination", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsaTransactionsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/care/procedure-requests": { "post": { "operationId": "post-care-procedure-requests", "summary": "Submit an expensive-procedure negotiation request.", "description": "Creates a member-owned procedure request in the existing operations appointment queue. This does not book a procedure.", "tags": [ "care" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProcedureRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcedureRequestResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/census/entry": { "get": { "operationId": "get-census-entry", "summary": "GET /api/census/entry", "description": "Returns census data tied to the authenticated employee.", "tags": [ "census" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CensusEntryResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/census/upload": { "post": { "operationId": "post-census-upload", "summary": "Upload a census file for downstream AI analysis.", "description": "Stores the uploaded file in Cloudflare R2 and returns a short-lived signed URL.", "tags": [ "census" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CensusUploadFormDataSchema" }, "encoding": { "file": { "contentType": "application/octet-stream" } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CensusUploadResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/census/dependents/{dependentId}": { "patch": { "operationId": "patch-census-dependents-{dependentId}", "summary": "Update a dependent email address.", "description": "Allows the employee to update the dependent's email before activation.", "tags": [ "census" ], "parameters": [ { "in": "path", "name": "dependentId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DependentIdSchema" } ], "description": "Dependent census entry ID" }, "description": "Dependent census entry ID", "example": "dependent_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDependentSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDependentResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/census/dependents/{dependentId}/invite": { "post": { "operationId": "post-census-dependents-{dependentId}-invite", "summary": "Resend a dependent invite email.", "description": "Sends a magic link invite to an adult dependent with an email on file.", "tags": [ "census" ], "parameters": [ { "in": "path", "name": "dependentId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DependentIdSchema" } ], "description": "Dependent census entry ID" }, "description": "Dependent census entry ID", "example": "dependent_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DependentInviteResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims": { "get": { "operationId": "get-claims", "summary": "GET /api/claims", "description": "Returns the authenticated user's claims with optional filtering.", "tags": [ "claims" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "description": "Comma-separated claim statuses (e.g. SUBMITTED,APPROVED)" }, "description": "Comma-separated claim statuses (e.g. SUBMITTED,APPROVED)", "example": "example" }, { "in": "query", "name": "source", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimSourceSchema" } ], "description": "Claim source filter" }, "description": "Claim source filter", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Max number of claims to return", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "description": "Max number of claims to return", "example": 1 }, { "in": "query", "name": "offset", "required": false, "schema": { "description": "Offset for pagination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Offset for pagination", "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimsListResponseSchema" }, "examples": { "list_claims": { "summary": "List claims response", "value": { "object": "list", "data": [ { "object": "claim", "id": "claim_aaaaaaaaaaaaaaaaaaaaaaaa", "created": 1775001600, "livemode": true, "metadata": {}, "source": "REIMBURSEMENT", "status": "SUBMITTED", "category": "VISION", "submitted_amount": 4250, "service_date": 1775001600, "merchant_name": "Market Street Vision", "description": "Eye exam" } ], "has_more": false, "url": "/api/claims" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}": { "get": { "operationId": "get-claims-{id}", "summary": "GET /api/claims/[id]", "description": "Get detailed information about a specific claim. Includes `memberInvoiceSummary` for inline invoice status. Swift: render inline invoice state from `memberInvoiceSummary`, then call `GET /api/claims/{id}/invoice` only when the user opens detailed invoice parsing results.", "tags": [ "claims" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimDetailsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/reimbursement": { "post": { "operationId": "post-claims-reimbursement", "summary": "POST /api/claims/reimbursement", "description": "Create a reimbursement claim for expenses the user has paid out of pocket. Swift: create the reimbursement claim first, then upload the invoice file and call `POST /api/claims/{id}/invoice` to attach and parse it.", "tags": [ "claims" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReimbursementClaimRequestSchema" }, "examples": { "create_reimbursement_claim": { "summary": "Create a reimbursement claim", "value": { "service_category": "VISION", "submitted_amount": 4250, "service_date": "2026-04-01", "merchant_name": "Market Street Vision", "description": "Eye exam", "metadata": { "external_id": "claim-042" } } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReimbursementClaimResponseSchema" }, "examples": { "created_reimbursement_claim": { "summary": "Created reimbursement claim", "value": { "success": true, "claim_id": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}/invoice": { "get": { "operationId": "get-claims-{id}-invoice", "summary": "GET /api/claims/[id]/invoice", "description": "Returns parsed member invoice metadata and line items for polling the invoice parse workflow. Swift: poll after `POST /api/claims/{id}/invoice` until `parseStatus` reaches `SUCCESS`, `PARTIAL`, or `FAILED`. `PARTIAL` can still contain usable line items. `FAILED` means the file is attached but structured extraction was not usable.", "tags": [ "claims" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimInvoiceStatusResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-claims-{id}-invoice", "summary": "POST /api/claims/[id]/invoice", "description": "Attach a member invoice to an existing claim, immediately substantiate the claim, and enqueue invoice parsing. Reimbursement claims in `DRAFT`, `SUBMITTED`, and `IN_REVIEW` are eligible. Swift: create the reimbursement claim first, upload the invoice with `purpose=\"member-invoices\"`, call this endpoint with `{ receiptKey, doctorId }`, and treat `202` + `parseStatus=\"PENDING\"` as enqueue success rather than parse completion.", "tags": [ "claims" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimInvoiceRequestSchema" } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimInvoiceResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}/payment-proposal": { "get": { "operationId": "get-claims-{id}-payment-proposal", "summary": "GET /api/claims/[id]/payment-proposal", "description": "Returns the exact remaining member responsibility and currently executable payment sources. HSA and linked-bank ACH are offered only when their server-side requirements pass. CARD remains unavailable until a processor can settle proceeds into the claims account.", "tags": [ "claims", "funding" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentProposalResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}/upload": { "post": { "operationId": "post-claims-{id}-upload", "summary": "POST /api/claims/[id]/upload", "description": "Upload a receipt to substantiate a claim.", "tags": [ "claims" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadReceiptRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadReceiptResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/invoice/preview": { "post": { "operationId": "post-claims-invoice-preview", "summary": "POST /api/claims/invoice/preview", "description": "Uses Reducto to extract invoice fields for claim prefills.", "tags": [ "claims" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePreviewRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePreviewResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/adjudicate": { "post": { "operationId": "post-admin-claims-{id}-adjudicate", "summary": "POST /api/admin/claims/[id]/adjudicate", "description": "Approve or reject a claim. Approval triggers adjudication to calculate coverage.", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjudicateClaimRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjudicateClaimResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/invoice": { "post": { "operationId": "post-admin-claims-{id}-invoice", "summary": "POST /api/admin/claims/[id]/invoice", "description": "Support-only endpoint for attaching and parsing a member invoice on behalf of a claim owner. Validates `ownerUserId`, the claim owner, and the `member-invoices/{ownerUserId}/...` file path before enqueueing the shared invoice parse workflow.", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminClaimInvoiceRequestSchema" } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminClaimInvoiceResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/preview-coverage": { "post": { "operationId": "post-admin-claims-{id}-preview-coverage", "summary": "POST /api/admin/claims/[id]/preview-coverage", "description": "Read-only coverage preview. Accepts optional category override.", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewCoverageRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewCoverageResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/readjudicate": { "post": { "operationId": "post-admin-claims-{id}-readjudicate", "summary": "POST /api/admin/claims/[id]/readjudicate", "description": "Freezes a corrected final adjudication only after a posted provider refund or settlement adjustment. Rebuilds accumulator projections and immediately starts any source-matched member refund.", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadjudicateClaimRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadjudicateClaimResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/receipt": { "post": { "operationId": "post-admin-claims-{id}-receipt", "summary": "POST /api/admin/claims/[id]/receipt", "description": "Support-only endpoint for attaching a private receipt to a claim. A receipt substantiates a card claim that is pending documentation and moves it to the review queue. Replacements on claims in any other status only update documentation.", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminClaimReceiptRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminClaimReceiptResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/resubstantiate": { "post": { "operationId": "post-admin-claims-{id}-resubstantiate", "summary": "POST /api/admin/claims/[id]/resubstantiate", "description": "Re-check auto-substantiation for a pending card claim", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResubstantiateClaimResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/admin/claims/{id}/update-category": { "post": { "operationId": "post-admin-claims-{id}-update-category", "summary": "POST /api/admin/claims/[id]/update-category", "description": "Update claim category before adjudication.", "tags": [ "claims", "admin" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCategoryRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCategoryResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}/payment-proposal/cancel": { "post": { "operationId": "post-claims-{id}-payment-proposal-cancel", "summary": "POST /api/claims/[id]/payment-proposal/cancel", "description": "Cancels an unexecuted member-action or scheduled claim payment. A processing or completed transfer cannot be canceled through this endpoint.", "tags": [ "claims", "funding" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelClaimPaymentRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentProposalResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}/payment-proposal/confirm": { "post": { "operationId": "post-claims-{id}-payment-proposal-confirm", "summary": "POST /api/claims/[id]/payment-proposal/confirm", "description": "Confirms the exact proposal amount from one selected source. Requires Idempotency-Key, a single-use claim-payment step-up grant, and explicit consent. HSA and bank payments settle into the organization claims account. Partial payments are not accepted.", "tags": [ "claims", "funding" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmClaimPaymentRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentProposalResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/claims/{id}/payment-proposal/step-up": { "post": { "operationId": "post-claims-{id}-payment-proposal-step-up", "summary": "POST /api/claims/[id]/payment-proposal/step-up", "description": "Mints a five-minute, single-use grant for confirming payment of this claim. Call immediately after the app's recent-confirmation step.", "tags": [ "claims", "funding" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ClaimIdSchema" } ], "description": "Claim ID" }, "description": "Claim ID", "example": "claim_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentStepUpResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/doctors/appointments": { "get": { "operationId": "get-doctors-appointments", "summary": "List appointments and in-flight scheduling jobs.", "description": "Returns upcoming appointments and scheduling jobs by default; use scope=past or scope=all to change the window.", "tags": [ "doctors" ], "parameters": [ { "in": "query", "name": "scope", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/AppointmentScopeSchema" } ], "default": "upcoming", "description": "Which appointments to return: upcoming, past, or all." }, "description": "Which appointments to return: upcoming, past, or all.", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/doctors/insights": { "get": { "operationId": "get-doctors-insights", "summary": "Fetch review summaries and attributes for a list of doctors.", "description": "Returns cached review summaries and status. Use for polling.", "tags": [ "doctors" ], "parameters": [ { "in": "query", "name": "ids", "required": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DoctorIdSchema" }, "minItems": 1, "maxItems": 20, "description": "Doctor IDs to fetch insights for." }, "description": "Doctor IDs to fetch insights for.", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInsightsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } } }, "/doctors/schedule": { "post": { "operationId": "post-doctors-schedule", "summary": "Schedule doctors based on prior search results", "description": "Persist a scheduling request with doctor selections and availability", "tags": [ "doctors" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleDoctorsRequestSchema" }, "examples": { "book_or_request_appointment": { "summary": "Request appointment booking", "value": { "doctors": [ { "doctor_id": "doctor_aaaaaaaaaaaaaaaaaaaaaaaa", "visited_status": "no" } ], "location": { "zip_code": "94107" }, "specialty": "primary care", "care_type": "annual physical", "symptoms": [], "urgency": "routine", "visit_type": "inperson", "availability": [ { "date": "2026-05-01T00:00:00.000Z", "slots": [ { "start": "2026-05-01T17:00:00.000Z", "end": "2026-05-01T18:00:00.000Z" } ] } ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "nullable": false } }, "required": [ "id" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/doctors/search": { "post": { "operationId": "post-doctors-search", "summary": "Find doctors based on natural language criteria using Google Places API", "description": "Search for doctors using Google Places (Text Search)", "tags": [ "doctors" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindDoctorsRequestSchema" }, "examples": { "find_care_options": { "summary": "Find care options", "value": { "location": { "city": "San Francisco", "region": "CA", "country_code": "US", "postal_code": "94107" }, "specialty": "primary care", "care_type": "annual physical", "symptoms": [], "urgency": "routine", "visit_type": "inperson", "max_results": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindDoctorsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/doctors/suggest": { "get": { "operationId": "get-doctors-suggest", "summary": "GET /api/doctors/suggest", "description": "Returns doctor autocomplete suggestions from Google Places.", "tags": [ "doctors" ], "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Doctor name query for autocomplete" }, "description": "Doctor name query for autocomplete", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Maximum number of results to return", "type": "integer", "minimum": 1, "maximum": 20 }, "description": "Maximum number of results to return", "example": 1 }, { "in": "query", "name": "city", "required": false, "schema": { "type": "string", "minLength": 1, "description": "City for location bias" }, "description": "City for location bias", "example": "example" }, { "in": "query", "name": "region", "required": false, "schema": { "type": "string", "minLength": 1, "description": "State or region code for location bias" }, "description": "State or region code for location bias", "example": "example" }, { "in": "query", "name": "postalCode", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Postal or ZIP code for location bias" }, "description": "Postal or ZIP code for location bias", "example": "example" }, { "in": "query", "name": "countryCode", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code" }, "description": "ISO 3166-1 alpha-2 country code", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DoctorSuggestResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/doctors/appointments/{id}": { "get": { "operationId": "get-doctors-appointments-{id}", "summary": "Get one appointment or in-flight scheduling job.", "description": "Returns the authenticated member's appointment summary by ID.", "tags": [ "doctors" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DoctorAppointmentJobIdSchema" } ], "description": "Appointment ID" }, "description": "Appointment ID", "example": "doctor_appointment_job_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentSummarySchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-doctors-appointments-{id}", "summary": "Cancel an appointment.", "description": "Cancels a pending, in-progress, or booked appointment by setting its status to CANCELLED.", "tags": [ "doctors" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DoctorAppointmentJobIdSchema" } ], "description": "Appointment ID" }, "description": "Appointment ID", "example": "doctor_appointment_job_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCancelRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCancelResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-doctors-appointments-{id}", "summary": "Delete a failed appointment scheduling job.", "description": "Deletes a failed appointment job. Other states return a conflict until cancellation is supported.", "tags": [ "doctors" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DoctorAppointmentJobIdSchema" } ], "description": "Appointment ID" }, "description": "Appointment ID", "example": "doctor_appointment_job_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentDeleteResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/cleanup-pdf": { "delete": { "operationId": "delete-cleanup-pdf", "summary": "Delete a generated PDF file from the public directory.", "description": "Removes the specified file if it exists under /public/generated.", "tags": [ "files" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CleanupPdfResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/funding/transactions": { "get": { "operationId": "get-funding-transactions", "summary": "List the authenticated member's reconciled funding-account transactions.", "description": "Returns a newest-first, append-only HSA statement with signed amounts and full-history running balances. HRA history remains unavailable until its account and reimbursement rails exist.", "tags": [ "funding" ], "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor for pagination" }, "description": "Opaque cursor for pagination", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingTransactionsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/funding/hsa/payment-authorization": { "get": { "operationId": "get-funding-hsa-payment-authorization", "summary": "GET /api/funding/hsa/payment-authorization", "description": "Returns the authenticated member's effective claim-payment mode. With no saved authorization, the mode is ASK_EVERY_TIME. Automatic HSA payment always uses a 24-hour review window and stops when coverage ends.", "tags": [ "funding" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentAuthorizationResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } }, "put": { "operationId": "put-funding-hsa-payment-authorization", "summary": "PUT /api/funding/hsa/payment-authorization", "description": "Saves a new immutable claim-payment authorization version. AUTO_WITH_REVIEW_WINDOW is opt-in; ASK_EVERY_TIME is the default. Requires a recent claim-payment step-up grant.", "tags": [ "funding" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClaimPaymentAuthorizationRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentAuthorizationResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-funding-hsa-payment-authorization", "summary": "DELETE /api/funding/hsa/payment-authorization", "description": "Revokes automatic claim payments and cancels scheduled transfers that have not executed. Completed payments remain intact. Requires a recent claim-payment step-up grant.", "tags": [ "funding" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentAuthorizationResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/funding/hsa/payment-authorization/step-up": { "post": { "operationId": "post-funding-hsa-payment-authorization-step-up", "summary": "POST /api/funding/hsa/payment-authorization/step-up", "description": "Mints a five-minute, single-use grant for changing or revoking claim-payment authorization. Call immediately after the app's recent-confirmation step.", "tags": [ "funding" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPaymentStepUpResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/labs/extract": { "post": { "operationId": "post-labs-extract", "summary": "Triggers AI processing for a lab file that has already been uploaded to R2", "description": "Use after /api/upload/initiate to create a lab test record and trigger AI extraction for an already-uploaded file.", "tags": [ "labs" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractLabRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractLabResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/legal/acceptances": { "get": { "operationId": "get-legal-acceptances", "summary": "Read current legal acceptance status.", "description": "Returns whether the authenticated user and any covered minor children represented by that user have accepted the current terms and privacy versions.", "tags": [ "legal" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalAcceptanceStatusResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-legal-acceptances", "summary": "Record legal document acceptance.", "description": "Appends evidence that the authenticated user accepted an exact published terms or privacy version for themself or a covered minor child. The accepting actor and server timestamp are authoritative. Adult dependents accept for themselves. Personal access tokens and third-party OAuth credentials cannot record acceptance.", "tags": [ "legal" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLegalAcceptanceRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLegalAcceptanceResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/legal/documents": { "get": { "operationId": "get-legal-documents", "summary": "List the current legal documents.", "description": "Public version metadata for the terms and privacy documents shown before sign-in. Clients must submit these exact version identifiers when recording acceptance.", "tags": [ "legal" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalDocumentsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } } }, "/medical-history": { "get": { "operationId": "get-medical-history", "summary": "GET /api/medical-history", "description": "Returns the latest confirmed snapshot for the authenticated member.", "tags": [ "medical-history" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicalHistoryResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } }, "put": { "operationId": "put-medical-history", "summary": "PUT /api/medical-history", "description": "Saves confirmed medical history signals and raw input for audit.", "tags": [ "medical-history" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicalHistoryUpdateSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicalHistoryResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/medical-history/extract": { "post": { "operationId": "post-medical-history-extract", "summary": "POST /api/medical-history/extract", "description": "Uses Claude to normalize medications, conditions, major care, and accessibility needs.", "tags": [ "medical-history" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicalHistoryExtractRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicalHistoryExtractResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/medications/mine": { "get": { "operationId": "get-medications-mine", "summary": "List the authenticated member's medications.", "description": "Returns active and archived member medication records plus confirmed preferred-pharmacy capabilities.", "tags": [ "medications" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberMedicationsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-medications-mine", "summary": "Add or reactivate a medication for the authenticated member.", "description": "Saves an NDC-backed or manual member medication snapshot. Matching records are reactivated rather than duplicated.", "tags": [ "medications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemberMedicationRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberMedicationSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-medications-mine", "summary": "Update a medication owned by the authenticated member.", "description": "Archives, reactivates, or updates supported member medication fields.", "tags": [ "medications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberMedicationRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberMedicationSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/medications/search": { "get": { "operationId": "get-medications-search", "summary": "GET /api/medications/search", "description": "Returns medication autocomplete suggestions from the search index.", "tags": [ "medications" ], "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Search query for medication autocomplete" }, "description": "Search query for medication autocomplete", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Max number of results to return", "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Max number of results to return", "example": 1 }, { "in": "query", "name": "offset", "required": false, "schema": { "description": "Pagination offset", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Pagination offset", "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicationSearchResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/mobile/config": { "get": { "operationId": "get-mobile-config", "summary": "GET /api/mobile/config", "description": "Public, unauthenticated configuration the mobile app reads on launch and foreground. Builds below minimumAppVersion must block usage behind an update screen; builds below recommendedAppVersion should show a dismissible update prompt. Swift: fail open — if this request fails, do not gate the app.", "tags": [ "mobile" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileConfigResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } } }, "/personal-email": { "delete": { "operationId": "delete-personal-email", "summary": "Unlink the associated secondary Google account.", "description": "Removes the linked Google account identified by the stored account ID.", "tags": [ "personal-email" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/personal-email/link": { "post": { "operationId": "post-personal-email-link", "summary": "Initiate secondary Google account linking.", "description": "Returns a Google OAuth authorization URL. The client opens this URL to let the user authorize an additional Google account.", "tags": [ "personal-email" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/phone/send-otp": { "post": { "operationId": "post-phone-send-otp", "summary": "Auth context unused — the plugin identifies the user via the forwarded request headers.", "description": "Sends a 6-digit OTP code to the provided phone number for verification. US numbers only (+1 followed by 10 digits).", "tags": [ "phone" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOtpRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOtpResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/phone/verify": { "post": { "operationId": "post-phone-verify", "summary": "Auth context unused — the plugin identifies the user via the forwarded request headers.", "description": "Verifies the phone number by checking the 6-digit OTP code. On success, the phone number is stored on the user record as verified.", "tags": [ "phone" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/plan": { "get": { "operationId": "get-plan", "summary": "GET /api/plan", "description": "Returns enrollment details, plan configuration, and benefit balances for the authenticated user.", "tags": [ "plan" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } }, "/plan/funding-attestation": { "post": { "operationId": "post-plan-funding-attestation", "summary": "POST /api/plan/funding-attestation", "description": "Records the three HSA eligibility answers for the authenticated primary member's active organization enrollment. Covered dependents do not own the enrollment funding account and cannot submit an attestation. A clean primary-member attestation routes to HSA account opening; disqualifying coverage routes to HRA review. Enabling automatic claim payments also requires a recent authorization-change grant in x-step-up-token.", "tags": [ "plan" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingAttestationInputSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingAttestationResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/pre-auths": { "get": { "operationId": "get-pre-auths", "summary": "GET /api/pre-auths", "description": "List pre-authorizations belonging to the authenticated member, newest first. Includes admin-created and card-decline auto-created ones, so the app can show \"already requested\" instead of duplicating a request.", "tags": [ "pre-auths" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "description": "Comma-separated statuses (e.g. PENDING,APPROVED)" }, "description": "Comma-separated statuses (e.g. PENDING,APPROVED)", "example": "example" }, { "in": "query", "name": "open", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "open=true returns only actionable requests: PENDING, unexpired, unconsumed" }, "description": "open=true returns only actionable requests: PENDING, unexpired, unconsumed", "example": "example" }, { "in": "query", "name": "cardActivityId", "required": false, "schema": { "type": "string", "description": "A card-activity item id from GET /card-activity. Returns the pre-authorization auto-created for that decline (empty list when none exists) — the reliable 'already requested' check. Other filters are ignored." }, "description": "A card-activity item id from GET /card-activity. Returns the pre-authorization auto-created for that decline (empty list when none exists) — the reliable 'already requested' check. Other filters are ignored.", "example": "123" }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Max number of pre-authorizations to return", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "description": "Max number of pre-authorizations to return", "example": 1 }, { "in": "query", "name": "offset", "required": false, "schema": { "description": "Offset for pagination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Offset for pagination", "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreAuthorizationsListResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-pre-auths", "summary": "POST /api/pre-auths", "description": "Member-initiated pre-approval request for care above the automatic approval limit (e.g. after a card decline). Created PENDING and reviewed by the care team; the card starts working for it once approved. Swift: after a decline with reason \"needs pre-approval\", offer this instead of a support email.", "tags": [ "pre-auths" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemberPreAuthorizationRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberPreAuthorizationSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/profile/{userId}": { "get": { "operationId": "get-profile-{userId}", "summary": "Fetch the authenticated user's profile.", "description": "Returns profile details for the signed-in member matching the requested user ID.", "tags": [ "profile" ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Unique identifier for the authenticated user" }, "description": "Unique identifier for the authenticated user", "example": "user_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-profile-{userId}", "summary": "Update the authenticated user's profile.", "description": "Applies partial updates to the user's profile information for the specified user ID.", "tags": [ "profile" ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Unique identifier for the authenticated user" }, "description": "Unique identifier for the authenticated user", "example": "user_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileUpdateSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/profile/address": { "get": { "operationId": "get-profile-address", "summary": "Get the authenticated member's residential address.", "description": "Returns the address used for card billing and whether every usable card has received it.", "tags": [ "profile" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResidentialAddressStatusResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-profile-address", "summary": "Replace the authenticated member's residential address.", "description": "Saves a complete US residential address and synchronizes it to every usable member card. This endpoint does not require an active organization.", "tags": [ "profile" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResidentialAddressRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResidentialAddressUpdateResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/push/devices": { "post": { "operationId": "post-push-devices", "summary": "Register a push notification device token.", "description": "Stores a push token for the authenticated user and revokes older tokens for the same device ID.", "tags": [ "push" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPushDeviceRequestSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPushDeviceResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/quotes/census": { "post": { "operationId": "post-quotes-census", "summary": "", "description": "Normalize and price an employee census through the canonical quoting pipeline. A coverage effective date is required and must fit the active rate-card window. Clean CSV stays deterministic; malformed CSV with at most 500 source rows can be corrected by Claude before strict validation. Any unresolved ZIP or tier blocks the entire premium. Returns the full election grid unless one election is supplied. Indicative only; nothing here binds stop-loss.", "tags": [ "quotes" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CensusQuoteRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CensusQuoteResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/sandbox/benefits": { "get": { "operationId": "get-sandbox-benefits", "summary": "GET /api/sandbox/benefits", "description": "Returns production-shaped plan and balance data with `livemode=false`. Requires `Authorization: Bearer sk_sandbox_PUBLIC` and never reads production enrollment or accumulator rows.", "tags": [ "sandbox", "benefits" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxBenefitsResponseSchema" }, "examples": { "get_sandbox_benefits": { "summary": "Safe benefit balance lookup", "value": { "object": "benefits_summary", "livemode": false, "created": 1775001600, "plan": { "object": "health_plan", "id": "health_plan_aaaaaaaaaaaaaaaaaaaaaaaa", "livemode": false, "name": "Sandbox PPO" }, "balances": { "deductible": { "used": { "cents": 125000, "currency": "USD" }, "limit": { "cents": 500000, "currency": "USD" }, "remaining": { "cents": 375000, "currency": "USD" } } } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } } }, "/sandbox/claims": { "get": { "operationId": "get-sandbox-claims", "summary": "GET /api/sandbox/claims", "description": "Returns production-shaped claim list data with `livemode=false`. Requires `Authorization: Bearer sk_sandbox_PUBLIC` and never reads or writes production member, organization, or claim rows.", "tags": [ "sandbox", "claims" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxClaimsListResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-sandbox-claims", "summary": "POST /api/sandbox/claims", "description": "Safely exercises claim creation, validation, list shapes, and idempotency with `livemode=false`. Requires `Authorization: Bearer sk_sandbox_PUBLIC`. The response is not persisted except through the idempotency replay cache when an `Idempotency-Key` is supplied.", "tags": [ "sandbox", "claims" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCreateClaimRequestSchema" }, "examples": { "create_sandbox_claim": { "summary": "Create a safe simulated claim", "value": { "member_id": "mem_test_001", "service_category": "VISION", "submitted_amount": 4250, "service_date": "2026-04-01", "merchant_name": "Sandbox Vision", "description": "Eye exam simulation", "metadata": { "source": "agent_smoke_test" } } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCreateClaimResponseSchema" }, "examples": { "created_sandbox_claim": { "summary": "Created sandbox claim", "value": { "object": "claim", "id": "claim_aaaaaaaaaaaaaaaaaaaaaaaa", "created": 1775001600, "livemode": false, "metadata": { "source": "agent_smoke_test" }, "member_id": "mem_test_001", "source": "REIMBURSEMENT", "status": "SUBMITTED", "category": "VISION", "submitted_amount": 4250, "approved_amount": null, "member_owes": null, "deductible_applied": null, "coinsurance_applied": null, "service_date": 1775001600, "merchant_name": "Sandbox Vision", "description": "Eye exam simulation", "receipt_url": null, "uploaded_at": null } }, "idempotency_replay": { "summary": "Same Idempotency-Key replay", "value": { "object": "claim", "id": "claim_aaaaaaaaaaaaaaaaaaaaaaaa", "created": 1775001600, "livemode": false, "metadata": { "source": "agent_smoke_test" }, "member_id": "mem_test_001", "source": "REIMBURSEMENT", "status": "SUBMITTED", "category": "VISION", "submitted_amount": 4250, "approved_amount": null, "member_owes": null, "deductible_applied": null, "coinsurance_applied": null, "service_date": 1775001600, "merchant_name": "Sandbox Vision", "description": "Eye exam simulation", "receipt_url": null, "uploaded_at": null } } } } } }, "400": { "$ref": "#/components/responses/400" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "Same key with different body", "value": { "type": "idempotency_key_already_used_error", "title": "This idempotency key was already used with different request parameters.", "status": "409", "detail": null, "param": "Idempotency-Key", "recovery_hint": "CHECK_INPUT" } } } } } }, "500": { "$ref": "#/components/responses/500" } } } }, "/sandbox/errors": { "post": { "operationId": "post-sandbox-errors", "summary": "POST /api/sandbox/errors", "description": "Returns the same RFC 9457-style error envelope used by production routes. Requires `Authorization: Bearer sk_sandbox_PUBLIC` and is safe for agents to call while learning recovery behavior.", "tags": [ "sandbox" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorSimulationRequestSchema" }, "examples": { "validation_error": { "summary": "Simulate a validation error", "value": { "type": "validation_error", "param": "submitted_amount", "recovery_hint": "CHECK_INPUT" } } } } } }, "responses": { "400": { "$ref": "#/components/responses/400", "content": { "application/json": { "examples": { "validation_error": { "summary": "Canonical validation error", "value": { "type": "validation_error", "title": "Simulated validation_error.", "status": "400", "detail": null, "param": "submitted_amount", "recovery_hint": "CHECK_INPUT" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxErrorResponseSchema" } } } } } } }, "/sandbox/medications/search": { "get": { "operationId": "get-sandbox-medications-search", "summary": "GET /api/sandbox/medications/search", "description": "Returns production-shaped medication search results with `livemode=false`. Requires `Authorization: Bearer sk_sandbox_PUBLIC`.", "tags": [ "sandbox", "medications" ], "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Medication search query" }, "description": "Medication search query", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "example": 1 }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "example": 1 } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxMedicationSearchResponseSchema" }, "examples": { "search_sandbox_medications": { "summary": "Safe medication search response", "value": { "object": "list", "data": [ { "id": "medication_search_aaaaaaaaaaaaaaaaaaaaaaaa", "ndc": "00002143380", "medication_name": "Atorvastatin", "brand_name": "Lipitor", "strength": "20 mg", "form": "tablet", "formatted_price": "$6.60", "url": "https://www.costplusdrugs.com/medications/atorvastatin-20mg-tablet/", "display_name": "Atorvastatin 20 mg tablet", "livemode": false } ], "has_more": false, "url": "/api/sandbox/medications/search" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } } } }, "/upload/initiate": { "post": { "operationId": "post-upload-initiate", "summary": "POST /api/upload/initiate", "description": "Generates a pre-signed Cloudflare R2 URL for direct client uploads (mobile-friendly two-step flow).", "tags": [ "uploads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateUploadRequestSchema" }, "examples": { "initiate_upload": { "summary": "Initiate a member invoice upload", "value": { "file_name": "vision-invoice.pdf", "content_type": "application/pdf", "file_size": 120000, "purpose": "member-invoices" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateUploadResponseSchema" }, "examples": { "upload_initiated": { "summary": "Presigned upload response", "value": { "upload_url": "https://files.example.com/presigned-put", "key": "member-invoices/member_aaaaaaaaaaaaaaaaaaaaaaaa/vision-invoice.pdf", "expires_at": "2026-04-28T12:15:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict. The idempotency key was reused with different request parameters." }, "500": { "$ref": "#/components/responses/500" } } } }, "/users/{userId}": { "get": { "operationId": "get-users-{userId}", "summary": "Fetch the authenticated user's full record.", "description": "Returns the complete user object, including profile data, legacy onboarding metadata, and the 16-item organization-scoped onboarding checklist.", "tags": [ "user" ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Unique identifier for the authenticated user" }, "description": "Unique identifier for the authenticated user", "example": "user_aaaaaaaaaaaaaaaaaaaaaaaa" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-users-{userId}", "summary": "Update user-level attributes.", "description": "Allows the authenticated user to update high-level attributes, the legacy onboarding cursor, and selected organization-scoped checklist items.", "tags": [ "user" ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/UserIdSchema" } ], "description": "Unique identifier for the authenticated user" }, "description": "Unique identifier for the authenticated user", "example": "user_aaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safely retrying mutating requests. Matching retries replay the first stored response for 24 hours; reusing a key with different parameters returns 409.", "schema": { "type": "string", "maxLength": 255 } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } } } }, "/wearables/activity": { "get": { "operationId": "get-wearables-activity", "summary": "Get daily activity.", "description": "Returns daily activity load: Oura steps, calories, and activity score, plus WHOOP day strain and heart-rate summary. Energy is kilocalories on both, converted from WHOOP's kilojoules.", "tags": [ "wearables" ], "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected." }, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected.", "example": 1 }, { "in": "query", "name": "startDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range start (YYYY-MM-DD). Requires endDate." }, "description": "Explicit range start (YYYY-MM-DD). Requires endDate.", "example": "example" }, { "in": "query", "name": "endDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range end (YYYY-MM-DD). Requires startDate." }, "description": "Explicit range end (YYYY-MM-DD). Requires startDate.", "example": "example" }, { "in": "query", "name": "includeRaw", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Include the untouched provider payload on each record. Roughly triples the response." }, "description": "Include the untouched provider payload on each record. Roughly triples the response.", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/wearables/connections": { "get": { "operationId": "get-wearables-connections", "summary": "List wearable connections.", "description": "Returns which wearable providers the authenticated member has linked, which scopes each grant carries, and whether a reconnect is needed before data can be read.", "tags": [ "wearables" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WearableConnectionsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/wearables/profile": { "get": { "operationId": "get-wearables-profile", "summary": "Get wearable profile.", "description": "Returns the body metrics each linked wearable holds: height in metres, weight in kilograms, max heart rate, age, and biological sex where reported.", "tags": [ "wearables" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WearableProfilesResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/wearables/recovery": { "get": { "operationId": "get-wearables-recovery", "summary": "Get daily recovery.", "description": "Returns WHOOP recovery scores and Oura readiness scores per day, both on a 0-100 scale, with HRV and resting heart rate where the provider reports them.", "tags": [ "wearables" ], "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected." }, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected.", "example": 1 }, { "in": "query", "name": "startDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range start (YYYY-MM-DD). Requires endDate." }, "description": "Explicit range start (YYYY-MM-DD). Requires endDate.", "example": "example" }, { "in": "query", "name": "endDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range end (YYYY-MM-DD). Requires startDate." }, "description": "Explicit range end (YYYY-MM-DD). Requires startDate.", "example": "example" }, { "in": "query", "name": "includeRaw", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Include the untouched provider payload on each record. Roughly triples the response." }, "description": "Include the untouched provider payload on each record. Roughly triples the response.", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/wearables/sleep": { "get": { "operationId": "get-wearables-sleep", "summary": "Get nightly sleep.", "description": "Returns nightly sleep across every linked wearable, normalized to shared units. Durations are minutes on both devices. Pass includeRaw=true to also receive the untouched provider payload.", "tags": [ "wearables" ], "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected." }, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected.", "example": 1 }, { "in": "query", "name": "startDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range start (YYYY-MM-DD). Requires endDate." }, "description": "Explicit range start (YYYY-MM-DD). Requires endDate.", "example": "example" }, { "in": "query", "name": "endDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range end (YYYY-MM-DD). Requires startDate." }, "description": "Explicit range end (YYYY-MM-DD). Requires startDate.", "example": "example" }, { "in": "query", "name": "includeRaw", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Include the untouched provider payload on each record. Roughly triples the response." }, "description": "Include the untouched provider payload on each record. Roughly triples the response.", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SleepResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } }, "/wearables/workouts": { "get": { "operationId": "get-wearables-workouts", "summary": "List workouts.", "description": "Returns workouts from every linked wearable with duration, calories, distance, and heart-rate summary. WHOOP adds strain; Oura adds the wearer's own easy/moderate/hard intensity label.", "tags": [ "wearables" ], "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected." }, "description": "How many days back to read, ending today. The effective default and ceiling differ per collection; over-long windows are shortened rather than rejected.", "example": 1 }, { "in": "query", "name": "startDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range start (YYYY-MM-DD). Requires endDate." }, "description": "Explicit range start (YYYY-MM-DD). Requires endDate.", "example": "example" }, { "in": "query", "name": "endDate", "required": false, "schema": { "type": "string", "format": "date", "description": "Explicit range end (YYYY-MM-DD). Requires startDate." }, "description": "Explicit range end (YYYY-MM-DD). Requires startDate.", "example": "example" }, { "in": "query", "name": "includeRaw", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Include the untouched provider payload on each record. Roughly triples the response." }, "description": "Include the untouched provider payload on each record. Roughly triples the response.", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutsResponseSchema" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } } }, "tags": [ { "name": "account" }, { "name": "accounts" }, { "name": "admin" }, { "name": "assistant" }, { "name": "banking" }, { "name": "benefits" }, { "name": "capabilities" }, { "name": "cards" }, { "name": "care" }, { "name": "census" }, { "name": "claims" }, { "name": "doctors" }, { "name": "files" }, { "name": "funding" }, { "name": "labs" }, { "name": "legal" }, { "name": "medical-history" }, { "name": "medications" }, { "name": "mobile" }, { "name": "personal-email" }, { "name": "phone" }, { "name": "plan" }, { "name": "pre-auths" }, { "name": "profile" }, { "name": "push" }, { "name": "quotes" }, { "name": "sandbox" }, { "name": "uploads" }, { "name": "user" }, { "name": "wearables" } ] }