{"openapi":"3.1.0","info":{"title":"MIDAS API","description":"Market Informed Demand Automation Server API","contact":{"name":"California Energy Commission","email":"midas@energy.ca.gov"},"version":"1.5.0"},"paths":{"/api/registration":{"post":{"tags":["authentication"],"summary":"Register a new user","description":"Register a new user account with AWS Cognito.\n\nAll fields are Base64-encoded. On success, a verification email is sent to the provided email address.","operationId":"register_user_api_registration_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/token":{"get":{"tags":["authentication"],"summary":"Get authentication token","description":"Authenticate using HTTP Basic credentials and receive a JWT token.\n\nThe JWT access token is returned in the `Token` response header. The response body contains token metadata (type and expiration).","operationId":"get_authentication_token_api_token_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}}},"security":[{"HTTPBasic":[]}]}},"/api/resendverification":{"post":{"tags":["authentication"],"summary":"Resend verification email","description":"Resend the email verification code to a registered user.\n\nIf the email is already verified, returns a success message without sending a new code.","operationId":"resend_verification_email_api_resendverification_post","parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string","description":"Username of the registered account","title":"Username"},"description":"Username of the registered account"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendVerificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/confirmemail":{"post":{"tags":["authentication"],"summary":"Confirm email address","description":"Confirm a user's email address using the verification code sent during registration.\n\nIf the email is already verified, returns success without re-processing the confirmation.","operationId":"confirm_user_email_post_api_confirmemail_post","parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string","description":"Username of the account to confirm","title":"Username"},"description":"Username of the account to confirm"},{"name":"confirmation_code","in":"query","required":true,"schema":{"type":"string","description":"Verification code emailed to the user during registration","title":"Confirmation Code"},"description":"Verification code emailed to the user during registration"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmEmailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/forgotpassword":{"post":{"tags":["authentication"],"summary":"Initiate password reset","description":"Initiate a password reset for a user account.\n\nSends a one-time reset token to the user's registered email. The response is intentionally generic to prevent account enumeration.","operationId":"initiate_password_reset_api_forgotpassword_post","parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string","description":"Username of the account requesting a reset","title":"Username"},"description":"Username of the account requesting a reset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/confirmpasswordreset":{"post":{"tags":["authentication"],"summary":"Confirm password reset","description":"Confirm a password reset using a one-time reset token.\n\n- Token is single-use and time-limited\n- New password is validated by AWS Cognito\n- Response is intentionally generic to prevent account enumeration","operationId":"confirm_password_reset_api_confirmpasswordreset_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmPasswordResetRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmPasswordResetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/uploadaccess/request":{"post":{"tags":["authentication"],"summary":"Request LSE upload access","description":"Allow a verified user to request LSE upload access for a specific energy and distribution code combination.\n\nRequires a valid JWT token. An admin must subsequently approve the request via the admin endpoint.","operationId":"request_upload_access_api_uploadaccess_request_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAccessRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAccessRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/admin/approvelseaccess":{"post":{"tags":["admin"],"summary":"Approve LSE upload access","description":"Approve a user's request for LSE upload access.\n\nSets the user's AccountType to 'lse' and assigns the specified energy and distribution codes. Sends an approval notification email.","operationId":"approve_lse_access_admin_approvelseaccess_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveAccess"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveAccessResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/admin/removelseaccess":{"post":{"tags":["admin"],"summary":"Remove LSE upload access","description":"Remove specific energy/distribution codes from a user's LSE access.\n\nIf both code lists become empty, the user's AccountType is automatically reset to 'user'. Sends a removal notification email.","operationId":"remove_lse_access_admin_removelseaccess_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveAccess"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveAccessResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/admin/lookup-values/create":{"post":{"tags":["admin"],"summary":"Create lookup table value","description":"Create a lookup table value.\n\nOnly administrators can create lookup values. Create enforces case-insensitive uniqueness by lookup table and value.","operationId":"create_lookup_table_value_admin_lookup_values_create_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLookupTableValueRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTableValueResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/admin/lookup-values/update":{"post":{"tags":["admin"],"summary":"Update lookup table value","description":"Update a lookup table value.\n\nOnly administrators can update lookup values. If the lookup value/code changes, the operation creates a new record and soft-deletes the old one.","operationId":"update_lookup_table_value_admin_lookup_values_update_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLookupTableValueRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTableValueResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/admin/lookup-values/delete":{"post":{"tags":["admin"],"summary":"Soft-delete lookup table value","description":"Soft-delete a lookup table value.\n\nOnly administrators can delete lookup values. Delete only marks the lookup value as deleted and does not physically delete the record.","operationId":"delete_lookup_table_value_admin_lookup_values_delete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteLookupTableValueRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTableValueResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/valuedata":{"get":{"tags":["value_data"],"summary":"Retrieve rate data, lookup tables, or XML schema","description":"Multi-purpose endpoint that returns different data based on query parameters:\n\n- **No parameters** (authenticated LSE): Returns the XML upload schema\n- **SignalType** (public): Returns list of RINs filtered by signal type (0=All, 1=Electricity Rates, 2=Greenhouse Gas Emissions, 3=California Independent System Operator Flex Alert)\n- **ID + QueryType** (public): Returns rate values for a specific RIN (QueryType: realtime, alldata)\n- **LookupTable** (public): Returns lookup table data (e.g., Distribution, Energy, StateProvince)\n\nQuery parameter names are case-insensitive.","operationId":"get_value_data_api_valuedata_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"SignalType","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Signal type filter (0=All, 1=Electricity Rates, 2=Greenhouse Gas Emissions, 3=California Independent System Operator Flex Alert)","title":"Signaltype"},"description":"Signal type filter (0=All, 1=Electricity Rates, 2=Greenhouse Gas Emissions, 3=California Independent System Operator Flex Alert)"},{"name":"ID","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Rate ID for specific rate data","title":"Id"},"description":"Rate ID for specific rate data"},{"name":"QueryType","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Query type (realtime, alldata)","title":"Querytype"},"description":"Query type (realtime, alldata)"},{"name":"LookupTable","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Lookup table name","title":"Lookuptable"},"description":"Lookup table name"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["value_data"],"summary":"Upload rate data","description":"Upload rate information and values for LSE accounts.\n\nAccepts JSON or XML payloads (XML is converted to JSON by middleware). Validates against user authorization and queues data for processing via SQS.","operationId":"upload_value_data_api_valuedata_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Payload"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadJobAcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/historicaldata/{rate_id}":{"get":{"tags":["historical_data"],"summary":"Retrieve historical rate data for a specific RIN","description":"Returns rate information and value data for a specific RIN filtered by date range.\n\n- **rate_id**: Rate Identification Number (RIN) as path parameter\n- **startdate**: Beginning date for data range (YYYY-MM-DD)\n- **enddate**: Ending date for data range (YYYY-MM-DD)\n\nDate range is limited to a maximum of 6 months. Public access (no authentication required).","operationId":"get_historical_data_api_historicaldata__rate_id__get","parameters":[{"name":"rate_id","in":"path","required":true,"schema":{"type":"string","description":"Rate Identification Number (RIN) to retrieve history for","title":"Rate Id"},"description":"Rate Identification Number (RIN) to retrieve history for"},{"name":"startdate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date for data range (YYYY-MM-DD)","title":"Startdate"},"description":"Start date for data range (YYYY-MM-DD)"},{"name":"enddate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date for data range (YYYY-MM-DD)","title":"Enddate"},"description":"End date for data range (YYYY-MM-DD)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/watttime/health":{"get":{"tags":["WattTime Health"],"summary":"Get WattTime health status","description":"Get health status of the WattTime token management system including token expiration, circuit breaker state, performance metrics, and cache performance.","operationId":"get_health_status_watttime_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenServiceHealth"}}}}}}},"/watttime/health/detailed":{"get":{"tags":["WattTime Health"],"summary":"Get detailed WattTime health","description":"Get detailed health status including circuit breaker state, token metrics, and request correlation tracking.","operationId":"get_detailed_health_status_watttime_health_detailed_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealthResponse"}}}}}}},"/watttime/health/refresh":{"post":{"tags":["WattTime Health"],"summary":"Trigger token refresh","description":"Manually trigger a WattTime token refresh for testing and operational purposes. Returns the refresh result with correlation tracking.","operationId":"trigger_token_refresh_watttime_health_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRefreshResponse"}}}}}}},"/watttime/metrics":{"get":{"tags":["WattTime Health"],"summary":"Get token metrics","description":"Get current token management metrics including refresh success rates, latency, cache performance, and circuit breaker activations.","operationId":"get_token_metrics_watttime_metrics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenMetricsResponse"}}}}}}},"/watttime/health/comprehensive":{"get":{"tags":["WattTime Health"],"summary":"Get comprehensive WattTime health","description":"Get comprehensive health status with calculated metrics including overall health score (0-100), token service status, circuit breaker state, refresh success rates, latency, cache performance, and alert thresholds.","operationId":"get_comprehensive_health_status_watttime_health_comprehensive_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComprehensiveHealthResponse"}}}}}}},"/watttime/status":{"get":{"tags":["WattTime Health"],"summary":"Get WattTime simple status","description":"Lightweight up/down status check for basic monitoring systems.","operationId":"get_simple_status_watttime_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleStatusResponse"}}}}}}},"/caiso/health":{"get":{"tags":["CAISO Health"],"summary":"Get CAISO health status","description":"Get health status of the CAISO Flex Alert service including circuit breaker state, API metrics, and cache performance.","operationId":"get_health_status_caiso_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAISOHealthResponse"}}}}}}},"/caiso/status":{"get":{"tags":["CAISO Health"],"summary":"Get CAISO simple status","description":"Lightweight up/down status check for basic monitoring systems.","operationId":"get_simple_status_caiso_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAISOSimpleStatusResponse"}}}}}}},"/api/jobs":{"get":{"tags":["jobs"],"summary":"List recent upload jobs","description":"Return recent upload jobs for the authenticated LSE user.","operationId":"list_jobs_api_jobs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"detailed","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include summary details for each job.","default":false,"title":"Detailed"},"description":"When true, include summary details for each job."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Get upload job detail","description":"Return full upload processing detail for one job ID.","operationId":"get_job_api_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","description":"Upload job identifier to retrieve","title":"Job Id"},"description":"Upload job identifier to retrieve"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["system"],"summary":"Health check","description":"Health check endpoint for monitoring and load balancer health checks.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthCheckResponse"}}}}}}},"/":{"get":{"tags":["system"],"summary":"API information","description":"Root endpoint providing basic API information and navigation links.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootResponse"}}}}}}}},"components":{"schemas":{"AlertsInfo":{"properties":{"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Current consecutive failure count","default":0},"alert_threshold_reached":{"type":"boolean","title":"Alert Threshold Reached","description":"Whether alert threshold (3) is reached","default":false},"critical_threshold_reached":{"type":"boolean","title":"Critical Threshold Reached","description":"Whether critical threshold (5) is reached","default":false}},"type":"object","title":"AlertsInfo","description":"Alert threshold information."},"ApproveAccess":{"properties":{"username":{"type":"string","title":"Username","description":"Username of the user gaining LSE upload access"},"energy_code":{"type":"string","title":"Energy Code","description":"Two-letter energy code (validated by lookup table)"},"distribution_code":{"type":"string","title":"Distribution Code","description":"Two-letter distribution code (validated by lookup table)"}},"type":"object","required":["username","energy_code","distribution_code"],"title":"ApproveAccess","description":"Request model for approving a user's LSE upload access."},"ApproveAccessResult":{"properties":{"message":{"type":"string","title":"Message"},"username":{"type":"string","title":"Username"}},"type":"object","required":["message","username"],"title":"ApproveAccessResult","description":"Response model returned after successful LSE access approval."},"CAISOCache":{"properties":{"ttl_minutes":{"type":"number","title":"Ttl Minutes","description":"Cache time-to-live in minutes"},"fallback_ttl_hours":{"type":"number","title":"Fallback Ttl Hours","description":"Fallback cache TTL in hours"},"entries":{"type":"integer","title":"Entries","description":"Number of cached entries","default":0}},"type":"object","required":["ttl_minutes","fallback_ttl_hours"],"title":"CAISOCache","description":"CAISO cache information."},"CAISOCircuitBreaker":{"properties":{"open":{"type":"boolean","title":"Open","description":"Whether circuit breaker is open","default":false},"open_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Open Since","description":"Time circuit opened (ISO 8601)"},"threshold":{"type":"integer","title":"Threshold","description":"Failure threshold before opening","default":5},"timeout_minutes":{"type":"number","title":"Timeout Minutes","description":"Minutes before retry after opening","default":5.0}},"type":"object","title":"CAISOCircuitBreaker","description":"CAISO circuit breaker state."},"CAISOHealthResponse":{"properties":{"healthy":{"type":"boolean","title":"Healthy","description":"Overall service health"},"issues":{"items":{"type":"string"},"type":"array","title":"Issues","description":"Current health issues"},"metrics":{"$ref":"#/components/schemas/CAISOMetrics"},"circuit_breaker":{"$ref":"#/components/schemas/CAISOCircuitBreaker"},"cache":{"$ref":"#/components/schemas/CAISOCache"}},"type":"object","required":["healthy","metrics","circuit_breaker","cache"],"title":"CAISOHealthResponse","description":"Response model for CAISO health status."},"CAISOMetrics":{"properties":{"total_requests":{"type":"integer","title":"Total Requests","description":"Total API requests made","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Request success rate percentage","default":0.0},"average_response_time":{"type":"number","title":"Average Response Time","description":"Average response time in seconds","default":0.0},"cache_hit_rate":{"type":"number","title":"Cache Hit Rate","description":"Cache hit rate percentage","default":0.0},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Current consecutive failure count","default":0},"rate_limit_hits":{"type":"integer","title":"Rate Limit Hits","description":"Number of rate limit hits","default":0},"last_request":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Request","description":"Last request time (ISO 8601)"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error","description":"Last error time (ISO 8601)"},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message","description":"Last error message"}},"type":"object","title":"CAISOMetrics","description":"CAISO API request metrics."},"CAISOSimpleStatusResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Service status (healthy, unhealthy)","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service name","examples":["caiso-flex-alert"]},"timestamp":{"type":"string","title":"Timestamp","description":"Current timestamp (ISO 8601)"}},"type":"object","required":["status","service","timestamp"],"title":"CAISOSimpleStatusResponse","description":"Response model for CAISO simple status."},"CacheMetric":{"properties":{"hits":{"type":"integer","title":"Hits","description":"Cache hit count","default":0},"misses":{"type":"integer","title":"Misses","description":"Cache miss count","default":0},"total_requests":{"type":"integer","title":"Total Requests","description":"Total cache requests","default":0},"hit_rate":{"type":"number","title":"Hit Rate","description":"Cache hit rate (0.0-1.0)","default":0.0}},"type":"object","title":"CacheMetric","description":"Cache performance metrics."},"CircuitBreakerDetail":{"properties":{"status":{"type":"string","title":"Status","description":"Circuit breaker status (closed, open, half-open)"},"failure_count":{"type":"integer","title":"Failure Count","description":"Current failure count","default":0},"failure_threshold":{"type":"integer","title":"Failure Threshold","description":"Failures before circuit opens","default":5},"last_failure_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Failure Time","description":"Last failure time (ISO 8601)"},"next_attempt_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Attempt Time","description":"Next allowed attempt time (ISO 8601)"},"can_attempt":{"type":"boolean","title":"Can Attempt","description":"Whether new attempts are allowed","default":true}},"type":"object","required":["status"],"title":"CircuitBreakerDetail","description":"Circuit breaker state detail."},"CircuitBreakerMetric":{"properties":{"activations":{"type":"integer","title":"Activations","description":"Number of circuit breaker activations","default":0}},"type":"object","title":"CircuitBreakerMetric","description":"Circuit breaker metrics."},"CircuitBreakerStatus":{"type":"string","enum":["closed","open","half-open"],"title":"CircuitBreakerStatus","description":"Circuit breaker status enumeration."},"ComprehensiveCacheMetric":{"properties":{"hits":{"type":"integer","title":"Hits","default":0},"misses":{"type":"integer","title":"Misses","default":0},"total_requests":{"type":"integer","title":"Total Requests","default":0},"hit_rate":{"type":"number","title":"Hit Rate","default":0.0},"hit_rate_percentage":{"type":"string","title":"Hit Rate Percentage","description":"Hit rate as percentage string","default":"0.0%"}},"type":"object","title":"ComprehensiveCacheMetric","description":"Cache metrics with percentage display."},"ComprehensiveHealthResponse":{"properties":{"correlation_id":{"type":"string","title":"Correlation Id","description":"Request correlation ID"},"timestamp":{"type":"string","title":"Timestamp","description":"Response timestamp (ISO 8601)"},"overall_health":{"$ref":"#/components/schemas/OverallHealthStatus"},"token_service":{"$ref":"#/components/schemas/TokenServiceSummary"},"circuit_breaker":{"$ref":"#/components/schemas/CircuitBreakerDetail"},"metrics":{"$ref":"#/components/schemas/ComprehensiveMetrics"},"alerts":{"$ref":"#/components/schemas/AlertsInfo"}},"type":"object","required":["correlation_id","timestamp","overall_health","token_service","circuit_breaker","metrics","alerts"],"title":"ComprehensiveHealthResponse","description":"Response model for comprehensive health status."},"ComprehensiveMetrics":{"properties":{"refresh_operations":{"$ref":"#/components/schemas/ComprehensiveRefreshOperations"},"performance":{"$ref":"#/components/schemas/ComprehensivePerformance"},"cache":{"$ref":"#/components/schemas/ComprehensiveCacheMetric"},"circuit_breaker":{"$ref":"#/components/schemas/CircuitBreakerMetric"}},"type":"object","required":["refresh_operations","performance","cache","circuit_breaker"],"title":"ComprehensiveMetrics","description":"All metrics for comprehensive health."},"ComprehensivePerformance":{"properties":{"average_latency_ms":{"type":"integer","title":"Average Latency Ms","default":0},"total_latency_ms":{"type":"integer","title":"Total Latency Ms","default":0},"latency_status":{"type":"string","title":"Latency Status","description":"Latency status label","default":"no_data"}},"type":"object","title":"ComprehensivePerformance","description":"Performance metrics with status label."},"ComprehensiveRefreshOperations":{"properties":{"success_count":{"type":"integer","title":"Success Count","default":0},"failure_count":{"type":"integer","title":"Failure Count","default":0},"total_count":{"type":"integer","title":"Total Count","default":0},"success_rate":{"type":"number","title":"Success Rate","default":0.0},"success_rate_percentage":{"type":"string","title":"Success Rate Percentage","description":"Success rate as percentage string","default":"0.0%"}},"type":"object","title":"ComprehensiveRefreshOperations","description":"Refresh operations with percentage display."},"ConfirmEmailResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Result message"},"username":{"type":"string","title":"Username","description":"Username that was confirmed"},"verified":{"type":"boolean","title":"Verified","description":"Whether the email is now verified"}},"type":"object","required":["message","username","verified"],"title":"ConfirmEmailResponse","description":"Response model for email confirmation."},"ConfirmPasswordResetRequest":{"properties":{"token":{"type":"string","minLength":10,"title":"Token","description":"One-time password reset token received via email","examples":["eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."]},"new_password":{"type":"string","minLength":8,"title":"New Password","description":"New account password (validated and enforced by Cognito policy)","examples":["Str0ngP@ssw0rd!"]}},"type":"object","required":["token","new_password"],"title":"ConfirmPasswordResetRequest"},"ConfirmPasswordResetResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Generic result message to prevent information leakage","examples":["If the reset request is valid, the password has been updated."]}},"type":"object","required":["message"],"title":"ConfirmPasswordResetResponse"},"CreateLookupTableValueRequest":{"properties":{"tableName":{"type":"string","title":"Tablename","description":"Lookup table name"},"value":{"$ref":"#/components/schemas/LookupTableValuePayload","description":"Lookup value to create"}},"type":"object","required":["tableName","value"],"title":"CreateLookupTableValueRequest","description":"Request model for creating a lookup table value."},"DeleteLookupTableValueRequest":{"properties":{"tableName":{"type":"string","title":"Tablename","description":"Lookup table name"},"value":{"type":"string","title":"Value","description":"Lookup value/code to soft-delete"}},"type":"object","required":["tableName","value"],"title":"DeleteLookupTableValueRequest","description":"Request model for soft-deleting a lookup table value."},"DetailedHealthResponse":{"properties":{"correlation_id":{"type":"string","title":"Correlation Id","description":"Request correlation ID for tracing"},"health_status":{"$ref":"#/components/schemas/HealthStatusDetail"},"circuit_breaker":{"$ref":"#/components/schemas/CircuitBreakerDetail"},"metrics":{"$ref":"#/components/schemas/MetricsDetail"}},"type":"object","required":["correlation_id","health_status","circuit_breaker","metrics"],"title":"DetailedHealthResponse","description":"Response model for detailed health status."},"ForgotPasswordResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Generic result message to prevent account enumeration"}},"type":"object","required":["message"],"title":"ForgotPasswordResponse","description":"Response model for forgot password initiation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthCheckResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Service health status","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service name","examples":["midas-api"]},"version":{"type":"string","title":"Version","description":"API version","examples":["1.5.0"]}},"type":"object","required":["status","service","version"],"title":"HealthCheckResponse","description":"Health check response."},"HealthStatusDetail":{"properties":{"healthy":{"type":"boolean","title":"Healthy","description":"Whether the token service is healthy"},"last_refresh":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Refresh","description":"Last successful refresh (ISO 8601)"},"token_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Expires At","description":"Token expiration time (ISO 8601)"},"time_until_expiry_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Time Until Expiry Minutes","description":"Minutes until token expires"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Number of consecutive refresh failures","default":0},"refresh_success_rate_24h":{"type":"number","title":"Refresh Success Rate 24H","description":"24-hour refresh success rate","default":0.0},"average_refresh_latency_ms":{"type":"integer","title":"Average Refresh Latency Ms","description":"Average refresh latency in ms","default":0},"circuit_breaker_status":{"type":"string","title":"Circuit Breaker Status","description":"Circuit breaker status","default":"closed"},"cache_hit_rate":{"type":"number","title":"Cache Hit Rate","description":"Token cache hit rate","default":0.0}},"type":"object","required":["healthy"],"title":"HealthStatusDetail","description":"Token service health status detail."},"JobStatus":{"type":"string","enum":["PROCESSING","COMPLETE","VALIDATION_FAILED"],"title":"JobStatus","description":"Job status values defined by the Jobs endpoint contract."},"LookupTableUpdatePayload":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code","description":"New lookup value/code"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human readable description"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL for Distribution/Energy tables"},"utc_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Utc Offset","description":"UTC offset for TimeZone table"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code","description":"Country code for StateProvince table"},"unit_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit Symbol","description":"Human-readable unit symbol"}},"type":"object","title":"LookupTableUpdatePayload","description":"Admin request payload for updating a lookup table value."},"LookupTableValuePayload":{"properties":{"code":{"type":"string","title":"Code","description":"Lookup value/code"},"description":{"type":"string","title":"Description","description":"Human readable description"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL for Distribution/Energy tables"},"utc_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Utc Offset","description":"UTC offset for TimeZone table"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code","description":"Country code for StateProvince table"},"unit_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit Symbol","description":"Human-readable unit symbol"}},"type":"object","required":["code","description"],"title":"LookupTableValuePayload","description":"Admin request payload for a lookup table value."},"LookupTableValueResult":{"properties":{"message":{"type":"string","title":"Message"},"table_name":{"type":"string","title":"Table Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["message","table_name","value"],"title":"LookupTableValueResult","description":"Response model for admin lookup table value operations."},"MetricsDetail":{"properties":{"refresh_success_count":{"type":"integer","title":"Refresh Success Count","description":"Successful refresh count","default":0},"refresh_failure_count":{"type":"integer","title":"Refresh Failure Count","description":"Failed refresh count","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Refresh success rate (0.0-1.0)","default":0.0},"average_latency_ms":{"type":"integer","title":"Average Latency Ms","description":"Average refresh latency in ms","default":0},"cache_hits":{"type":"integer","title":"Cache Hits","description":"Cache hit count","default":0},"cache_misses":{"type":"integer","title":"Cache Misses","description":"Cache miss count","default":0},"cache_hit_rate":{"type":"number","title":"Cache Hit Rate","description":"Cache hit rate (0.0-1.0)","default":0.0},"circuit_breaker_activations":{"type":"integer","title":"Circuit Breaker Activations","description":"Circuit breaker activation count","default":0}},"type":"object","title":"MetricsDetail","description":"Token management metrics."},"OverallHealthStatus":{"properties":{"healthy":{"type":"boolean","title":"Healthy","description":"Whether the system is overall healthy"},"health_score":{"type":"integer","title":"Health Score","description":"Health score from 0 (critical) to 100 (excellent)"},"status":{"type":"string","title":"Status","description":"Health status label (healthy, degraded)"}},"type":"object","required":["healthy","health_score","status"],"title":"OverallHealthStatus","description":"Overall health assessment."},"PerformanceMetric":{"properties":{"average_latency_ms":{"type":"integer","title":"Average Latency Ms","description":"Average latency in ms","default":0},"total_latency_ms":{"type":"integer","title":"Total Latency Ms","description":"Total latency in ms","default":0}},"type":"object","title":"PerformanceMetric","description":"Performance metrics."},"RefreshOperationsMetric":{"properties":{"success_count":{"type":"integer","title":"Success Count","description":"Successful refresh count","default":0},"failure_count":{"type":"integer","title":"Failure Count","description":"Failed refresh count","default":0},"total_count":{"type":"integer","title":"Total Count","description":"Total refresh count","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Success rate (0.0-1.0)","default":0.0}},"type":"object","title":"RefreshOperationsMetric","description":"Refresh operation metrics."},"RefreshResultDetail":{"properties":{"status":{"type":"string","title":"Status","description":"Refresh status (success, failure, rate_limited)"},"token_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Expires At","description":"New token expiration (ISO 8601)"},"refresh_duration_ms":{"type":"integer","title":"Refresh Duration Ms","description":"Refresh duration in ms","default":0},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if failed"},"retry_after_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After Seconds","description":"Seconds before retry is allowed"},"is_success":{"type":"boolean","title":"Is Success","description":"Whether the refresh succeeded"},"is_retryable":{"type":"boolean","title":"Is Retryable","description":"Whether the failure is retryable"}},"type":"object","required":["status","is_success","is_retryable"],"title":"RefreshResultDetail","description":"Token refresh operation result."},"RegistrationResponse":{"properties":{"message":{"type":"string","title":"Message"},"username":{"type":"string","title":"Username"},"email_verification_sent":{"type":"boolean","title":"Email Verification Sent"}},"type":"object","required":["message","username","email_verification_sent"],"title":"RegistrationResponse","description":"Response model for user registration."},"RemoveAccess":{"properties":{"username":{"type":"string","title":"Username","description":"Username of the user whose access is being removed"},"energy_code":{"type":"string","title":"Energy Code","description":"Energy code to remove"},"distribution_code":{"type":"string","title":"Distribution Code","description":"Distribution code to remove"}},"type":"object","required":["username","energy_code","distribution_code"],"title":"RemoveAccess","description":"Request model for removing specific upload codes from a user."},"RemoveAccessResult":{"properties":{"message":{"type":"string","title":"Message"},"username":{"type":"string","title":"Username"},"remaining_energy_codes":{"items":{"type":"string"},"type":"array","title":"Remaining Energy Codes"},"remaining_distribution_codes":{"items":{"type":"string"},"type":"array","title":"Remaining Distribution Codes"}},"type":"object","required":["message","username"],"title":"RemoveAccessResult","description":"Response model returned after successful LSE access removal."},"ResendVerificationResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Result message"},"username":{"type":"string","title":"Username","description":"Username that was requested"}},"type":"object","required":["message","username"],"title":"ResendVerificationResponse","description":"Response model for resend verification email."},"RootResponse":{"properties":{"message":{"type":"string","title":"Message","description":"API welcome message"},"version":{"type":"string","title":"Version","description":"API version","examples":["1.5.0"]},"docs":{"type":"string","title":"Docs","description":"API documentation URL","examples":["/openapi"]},"health":{"type":"string","title":"Health","description":"Health check URL","examples":["/health"]}},"type":"object","required":["message","version","docs","health"],"title":"RootResponse","description":"Root endpoint response with API information."},"SimpleStatusResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Service status (healthy, unhealthy)","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service name","examples":["watttime-token-management"]},"timestamp":{"type":"string","title":"Timestamp","description":"Current timestamp (ISO 8601)"}},"type":"object","required":["status","service","timestamp"],"title":"SimpleStatusResponse","description":"Response model for simple status check."},"TokenMetricsResponse":{"properties":{"refresh_operations":{"$ref":"#/components/schemas/RefreshOperationsMetric"},"performance":{"$ref":"#/components/schemas/PerformanceMetric"},"cache":{"$ref":"#/components/schemas/CacheMetric"},"circuit_breaker":{"$ref":"#/components/schemas/CircuitBreakerMetric"}},"type":"object","required":["refresh_operations","performance","cache","circuit_breaker"],"title":"TokenMetricsResponse","description":"Response model for token metrics."},"TokenRefreshResponse":{"properties":{"correlation_id":{"type":"string","title":"Correlation Id","description":"Request correlation ID for tracing"},"refresh_result":{"$ref":"#/components/schemas/RefreshResultDetail"}},"type":"object","required":["correlation_id","refresh_result"],"title":"TokenRefreshResponse","description":"Response model for manual token refresh."},"TokenResponse":{"properties":{"message":{"type":"string","title":"Message"},"token_type":{"type":"string","title":"Token Type"},"expires_in":{"type":"integer","title":"Expires In"}},"type":"object","required":["message","token_type","expires_in"],"title":"TokenResponse","description":"Response model for token authentication."},"TokenServiceHealth":{"properties":{"healthy":{"type":"boolean","title":"Healthy","description":"Overall health status"},"last_refresh":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Refresh","description":"Last successful token refresh"},"token_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Token Expires At","description":"Current token expiration time"},"time_until_expiry_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Time Until Expiry Minutes","description":"Minutes until token expires"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Number of consecutive refresh failures","default":0},"refresh_success_rate_24h":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Refresh Success Rate 24H","description":"24-hour refresh success rate","default":0.0},"average_refresh_latency_ms":{"type":"integer","minimum":0.0,"title":"Average Refresh Latency Ms","description":"Average refresh latency in milliseconds","default":0},"circuit_breaker_status":{"$ref":"#/components/schemas/CircuitBreakerStatus","description":"Circuit breaker status","default":"closed"},"cache_hit_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Cache Hit Rate","description":"Token cache hit rate","default":0.0}},"type":"object","required":["healthy"],"title":"TokenServiceHealth","description":"Pydantic model for token service health status.","example":{"average_refresh_latency_ms":1250,"cache_hit_rate":0.85,"circuit_breaker_status":"closed","consecutive_failures":0,"healthy":true,"last_refresh":"2024-01-15T10:30:00Z","refresh_success_rate_24h":0.98,"time_until_expiry_minutes":25,"token_expires_at":"2024-01-15T11:00:00Z"}},"TokenServiceSummary":{"properties":{"healthy":{"type":"boolean","title":"Healthy","description":"Token service health"},"last_refresh":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Refresh","description":"Last refresh time (ISO 8601)"},"token_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Expires At","description":"Token expiration (ISO 8601)"},"time_until_expiry_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Time Until Expiry Minutes","description":"Minutes until token expires"},"cache_hit_rate":{"type":"number","title":"Cache Hit Rate","description":"Cache hit rate","default":0.0}},"type":"object","required":["healthy"],"title":"TokenServiceSummary","description":"Token service summary for comprehensive health."},"UpdateLookupTableValueRequest":{"properties":{"tableName":{"type":"string","title":"Tablename","description":"Lookup table name"},"oldValue":{"type":"string","title":"Oldvalue","description":"Existing lookup value/code"},"newValue":{"$ref":"#/components/schemas/LookupTableUpdatePayload","description":"New lookup value data"}},"type":"object","required":["tableName","oldValue","newValue"],"title":"UpdateLookupTableValueRequest","description":"Request model for updating a lookup table value."},"UploadAccessRequest":{"properties":{"energy_code":{"type":"string","title":"Energy Code","description":"Energy code requested for upload access"},"distribution_code":{"type":"string","title":"Distribution Code","description":"Distribution code requested for upload access"}},"type":"object","required":["energy_code","distribution_code"],"title":"UploadAccessRequest"},"UploadAccessRequestResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Result message"},"username":{"type":"string","title":"Username","description":"Username that requested access"}},"type":"object","required":["message","username"],"title":"UploadAccessRequestResponse","description":"Response model for upload access request."},"UploadJobAcceptedResponse":{"properties":{"message":{"type":"string","title":"Message"},"jobID":{"type":"string","title":"Jobid"},"status":{"$ref":"#/components/schemas/JobStatus"},"statusUrl":{"type":"string","title":"Statusurl"},"createdDateTime":{"type":"string","title":"Createddatetime"},"warnings":{"anyOf":[{"items":{"$ref":"#/components/schemas/UploadWarning"},"type":"array"},{"type":"null"}],"title":"Warnings","description":"Data-gap / past-data warnings detected during upload, if any"}},"type":"object","required":["message","jobID","status","statusUrl","createdDateTime"],"title":"UploadJobAcceptedResponse","description":"Response returned by POST /api/ValueData for LSE uploads."},"UploadWarning":{"properties":{"_PK0":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pk0","description":"Primary Partition Key"},"_SK0":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sk0","description":"Primary Sort Key"},"_PK1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pk1","description":"GSI1 Partition Key"},"_SK1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sk1","description":"GSI1 Sort Key"},"_PK2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pk2","description":"GSI2 Partition Key"},"_SK2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sk2","description":"GSI2 Sort Key"},"_PK3":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pk3","description":"GSI3 Partition Key"},"_SK3":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sk3","description":"GSI3 Sort Key"},"_PK4":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pk4","description":"GSI4 Partition Key"},"_SK4":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sk4","description":"GSI4 Sort Key"},"_CreatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdat","description":"Creation timestamp"},"_CreatedBy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdby","description":"Username of the creator"},"_ArchivedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archivedat","description":"Archive timestamp"},"code":{"type":"string","title":"Code","description":"Warning code (e.g., 'PAST_DATA', 'DATA_GAP')"},"message":{"type":"string","title":"Message","description":"Human-readable warning message"},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional warning details"}},"type":"object","required":["code","message"],"title":"UploadWarning","description":"Model for upload warnings (MIDAS-014).\nWarnings are informational messages that don't prevent the upload from proceeding."},"UserCreate":{"properties":{"fullname":{"type":"string","title":"Fullname","description":"Base64 encoded full name"},"username":{"type":"string","title":"Username","description":"Base64 encoded username"},"password":{"type":"string","title":"Password","description":"Base64 encoded password"},"emailaddress":{"type":"string","title":"Emailaddress","description":"Base64 encoded email address"},"organization":{"type":"string","title":"Organization","description":"Base64 encoded organization name"}},"type":"object","required":["fullname","username","password","emailaddress","organization"],"title":"UserCreate","description":"Model for user registration data (base64 encoded fields)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBasic":{"type":"http","scheme":"basic"},"HTTPBearer":{"type":"http","scheme":"bearer"}}}}