{"openapi":"3.1.0","info":{"title":"Lottery Feed API","version":"0.1.0","description":"Compact public lottery results API backed by the official-first feed service. Public status and subscription surfaces expose F1-F7 plan delivery levels, with the standard subscription applying the F3 2h delay after feed storage. Reserved lf_sandbox_* tokens and the exact legacy lf_test_demo_sandbox token return deterministic fixtures; lf_dev_* keys use normal development-key authorization and lf_live_* keys are required for live customer data."},"externalDocs":{"description":"API changelog and version policy","url":"https://lotteryfeedapi.com/api-docs/changelog"},"x-lottery-feed-version-policy":{"current_namespace":"/v1","compatibility":"stable compact public read model","changelog_url":"https://lotteryfeedapi.com/api-docs/changelog","breaking_change_policy":"Removing a response field; Changing a response field type; Changing documented status meanings; Tightening required parameters; Changing authentication behavior","non_breaking_change_policy":"Adding optional response fields; Adding enum values with documented fallback behavior; Adding new endpoints; Adding new filters that keep existing defaults stable","deprecation_headers":["Deprecation","Sunset","Link"],"deprecation_link_rel":"deprecation"},"servers":[{"url":"https://api.lotteryfeedapi.com/v1","description":"Configured public API gateway"},{"url":"/v1","description":"Same-origin product app gateway"}],"security":[{"bearerAuth":[]}],"paths":{"/":{"get":{"operationId":"getApiRoot","summary":"Get API version and discovery links","description":"Public version-root response with stable links to API documentation, OpenAPI, and service status.","security":[],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["api_version","documentation","openapi","status"],"properties":{"api_version":{"type":"string","example":"v1"},"documentation":{"type":"string","example":"/api-docs"},"openapi":{"type":"string","example":"/v1/openapi.json"},"status":{"type":"string","example":"/v1/status"}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}}}}},"/results/latest":{"get":{"operationId":"listLatestResults","summary":"List latest draw results with stored numbers","x-required-scopes":["results:read"],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"example":"US"},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"example":"MD"},{"name":"ball_count","in":"query","required":false,"schema":{"type":"integer"},"example":3},{"name":"game_code","in":"query","required":false,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"q","in":"query","required":false,"description":"Case-insensitive public search across lottery names, game codes, states, and country labels where supported.","schema":{"type":"string"},"example":"Pick 3"},{"name":"include","in":"query","required":false,"description":"Optional comma-separated public projection. Use include=trust, include=trust_evidence, or include=provenance_timeline to add bounded public trust_evidence. Use include=mismatch_timeline, include=observer_mismatch, or include=source_comparison to add a customer-safe source comparison timeline. Raw source diagnostics are never included.","schema":{"type":"string","example":"trust,mismatch_timeline"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"title":"PublicDrawList","type":"object","required":["filters","count","returned_count","total_count","limit","has_more","data"],"properties":{"generated_at":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","example":2,"description":"Backward-compatible alias for returned_count."},"returned_count":{"type":"integer","example":2,"description":"Number of rows returned in this response after applying limit."},"total_count":{"type":"integer","example":27,"description":"Total rows available after filters and access rules before applying limit."},"limit":{"type":"integer","example":100,"description":"Maximum rows requested or applied by the endpoint."},"has_more":{"type":"boolean","example":true,"description":"True when total_count is greater than returned_count."},"data":{"type":"array","items":{"type":"object","required":["game_code","name","state","state_code","country","numbers","numbers_formatted","numbers_string","source_confidence","provenance","links"],"properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"name":{"type":"string","example":"Maryland Pick 3 Midday"},"state":{"type":"string","example":"Maryland"},"state_code":{"type":"string","example":"MD"},"country":{"type":"string","example":"US"},"ball_count":{"type":"integer","example":3},"draw_date":{"type":"string","format":"date","example":"2026-05-25"},"numbers":{"type":"array","items":{"type":"string"},"example":["6","2","3"]},"numbers_formatted":{"type":"string","example":"6-2-3"},"numbers_string":{"type":"string","example":"6-2-3"},"source":{"type":"string","example":"mdlottery.com"},"status":{"type":"string","example":"official"},"fetched_at":{"type":"string","format":"date-time"},"inserted_at":{"type":"string","format":"date-time"},"source_confidence":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"provenance":{"type":"object","description":"Compact customer-visible provenance summary with reviewed source labels and roles.","required":["label","role","display"],"properties":{"label":{"type":"string","example":"Maryland Lottery"},"role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"source":{"type":"string","example":"mdlottery.com"},"provider":{"type":"string","example":"mdlottery.com"},"display":{"type":"string","example":"mdlottery.com published this result."}}},"correction":{"type":"object","description":"Compact customer-visible correction evidence.","required":["label","description"],"properties":{"label":{"type":"string","example":"Corrected numbers"},"description":{"type":"string","example":"A previous customer-visible number set (2-3-5) is recorded for this draw."},"corrected_at":{"type":"string","format":"date-time"},"corrected_by":{"type":"string","example":"Operator review"},"previous_numbers":{"type":"array","items":{"type":"string"},"example":["2","3","5"]},"previous_numbers_formatted":{"type":"string","example":"2-3-5"},"version_count":{"type":"integer","example":2},"reason":{"type":"string","example":"Official correction received after initial publication."}}},"trust_evidence":{"type":"object","description":"Optional bounded trust timeline returned when include=trust, include=trust_evidence, or include=provenance_timeline is requested.","required":["summary","publicSource","sourceCheckedLabel","addedToFeedLabel","metrics","timeline"],"properties":{"summary":{"type":"object","required":["label","headline","description"],"properties":{"label":{"type":"string","example":"Official provenance"},"headline":{"type":"string","example":"Official-source result"},"description":{"type":"string"}}},"publicSource":{"type":"string","example":"mdlottery.com"},"sourceCheckedLabel":{"type":"string","example":"Jun 21, 2026, 12:00 PM UTC"},"addedToFeedLabel":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"metrics":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","example":"Confidence label"},"value":{"type":"string","example":"Official source"}}}},"timeline":{"type":"array","maxItems":4,"items":{"type":"object","required":["label","value","caption","status"],"properties":{"label":{"type":"string","example":"Result stored"},"value":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"caption":{"type":"string"},"status":{"type":"string","enum":["ready","pending","reviewed"],"example":"ready"}}}}}},"mismatch_timeline":{"type":"object","description":"Optional bounded source comparison timeline returned only when include=mismatch_timeline, include=observer_mismatch, or include=source_comparison is requested. Default responses omit it.","required":["available","stored_numbers_formatted","current_confidence","summary","review_state","events"],"properties":{"available":{"type":"boolean","example":true},"draw_date":{"type":"string","format":"date","example":"2026-06-24"},"game_code":{"type":"string","example":"md-pick3-midday"},"stored_numbers_formatted":{"type":"string","example":"2-3-6"},"current_confidence":{"type":"object","required":["level","label"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"verified"},"label":{"type":"string","example":"Verified source"}}},"summary":{"type":"object","required":["class","label","decision","customer_action"],"properties":{"class":{"type":"string","enum":["manual_correction","fallback_approved","observer_disagreement","official_blocked_observer_seen"],"example":"observer_disagreement"},"label":{"type":"string","example":"Observer disagreement"},"decision":{"type":"string","example":"Stored result kept after public review evidence"},"customer_action":{"type":"string"}}},"review_state":{"type":"object","description":"Compact public review state derived from confidence, correction, and fallback classification.","required":["state","label","public_note"],"properties":{"state":{"type":"string","enum":["operator_reviewed","approved_fallback","observer_only","review_recorded"],"example":"operator_reviewed"},"label":{"type":"string","example":"Operator review completed"},"public_note":{"type":"string"}}},"events":{"type":"array","maxItems":6,"items":{"type":"object","required":["type","label","source_role"],"properties":{"type":{"type":"string","enum":["stored_result","previous_public_result","observer_seen","observer_disagreed","fallback_approved","source_arrival","review_recorded","operator_reviewed"],"example":"observer_disagreed"},"label":{"type":"string","example":"Observer reported different numbers"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"numbers_formatted":{"type":"string","example":"8-1-2"},"occurred_at":{"type":"string","format":"date-time"},"decision":{"type":"string"}}}},"source_arrivals":{"type":"array","maxItems":6,"description":"Optional bounded source-arrival comparison rows with labels, roles, numbers, and first-seen timestamps.","items":{"type":"object","required":["source_label","source_role","status"],"properties":{"source_label":{"type":"string","example":"Magayo"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"status":{"type":"string","enum":["matches_stored","differs_from_stored","stale_draw","unclassified"],"example":"differs_from_stored"},"numbers_formatted":{"type":"string","example":"8-1-2"},"observed_draw_date":{"type":"string","format":"date","example":"2026-06-24"},"first_seen_at":{"type":"string","format":"date-time"}}}}}},"links":{"type":"object","description":"Compact customer navigation links for public pages and API follow-up requests.","required":["canonical","lottery","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"},"lottery":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/results/latest/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/results"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday&date=2026-05-25"},"history":{"type":"string","example":"/v1/results/history?date=2026-05-25&game_code=md-pick3-midday"},"history_page":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"}}}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter or request body."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/results/latest/{game_code}":{"get":{"operationId":"getLatestResult","summary":"Get latest result for one lottery","x-required-scopes":["results:read"],"parameters":[{"name":"game_code","in":"path","required":true,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"include","in":"query","required":false,"description":"Optional comma-separated public projection. Use include=trust, include=trust_evidence, or include=provenance_timeline to add bounded public trust_evidence. Use include=mismatch_timeline, include=observer_mismatch, or include=source_comparison to add a customer-safe source comparison timeline. Raw source diagnostics are never included.","schema":{"type":"string","example":"trust,mismatch_timeline"}},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["game_code","name","state","state_code","country","numbers","numbers_formatted","numbers_string","source_confidence","provenance","links"],"properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"name":{"type":"string","example":"Maryland Pick 3 Midday"},"state":{"type":"string","example":"Maryland"},"state_code":{"type":"string","example":"MD"},"country":{"type":"string","example":"US"},"ball_count":{"type":"integer","example":3},"draw_date":{"type":"string","format":"date","example":"2026-05-25"},"numbers":{"type":"array","items":{"type":"string"},"example":["6","2","3"]},"numbers_formatted":{"type":"string","example":"6-2-3"},"numbers_string":{"type":"string","example":"6-2-3"},"source":{"type":"string","example":"mdlottery.com"},"status":{"type":"string","example":"official"},"fetched_at":{"type":"string","format":"date-time"},"inserted_at":{"type":"string","format":"date-time"},"source_confidence":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"provenance":{"type":"object","description":"Compact customer-visible provenance summary with reviewed source labels and roles.","required":["label","role","display"],"properties":{"label":{"type":"string","example":"Maryland Lottery"},"role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"source":{"type":"string","example":"mdlottery.com"},"provider":{"type":"string","example":"mdlottery.com"},"display":{"type":"string","example":"mdlottery.com published this result."}}},"correction":{"type":"object","description":"Compact customer-visible correction evidence.","required":["label","description"],"properties":{"label":{"type":"string","example":"Corrected numbers"},"description":{"type":"string","example":"A previous customer-visible number set (2-3-5) is recorded for this draw."},"corrected_at":{"type":"string","format":"date-time"},"corrected_by":{"type":"string","example":"Operator review"},"previous_numbers":{"type":"array","items":{"type":"string"},"example":["2","3","5"]},"previous_numbers_formatted":{"type":"string","example":"2-3-5"},"version_count":{"type":"integer","example":2},"reason":{"type":"string","example":"Official correction received after initial publication."}}},"trust_evidence":{"type":"object","description":"Optional bounded trust timeline returned when include=trust, include=trust_evidence, or include=provenance_timeline is requested.","required":["summary","publicSource","sourceCheckedLabel","addedToFeedLabel","metrics","timeline"],"properties":{"summary":{"type":"object","required":["label","headline","description"],"properties":{"label":{"type":"string","example":"Official provenance"},"headline":{"type":"string","example":"Official-source result"},"description":{"type":"string"}}},"publicSource":{"type":"string","example":"mdlottery.com"},"sourceCheckedLabel":{"type":"string","example":"Jun 21, 2026, 12:00 PM UTC"},"addedToFeedLabel":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"metrics":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","example":"Confidence label"},"value":{"type":"string","example":"Official source"}}}},"timeline":{"type":"array","maxItems":4,"items":{"type":"object","required":["label","value","caption","status"],"properties":{"label":{"type":"string","example":"Result stored"},"value":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"caption":{"type":"string"},"status":{"type":"string","enum":["ready","pending","reviewed"],"example":"ready"}}}}}},"mismatch_timeline":{"type":"object","description":"Optional bounded source comparison timeline returned only when include=mismatch_timeline, include=observer_mismatch, or include=source_comparison is requested. Default responses omit it.","required":["available","stored_numbers_formatted","current_confidence","summary","review_state","events"],"properties":{"available":{"type":"boolean","example":true},"draw_date":{"type":"string","format":"date","example":"2026-06-24"},"game_code":{"type":"string","example":"md-pick3-midday"},"stored_numbers_formatted":{"type":"string","example":"2-3-6"},"current_confidence":{"type":"object","required":["level","label"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"verified"},"label":{"type":"string","example":"Verified source"}}},"summary":{"type":"object","required":["class","label","decision","customer_action"],"properties":{"class":{"type":"string","enum":["manual_correction","fallback_approved","observer_disagreement","official_blocked_observer_seen"],"example":"observer_disagreement"},"label":{"type":"string","example":"Observer disagreement"},"decision":{"type":"string","example":"Stored result kept after public review evidence"},"customer_action":{"type":"string"}}},"review_state":{"type":"object","description":"Compact public review state derived from confidence, correction, and fallback classification.","required":["state","label","public_note"],"properties":{"state":{"type":"string","enum":["operator_reviewed","approved_fallback","observer_only","review_recorded"],"example":"operator_reviewed"},"label":{"type":"string","example":"Operator review completed"},"public_note":{"type":"string"}}},"events":{"type":"array","maxItems":6,"items":{"type":"object","required":["type","label","source_role"],"properties":{"type":{"type":"string","enum":["stored_result","previous_public_result","observer_seen","observer_disagreed","fallback_approved","source_arrival","review_recorded","operator_reviewed"],"example":"observer_disagreed"},"label":{"type":"string","example":"Observer reported different numbers"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"numbers_formatted":{"type":"string","example":"8-1-2"},"occurred_at":{"type":"string","format":"date-time"},"decision":{"type":"string"}}}},"source_arrivals":{"type":"array","maxItems":6,"description":"Optional bounded source-arrival comparison rows with labels, roles, numbers, and first-seen timestamps.","items":{"type":"object","required":["source_label","source_role","status"],"properties":{"source_label":{"type":"string","example":"Magayo"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"status":{"type":"string","enum":["matches_stored","differs_from_stored","stale_draw","unclassified"],"example":"differs_from_stored"},"numbers_formatted":{"type":"string","example":"8-1-2"},"observed_draw_date":{"type":"string","format":"date","example":"2026-06-24"},"first_seen_at":{"type":"string","format":"date-time"}}}}}},"links":{"type":"object","description":"Compact customer navigation links for public pages and API follow-up requests.","required":["canonical","lottery","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"},"lottery":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/results/latest/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/results"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday&date=2026-05-25"},"history":{"type":"string","example":"/v1/results/history?date=2026-05-25&game_code=md-pick3-midday"},"history_page":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter or request body."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"404":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/results/history":{"get":{"operationId":"listHistoricalResults","summary":"List historical draw results for a date","x-required-scopes":["results:read"],"parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-05-25"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"example":"US"},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"example":"MD"},{"name":"ball_count","in":"query","required":false,"schema":{"type":"integer"},"example":3},{"name":"game_code","in":"query","required":false,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"q","in":"query","required":false,"description":"Case-insensitive public search across lottery names, game codes, states, and country labels where supported.","schema":{"type":"string"},"example":"Pick 3"},{"name":"include","in":"query","required":false,"description":"Optional comma-separated public projection. Use include=trust, include=trust_evidence, or include=provenance_timeline to add bounded public trust_evidence. Use include=mismatch_timeline, include=observer_mismatch, or include=source_comparison to add a customer-safe source comparison timeline. Raw source diagnostics are never included.","schema":{"type":"string","example":"trust,mismatch_timeline"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"title":"PublicDrawHistoryList","type":"object","required":["filters","count","returned_count","total_count","limit","has_more","data"],"properties":{"generated_at":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","example":2,"description":"Backward-compatible alias for returned_count."},"returned_count":{"type":"integer","example":2,"description":"Number of rows returned in this response after applying limit."},"total_count":{"type":"integer","example":27,"description":"Total rows available after filters and access rules before applying limit."},"limit":{"type":"integer","example":100,"description":"Maximum rows requested or applied by the endpoint."},"has_more":{"type":"boolean","example":true,"description":"True when total_count is greater than returned_count."},"data":{"type":"array","items":{"type":"object","required":["game_code","name","state","state_code","country","numbers","numbers_formatted","numbers_string","source_confidence","provenance","links"],"properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"name":{"type":"string","example":"Maryland Pick 3 Midday"},"state":{"type":"string","example":"Maryland"},"state_code":{"type":"string","example":"MD"},"country":{"type":"string","example":"US"},"ball_count":{"type":"integer","example":3},"draw_date":{"type":"string","format":"date","example":"2026-05-25"},"numbers":{"type":"array","items":{"type":"string"},"example":["6","2","3"]},"numbers_formatted":{"type":"string","example":"6-2-3"},"numbers_string":{"type":"string","example":"6-2-3"},"source":{"type":"string","example":"mdlottery.com"},"status":{"type":"string","example":"official"},"fetched_at":{"type":"string","format":"date-time"},"inserted_at":{"type":"string","format":"date-time"},"source_confidence":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"provenance":{"type":"object","description":"Compact customer-visible provenance summary with reviewed source labels and roles.","required":["label","role","display"],"properties":{"label":{"type":"string","example":"Maryland Lottery"},"role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"source":{"type":"string","example":"mdlottery.com"},"provider":{"type":"string","example":"mdlottery.com"},"display":{"type":"string","example":"mdlottery.com published this result."}}},"correction":{"type":"object","description":"Compact customer-visible correction evidence.","required":["label","description"],"properties":{"label":{"type":"string","example":"Corrected numbers"},"description":{"type":"string","example":"A previous customer-visible number set (2-3-5) is recorded for this draw."},"corrected_at":{"type":"string","format":"date-time"},"corrected_by":{"type":"string","example":"Operator review"},"previous_numbers":{"type":"array","items":{"type":"string"},"example":["2","3","5"]},"previous_numbers_formatted":{"type":"string","example":"2-3-5"},"version_count":{"type":"integer","example":2},"reason":{"type":"string","example":"Official correction received after initial publication."}}},"trust_evidence":{"type":"object","description":"Optional bounded trust timeline returned when include=trust, include=trust_evidence, or include=provenance_timeline is requested.","required":["summary","publicSource","sourceCheckedLabel","addedToFeedLabel","metrics","timeline"],"properties":{"summary":{"type":"object","required":["label","headline","description"],"properties":{"label":{"type":"string","example":"Official provenance"},"headline":{"type":"string","example":"Official-source result"},"description":{"type":"string"}}},"publicSource":{"type":"string","example":"mdlottery.com"},"sourceCheckedLabel":{"type":"string","example":"Jun 21, 2026, 12:00 PM UTC"},"addedToFeedLabel":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"metrics":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","example":"Confidence label"},"value":{"type":"string","example":"Official source"}}}},"timeline":{"type":"array","maxItems":4,"items":{"type":"object","required":["label","value","caption","status"],"properties":{"label":{"type":"string","example":"Result stored"},"value":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"caption":{"type":"string"},"status":{"type":"string","enum":["ready","pending","reviewed"],"example":"ready"}}}}}},"mismatch_timeline":{"type":"object","description":"Optional bounded source comparison timeline returned only when include=mismatch_timeline, include=observer_mismatch, or include=source_comparison is requested. Default responses omit it.","required":["available","stored_numbers_formatted","current_confidence","summary","review_state","events"],"properties":{"available":{"type":"boolean","example":true},"draw_date":{"type":"string","format":"date","example":"2026-06-24"},"game_code":{"type":"string","example":"md-pick3-midday"},"stored_numbers_formatted":{"type":"string","example":"2-3-6"},"current_confidence":{"type":"object","required":["level","label"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"verified"},"label":{"type":"string","example":"Verified source"}}},"summary":{"type":"object","required":["class","label","decision","customer_action"],"properties":{"class":{"type":"string","enum":["manual_correction","fallback_approved","observer_disagreement","official_blocked_observer_seen"],"example":"observer_disagreement"},"label":{"type":"string","example":"Observer disagreement"},"decision":{"type":"string","example":"Stored result kept after public review evidence"},"customer_action":{"type":"string"}}},"review_state":{"type":"object","description":"Compact public review state derived from confidence, correction, and fallback classification.","required":["state","label","public_note"],"properties":{"state":{"type":"string","enum":["operator_reviewed","approved_fallback","observer_only","review_recorded"],"example":"operator_reviewed"},"label":{"type":"string","example":"Operator review completed"},"public_note":{"type":"string"}}},"events":{"type":"array","maxItems":6,"items":{"type":"object","required":["type","label","source_role"],"properties":{"type":{"type":"string","enum":["stored_result","previous_public_result","observer_seen","observer_disagreed","fallback_approved","source_arrival","review_recorded","operator_reviewed"],"example":"observer_disagreed"},"label":{"type":"string","example":"Observer reported different numbers"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"numbers_formatted":{"type":"string","example":"8-1-2"},"occurred_at":{"type":"string","format":"date-time"},"decision":{"type":"string"}}}},"source_arrivals":{"type":"array","maxItems":6,"description":"Optional bounded source-arrival comparison rows with labels, roles, numbers, and first-seen timestamps.","items":{"type":"object","required":["source_label","source_role","status"],"properties":{"source_label":{"type":"string","example":"Magayo"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"status":{"type":"string","enum":["matches_stored","differs_from_stored","stale_draw","unclassified"],"example":"differs_from_stored"},"numbers_formatted":{"type":"string","example":"8-1-2"},"observed_draw_date":{"type":"string","format":"date","example":"2026-06-24"},"first_seen_at":{"type":"string","format":"date-time"}}}}}},"links":{"type":"object","description":"Compact customer navigation links for public pages and API follow-up requests.","required":["canonical","lottery","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"},"lottery":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/results/latest/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/results"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday&date=2026-05-25"},"history":{"type":"string","example":"/v1/results/history?date=2026-05-25&game_code=md-pick3-midday"},"history_page":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"}}}}}},"history_snapshot":{"type":"object","description":"Compact history provenance identifying a stable stored snapshot, reviewed fallback snapshot, sandbox fixture, or empty date.","required":["kind","archived","cache_hint"],"properties":{"kind":{"type":"string","enum":["archive_snapshot","stored_fallback","sandbox_fixture","empty"],"example":"archive_snapshot"},"draw_date":{"type":"string","format":"date","example":"2026-06-21"},"archived":{"type":"boolean","example":true},"fetched_at":{"type":"string","format":"date-time","example":"2026-06-22T11:00:00.000Z"},"generated_at":{"type":"string","format":"date-time","example":"2026-06-21T12:00:00.000Z"},"draw_count":{"type":"integer","example":42},"cache_hint":{"type":"string","example":"Stable published history snapshot. Safe for customer-side date caching until the next published correction."}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/results/check":{"post":{"operationId":"checkLotteryResult","summary":"Check submitted numbers against one stored draw","x-required-scopes":["results:read"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["game_code","draw_date","numbers"],"properties":{"game_code":{"type":"string"},"draw_date":{"type":"string","format":"date"},"numbers":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":16}}}}}}},"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"boolean"},"match_count":{"type":"integer","description":"Count of submitted numbers that match the winning number in the same position."},"number_match_count":{"type":"integer","description":"Count of submitted numbers that appear in the winning numbers, ignoring order and respecting duplicates."},"match_class":{"type":"string","enum":["exact_order","all_numbers_any_order","partial_position","partial_numbers","no_match","no_visible_draw"]},"match_summary":{"type":"string"},"disclaimer":{"type":"string"},"game_code":{"type":"string"},"draw_date":{"type":"string","format":"date"},"submitted_numbers":{"type":"array","items":{"type":"string"}},"submitted_numbers_formatted":{"type":"string","description":"Submitted numbers joined with hyphens for display and idempotent customer logs.","example":"6-2-3"},"winning_numbers":{"type":"array","items":{"type":"string"}},"winning_numbers_formatted":{"type":"string","description":"Stored winning numbers joined with hyphens. Empty when no visible draw is available.","example":"6-2-3"}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"411":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"LENGTH_REQUIRED"},"message":{"type":"string","example":"A Content-Length header is required for this request."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"413":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"PAYLOAD_TOO_LARGE"},"message":{"type":"string","example":"Request body exceeds the supported size."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/lotteries":{"get":{"operationId":"listLotteries","summary":"List customer-visible lotteries with latest numbers","x-required-scopes":["lotteries:read"],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"example":"US"},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"example":"MD"},{"name":"ball_count","in":"query","required":false,"schema":{"type":"integer"},"example":3},{"name":"game_code","in":"query","required":false,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"q","in":"query","required":false,"description":"Case-insensitive public search across lottery names, game codes, states, and country labels where supported.","schema":{"type":"string"},"example":"Pick 3"},{"name":"include","in":"query","required":false,"description":"Optional comma-separated public projection. Use include=trust, include=trust_evidence, or include=provenance_timeline to add bounded public trust_evidence. Use include=mismatch_timeline, include=observer_mismatch, or include=source_comparison to add a customer-safe source comparison timeline. Use include=prize_structure_coverage, include=prize_coverage, or include=prize_status to add compact source-review status for prize tables without payout rows. Use include=jackpot_status, include=jackpot_coverage, or include=jackpot_tracking to add compact jackpot source-review status without jackpot amount values. Raw source diagnostics are never included.","schema":{"type":"string","example":"prize_structure_coverage,jackpot_status"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"title":"PublicLotteryList","type":"object","required":["filters","count","returned_count","total_count","limit","has_more","data"],"properties":{"generated_at":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","example":2,"description":"Backward-compatible alias for returned_count."},"returned_count":{"type":"integer","example":2,"description":"Number of rows returned in this response after applying limit."},"total_count":{"type":"integer","example":27,"description":"Total rows available after filters and access rules before applying limit."},"limit":{"type":"integer","example":100,"description":"Maximum rows requested or applied by the endpoint."},"has_more":{"type":"boolean","example":true,"description":"True when total_count is greater than returned_count."},"data":{"type":"array","items":{"type":"object","required":["game_code","name","state","state_code","country","links","latest_draw_availability"],"properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"name":{"type":"string","example":"Maryland Pick 3 Midday"},"state":{"type":"string","example":"Maryland"},"state_code":{"type":"string","example":"MD"},"country":{"type":"string","example":"US"},"ball_count":{"type":"integer","example":3},"links":{"type":"object","description":"Compact customer navigation links for catalog pages and lottery metadata API calls.","required":["canonical","latest_result","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/lotteries/md-pick3-midday"},"latest_result":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/lotteries/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/lotteries"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday"}}},"draw_schedule":{"type":"object","description":"Compact public draw schedule summary. Timezone IDs are preserved when known so clients can handle DST correctly.","properties":{"local_time":{"type":"string","example":"12:27 PM ET"},"utc_time":{"type":"string","example":"16:27 UTC"},"days":{"type":"string","example":"Every day"},"description":{"type":"string","example":"Every day. On Sunday, only the evening draw runs."},"timezone":{"type":"string","example":"America/New_York"},"next_draw":{"type":"object","description":"Next scheduled draw derived from normalized schedule metadata. Dates are local to the lottery timezone; UTC fields support timezone-safe integrations.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"local_time":{"type":"string","example":"6:28 PM CDT"},"utc_time":{"type":"string","example":"23:28 UTC"},"local_datetime":{"type":"string","example":"2026-06-21T18:28:00"},"utc_datetime":{"type":"string","format":"date-time","example":"2026-06-21T23:28:00Z"},"timezone":{"type":"string","example":"America/Chicago"},"days_until":{"type":"integer","example":0},"polling_window":{"type":"object","description":"Recommended bounded result-check window derived from scheduled draw time. It is a polling hint, not proof that the official result is published.","properties":{"first_check_after_utc":{"type":"string","format":"date-time","example":"2026-06-21T23:38:00Z"},"retry_until_utc":{"type":"string","format":"date-time","example":"2026-06-22T01:28:00Z"},"first_check_delay_minutes":{"type":"integer","example":10},"retry_window_minutes":{"type":"integer","example":120},"label":{"type":"string","example":"Start result checks at 2026-06-21T23:38:00Z; keep retries bounded until 2026-06-22T01:28:00Z unless your plan or source policy says otherwise."}}},"label":{"type":"string","example":"Next scheduled draw on Sunday, June 21, 2026 at 6:28 PM CDT (23:28 UTC)."}}},"note":{"type":"string","example":"On Sunday, only the evening draw runs."},"source":{"type":"object","properties":{"label":{"type":"string","example":"Maryland Lottery rules"},"url":{"type":"string","format":"uri","example":"https://www.mdlottery.com/"}}}}},"date_context":{"type":"object","description":"Present when date=YYYY-MM-DD is supplied. Status is derived from normalized public schedule text when safe.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"status":{"type":"string","enum":["scheduled","not_scheduled","unknown"],"example":"scheduled"},"label":{"type":"string","example":"Scheduled on Sunday. Every day. On Sunday, only the evening draw runs."}}},"next_draw":{"type":"object","description":"Next scheduled draw derived from normalized schedule metadata. Dates are local to the lottery timezone; UTC fields support timezone-safe integrations.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"local_time":{"type":"string","example":"6:28 PM CDT"},"utc_time":{"type":"string","example":"23:28 UTC"},"local_datetime":{"type":"string","example":"2026-06-21T18:28:00"},"utc_datetime":{"type":"string","format":"date-time","example":"2026-06-21T23:28:00Z"},"timezone":{"type":"string","example":"America/Chicago"},"days_until":{"type":"integer","example":0},"polling_window":{"type":"object","description":"Recommended bounded result-check window derived from scheduled draw time. It is a polling hint, not proof that the official result is published.","properties":{"first_check_after_utc":{"type":"string","format":"date-time","example":"2026-06-21T23:38:00Z"},"retry_until_utc":{"type":"string","format":"date-time","example":"2026-06-22T01:28:00Z"},"first_check_delay_minutes":{"type":"integer","example":10},"retry_window_minutes":{"type":"integer","example":120},"label":{"type":"string","example":"Start result checks at 2026-06-21T23:38:00Z; keep retries bounded until 2026-06-22T01:28:00Z unless your plan or source policy says otherwise."}}},"label":{"type":"string","example":"Next scheduled draw on Sunday, June 21, 2026 at 6:28 PM CDT (23:28 UTC)."}}},"prize_structure_coverage":{"type":"object","description":"Compact prize-structure source-review coverage returned with include=prize_structure_coverage. This summary is safe for catalog/list responses and never includes payout rows.","required":["status","label","summary","guidance","include","prize_table_include"],"properties":{"status":{"type":"string","enum":["source_reviewed","not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Prize structure publication pending"},"summary":{"type":"string","example":"Prize rows remain hidden until amounts use an explicit currency and scale and the source evidence is approved for public publication."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["Use published results, history, schedules, and source-confidence metadata while prize publication is pending."]},"include":{"type":"string","enum":["prize_structure_coverage"],"example":"prize_structure_coverage"},"prize_table_include":{"type":"string","enum":["prize_structure"],"example":"prize_structure"},"reviewed_at":{"type":"string","format":"date","example":"2026-06-25"},"source":{"type":"object","properties":{"label":{"type":"string","example":"Tennessee Lottery Cash 3 rules"},"url":{"type":"string","format":"uri","example":"https://tnlottery.com/games/how-to-play/cash3/"}}},"row_count":{"type":"integer","example":9}}},"prize_structure_notice":{"type":"object","description":"Compact notice returned with include=prize_structure when a source-reviewed prize table is not available. No payout guesses are included.","required":["status","label","summary","guidance","include"],"properties":{"status":{"type":"string","enum":["not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Prize structure not source-reviewed yet"},"summary":{"type":"string","example":"Lottery Feed API hides prize tables until the official rules are checked, dated, and reviewed for payout-safe customer display."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["Do not infer prizes from another state, another draw game, or a third-party summary."]},"include":{"type":"string","enum":["prize_structure"],"example":"prize_structure"}}},"jackpot_coverage":{"type":"object","description":"Compact jackpot source-review coverage returned with include=jackpot_status, include=jackpot_coverage, or include=jackpot_tracking. No jackpot amount rows are included.","required":["status","label","summary","guidance","include","jackpot_include"],"properties":{"status":{"type":"string","enum":["not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Jackpot tracking not source-reviewed yet"},"summary":{"type":"string","example":"New York Lotto jackpot values are hidden until an official jackpot source, source timestamp, amount, currency, and rollover semantics are reviewed."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["Do not infer jackpot amounts from a result feed, third-party summary, another draw game, or another jurisdiction."]},"include":{"type":"string","enum":["jackpot_status"],"example":"jackpot_status"},"jackpot_include":{"type":"string","enum":["jackpot"],"example":"jackpot"}}},"jackpot_notice":{"type":"object","description":"Compact notice returned with include=jackpot when source-reviewed jackpot tracking is not available. No jackpot amount, currency, rollover, or timestamp values are included.","required":["status","label","summary","guidance","include"],"properties":{"status":{"type":"string","enum":["not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Jackpot not source-reviewed yet"},"summary":{"type":"string","example":"New York Lotto jackpot tracking is not enabled until official jackpot evidence is reviewed and dated."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["No jackpot amount, currency, rollover, cash-value, or annuity fields are available for this game."]},"include":{"type":"string","enum":["jackpot"],"example":"jackpot"}}},"latest_draw_availability":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["available","not_stored","delayed_for_access","unavailable_for_access"]},"message":{"type":"string"},"available_after":{"type":["string","null"],"format":"date-time"}}},"latest_draw":{"type":"object","properties":{"draw_date":{"type":"string","format":"date"},"numbers":{"type":"array","items":{"type":"string"}},"numbers_formatted":{"type":"string","example":"6-2-3"},"numbers_string":{"type":"string","example":"6-2-3"},"source":{"type":"string"},"status":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"inserted_at":{"type":"string","format":"date-time"},"source_confidence":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"provenance":{"type":"object","description":"Compact customer-visible provenance summary with reviewed source labels and roles.","required":["label","role","display"],"properties":{"label":{"type":"string","example":"Maryland Lottery"},"role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"source":{"type":"string","example":"mdlottery.com"},"provider":{"type":"string","example":"mdlottery.com"},"display":{"type":"string","example":"mdlottery.com published this result."}}},"correction":{"type":"object","description":"Compact customer-visible correction evidence.","required":["label","description"],"properties":{"label":{"type":"string","example":"Corrected numbers"},"description":{"type":"string","example":"A previous customer-visible number set (2-3-5) is recorded for this draw."},"corrected_at":{"type":"string","format":"date-time"},"corrected_by":{"type":"string","example":"Operator review"},"previous_numbers":{"type":"array","items":{"type":"string"},"example":["2","3","5"]},"previous_numbers_formatted":{"type":"string","example":"2-3-5"},"version_count":{"type":"integer","example":2},"reason":{"type":"string","example":"Official correction received after initial publication."}}},"trust_evidence":{"type":"object","description":"Optional bounded trust timeline returned when include=trust, include=trust_evidence, or include=provenance_timeline is requested.","required":["summary","publicSource","sourceCheckedLabel","addedToFeedLabel","metrics","timeline"],"properties":{"summary":{"type":"object","required":["label","headline","description"],"properties":{"label":{"type":"string","example":"Official provenance"},"headline":{"type":"string","example":"Official-source result"},"description":{"type":"string"}}},"publicSource":{"type":"string","example":"mdlottery.com"},"sourceCheckedLabel":{"type":"string","example":"Jun 21, 2026, 12:00 PM UTC"},"addedToFeedLabel":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"metrics":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","example":"Confidence label"},"value":{"type":"string","example":"Official source"}}}},"timeline":{"type":"array","maxItems":4,"items":{"type":"object","required":["label","value","caption","status"],"properties":{"label":{"type":"string","example":"Result stored"},"value":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"caption":{"type":"string"},"status":{"type":"string","enum":["ready","pending","reviewed"],"example":"ready"}}}}}},"mismatch_timeline":{"type":"object","description":"Optional bounded source comparison timeline returned only when include=mismatch_timeline, include=observer_mismatch, or include=source_comparison is requested. Default responses omit it.","required":["available","stored_numbers_formatted","current_confidence","summary","review_state","events"],"properties":{"available":{"type":"boolean","example":true},"draw_date":{"type":"string","format":"date","example":"2026-06-24"},"game_code":{"type":"string","example":"md-pick3-midday"},"stored_numbers_formatted":{"type":"string","example":"2-3-6"},"current_confidence":{"type":"object","required":["level","label"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"verified"},"label":{"type":"string","example":"Verified source"}}},"summary":{"type":"object","required":["class","label","decision","customer_action"],"properties":{"class":{"type":"string","enum":["manual_correction","fallback_approved","observer_disagreement","official_blocked_observer_seen"],"example":"observer_disagreement"},"label":{"type":"string","example":"Observer disagreement"},"decision":{"type":"string","example":"Stored result kept after public review evidence"},"customer_action":{"type":"string"}}},"review_state":{"type":"object","description":"Compact public review state derived from confidence, correction, and fallback classification.","required":["state","label","public_note"],"properties":{"state":{"type":"string","enum":["operator_reviewed","approved_fallback","observer_only","review_recorded"],"example":"operator_reviewed"},"label":{"type":"string","example":"Operator review completed"},"public_note":{"type":"string"}}},"events":{"type":"array","maxItems":6,"items":{"type":"object","required":["type","label","source_role"],"properties":{"type":{"type":"string","enum":["stored_result","previous_public_result","observer_seen","observer_disagreed","fallback_approved","source_arrival","review_recorded","operator_reviewed"],"example":"observer_disagreed"},"label":{"type":"string","example":"Observer reported different numbers"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"numbers_formatted":{"type":"string","example":"8-1-2"},"occurred_at":{"type":"string","format":"date-time"},"decision":{"type":"string"}}}},"source_arrivals":{"type":"array","maxItems":6,"description":"Optional bounded source-arrival comparison rows with labels, roles, numbers, and first-seen timestamps.","items":{"type":"object","required":["source_label","source_role","status"],"properties":{"source_label":{"type":"string","example":"Magayo"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"status":{"type":"string","enum":["matches_stored","differs_from_stored","stale_draw","unclassified"],"example":"differs_from_stored"},"numbers_formatted":{"type":"string","example":"8-1-2"},"observed_draw_date":{"type":"string","format":"date","example":"2026-06-24"},"first_seen_at":{"type":"string","format":"date-time"}}}}}},"links":{"type":"object","description":"Compact customer navigation links for public pages and API follow-up requests.","required":["canonical","lottery","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"},"lottery":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/results/latest/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/results"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday&date=2026-05-25"},"history":{"type":"string","example":"/v1/results/history?date=2026-05-25&game_code=md-pick3-midday"},"history_page":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"}}}}}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter or request body."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/lotteries/{game_code}":{"get":{"operationId":"getLottery","summary":"Get one lottery","x-required-scopes":["lotteries:read"],"parameters":[{"name":"game_code","in":"path","required":true,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"example":"2026-05-25"},{"name":"include","in":"query","required":false,"description":"Optional comma-separated single-lottery projection. Use include=prize_structure to request publication status; payout rows remain omitted until typed currency, scale, source evidence, and publication approval are available. Use include=prize_structure_coverage / prize_coverage / prize_status for compact status without payout rows, include=jackpot for a no-value jackpot source-review notice, include=jackpot_status / jackpot_coverage / jackpot_tracking for compact jackpot review coverage, include=trust / trust_evidence / provenance_timeline for compact public trust evidence, or include=mismatch_timeline / observer_mismatch / source_comparison for customer-safe source comparison evidence. Default responses stay compact.","schema":{"type":"string","example":"prize_structure_coverage,jackpot_status,mismatch_timeline"}},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["game_code","name","state","state_code","country","links","latest_draw_availability"],"properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"name":{"type":"string","example":"Maryland Pick 3 Midday"},"state":{"type":"string","example":"Maryland"},"state_code":{"type":"string","example":"MD"},"country":{"type":"string","example":"US"},"ball_count":{"type":"integer","example":3},"links":{"type":"object","description":"Compact customer navigation links for catalog pages and lottery metadata API calls.","required":["canonical","latest_result","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/lotteries/md-pick3-midday"},"latest_result":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/lotteries/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/lotteries"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday"}}},"draw_schedule":{"type":"object","description":"Compact public draw schedule summary. Timezone IDs are preserved when known so clients can handle DST correctly.","properties":{"local_time":{"type":"string","example":"12:27 PM ET"},"utc_time":{"type":"string","example":"16:27 UTC"},"days":{"type":"string","example":"Every day"},"description":{"type":"string","example":"Every day. On Sunday, only the evening draw runs."},"timezone":{"type":"string","example":"America/New_York"},"next_draw":{"type":"object","description":"Next scheduled draw derived from normalized schedule metadata. Dates are local to the lottery timezone; UTC fields support timezone-safe integrations.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"local_time":{"type":"string","example":"6:28 PM CDT"},"utc_time":{"type":"string","example":"23:28 UTC"},"local_datetime":{"type":"string","example":"2026-06-21T18:28:00"},"utc_datetime":{"type":"string","format":"date-time","example":"2026-06-21T23:28:00Z"},"timezone":{"type":"string","example":"America/Chicago"},"days_until":{"type":"integer","example":0},"polling_window":{"type":"object","description":"Recommended bounded result-check window derived from scheduled draw time. It is a polling hint, not proof that the official result is published.","properties":{"first_check_after_utc":{"type":"string","format":"date-time","example":"2026-06-21T23:38:00Z"},"retry_until_utc":{"type":"string","format":"date-time","example":"2026-06-22T01:28:00Z"},"first_check_delay_minutes":{"type":"integer","example":10},"retry_window_minutes":{"type":"integer","example":120},"label":{"type":"string","example":"Start result checks at 2026-06-21T23:38:00Z; keep retries bounded until 2026-06-22T01:28:00Z unless your plan or source policy says otherwise."}}},"label":{"type":"string","example":"Next scheduled draw on Sunday, June 21, 2026 at 6:28 PM CDT (23:28 UTC)."}}},"note":{"type":"string","example":"On Sunday, only the evening draw runs."},"source":{"type":"object","properties":{"label":{"type":"string","example":"Maryland Lottery rules"},"url":{"type":"string","format":"uri","example":"https://www.mdlottery.com/"}}}}},"date_context":{"type":"object","description":"Present when date=YYYY-MM-DD is supplied. Status is derived from normalized public schedule text when safe.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"status":{"type":"string","enum":["scheduled","not_scheduled","unknown"],"example":"scheduled"},"label":{"type":"string","example":"Scheduled on Sunday. Every day. On Sunday, only the evening draw runs."}}},"next_draw":{"type":"object","description":"Next scheduled draw derived from normalized schedule metadata. Dates are local to the lottery timezone; UTC fields support timezone-safe integrations.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"local_time":{"type":"string","example":"6:28 PM CDT"},"utc_time":{"type":"string","example":"23:28 UTC"},"local_datetime":{"type":"string","example":"2026-06-21T18:28:00"},"utc_datetime":{"type":"string","format":"date-time","example":"2026-06-21T23:28:00Z"},"timezone":{"type":"string","example":"America/Chicago"},"days_until":{"type":"integer","example":0},"polling_window":{"type":"object","description":"Recommended bounded result-check window derived from scheduled draw time. It is a polling hint, not proof that the official result is published.","properties":{"first_check_after_utc":{"type":"string","format":"date-time","example":"2026-06-21T23:38:00Z"},"retry_until_utc":{"type":"string","format":"date-time","example":"2026-06-22T01:28:00Z"},"first_check_delay_minutes":{"type":"integer","example":10},"retry_window_minutes":{"type":"integer","example":120},"label":{"type":"string","example":"Start result checks at 2026-06-21T23:38:00Z; keep retries bounded until 2026-06-22T01:28:00Z unless your plan or source policy says otherwise."}}},"label":{"type":"string","example":"Next scheduled draw on Sunday, June 21, 2026 at 6:28 PM CDT (23:28 UTC)."}}},"prize_structure_coverage":{"type":"object","description":"Compact prize-structure source-review coverage returned with include=prize_structure_coverage. This summary is safe for catalog/list responses and never includes payout rows.","required":["status","label","summary","guidance","include","prize_table_include"],"properties":{"status":{"type":"string","enum":["source_reviewed","not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Prize structure publication pending"},"summary":{"type":"string","example":"Prize rows remain hidden until amounts use an explicit currency and scale and the source evidence is approved for public publication."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["Use published results, history, schedules, and source-confidence metadata while prize publication is pending."]},"include":{"type":"string","enum":["prize_structure_coverage"],"example":"prize_structure_coverage"},"prize_table_include":{"type":"string","enum":["prize_structure"],"example":"prize_structure"},"reviewed_at":{"type":"string","format":"date","example":"2026-06-25"},"source":{"type":"object","properties":{"label":{"type":"string","example":"Tennessee Lottery Cash 3 rules"},"url":{"type":"string","format":"uri","example":"https://tnlottery.com/games/how-to-play/cash3/"}}},"row_count":{"type":"integer","example":9}}},"prize_structure_notice":{"type":"object","description":"Compact notice returned with include=prize_structure when a source-reviewed prize table is not available. No payout guesses are included.","required":["status","label","summary","guidance","include"],"properties":{"status":{"type":"string","enum":["not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Prize structure not source-reviewed yet"},"summary":{"type":"string","example":"Lottery Feed API hides prize tables until the official rules are checked, dated, and reviewed for payout-safe customer display."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["Do not infer prizes from another state, another draw game, or a third-party summary."]},"include":{"type":"string","enum":["prize_structure"],"example":"prize_structure"}}},"jackpot_coverage":{"type":"object","description":"Compact jackpot source-review coverage returned with include=jackpot_status, include=jackpot_coverage, or include=jackpot_tracking. No jackpot amount rows are included.","required":["status","label","summary","guidance","include","jackpot_include"],"properties":{"status":{"type":"string","enum":["not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Jackpot tracking not source-reviewed yet"},"summary":{"type":"string","example":"New York Lotto jackpot values are hidden until an official jackpot source, source timestamp, amount, currency, and rollover semantics are reviewed."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["Do not infer jackpot amounts from a result feed, third-party summary, another draw game, or another jurisdiction."]},"include":{"type":"string","enum":["jackpot_status"],"example":"jackpot_status"},"jackpot_include":{"type":"string","enum":["jackpot"],"example":"jackpot"}}},"jackpot_notice":{"type":"object","description":"Compact notice returned with include=jackpot when source-reviewed jackpot tracking is not available. No jackpot amount, currency, rollover, or timestamp values are included.","required":["status","label","summary","guidance","include"],"properties":{"status":{"type":"string","enum":["not_source_reviewed"],"example":"not_source_reviewed"},"label":{"type":"string","example":"Jackpot not source-reviewed yet"},"summary":{"type":"string","example":"New York Lotto jackpot tracking is not enabled until official jackpot evidence is reviewed and dated."},"guidance":{"type":"array","maxItems":6,"items":{"type":"string"},"example":["No jackpot amount, currency, rollover, cash-value, or annuity fields are available for this game."]},"include":{"type":"string","enum":["jackpot"],"example":"jackpot"}}},"latest_draw_availability":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["available","not_stored","delayed_for_access","unavailable_for_access"]},"message":{"type":"string"},"available_after":{"type":["string","null"],"format":"date-time"}}},"latest_draw":{"type":"object","properties":{"draw_date":{"type":"string","format":"date"},"numbers":{"type":"array","items":{"type":"string"}},"numbers_formatted":{"type":"string","example":"6-2-3"},"numbers_string":{"type":"string","example":"6-2-3"},"source":{"type":"string"},"status":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"inserted_at":{"type":"string","format":"date-time"},"source_confidence":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"provenance":{"type":"object","description":"Compact customer-visible provenance summary with reviewed source labels and roles.","required":["label","role","display"],"properties":{"label":{"type":"string","example":"Maryland Lottery"},"role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"source":{"type":"string","example":"mdlottery.com"},"provider":{"type":"string","example":"mdlottery.com"},"display":{"type":"string","example":"mdlottery.com published this result."}}},"correction":{"type":"object","description":"Compact customer-visible correction evidence.","required":["label","description"],"properties":{"label":{"type":"string","example":"Corrected numbers"},"description":{"type":"string","example":"A previous customer-visible number set (2-3-5) is recorded for this draw."},"corrected_at":{"type":"string","format":"date-time"},"corrected_by":{"type":"string","example":"Operator review"},"previous_numbers":{"type":"array","items":{"type":"string"},"example":["2","3","5"]},"previous_numbers_formatted":{"type":"string","example":"2-3-5"},"version_count":{"type":"integer","example":2},"reason":{"type":"string","example":"Official correction received after initial publication."}}},"trust_evidence":{"type":"object","description":"Optional bounded trust timeline returned when include=trust, include=trust_evidence, or include=provenance_timeline is requested.","required":["summary","publicSource","sourceCheckedLabel","addedToFeedLabel","metrics","timeline"],"properties":{"summary":{"type":"object","required":["label","headline","description"],"properties":{"label":{"type":"string","example":"Official provenance"},"headline":{"type":"string","example":"Official-source result"},"description":{"type":"string"}}},"publicSource":{"type":"string","example":"mdlottery.com"},"sourceCheckedLabel":{"type":"string","example":"Jun 21, 2026, 12:00 PM UTC"},"addedToFeedLabel":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"metrics":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","example":"Confidence label"},"value":{"type":"string","example":"Official source"}}}},"timeline":{"type":"array","maxItems":4,"items":{"type":"object","required":["label","value","caption","status"],"properties":{"label":{"type":"string","example":"Result stored"},"value":{"type":"string","example":"Jun 21, 2026, 12:01 PM UTC"},"caption":{"type":"string"},"status":{"type":"string","enum":["ready","pending","reviewed"],"example":"ready"}}}}}},"mismatch_timeline":{"type":"object","description":"Optional bounded source comparison timeline returned only when include=mismatch_timeline, include=observer_mismatch, or include=source_comparison is requested. Default responses omit it.","required":["available","stored_numbers_formatted","current_confidence","summary","review_state","events"],"properties":{"available":{"type":"boolean","example":true},"draw_date":{"type":"string","format":"date","example":"2026-06-24"},"game_code":{"type":"string","example":"md-pick3-midday"},"stored_numbers_formatted":{"type":"string","example":"2-3-6"},"current_confidence":{"type":"object","required":["level","label"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"verified"},"label":{"type":"string","example":"Verified source"}}},"summary":{"type":"object","required":["class","label","decision","customer_action"],"properties":{"class":{"type":"string","enum":["manual_correction","fallback_approved","observer_disagreement","official_blocked_observer_seen"],"example":"observer_disagreement"},"label":{"type":"string","example":"Observer disagreement"},"decision":{"type":"string","example":"Stored result kept after public review evidence"},"customer_action":{"type":"string"}}},"review_state":{"type":"object","description":"Compact public review state derived from confidence, correction, and fallback classification.","required":["state","label","public_note"],"properties":{"state":{"type":"string","enum":["operator_reviewed","approved_fallback","observer_only","review_recorded"],"example":"operator_reviewed"},"label":{"type":"string","example":"Operator review completed"},"public_note":{"type":"string"}}},"events":{"type":"array","maxItems":6,"items":{"type":"object","required":["type","label","source_role"],"properties":{"type":{"type":"string","enum":["stored_result","previous_public_result","observer_seen","observer_disagreed","fallback_approved","source_arrival","review_recorded","operator_reviewed"],"example":"observer_disagreed"},"label":{"type":"string","example":"Observer reported different numbers"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"numbers_formatted":{"type":"string","example":"8-1-2"},"occurred_at":{"type":"string","format":"date-time"},"decision":{"type":"string"}}}},"source_arrivals":{"type":"array","maxItems":6,"description":"Optional bounded source-arrival comparison rows with labels, roles, numbers, and first-seen timestamps.","items":{"type":"object","required":["source_label","source_role","status"],"properties":{"source_label":{"type":"string","example":"Magayo"},"source_role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"observer"},"status":{"type":"string","enum":["matches_stored","differs_from_stored","stale_draw","unclassified"],"example":"differs_from_stored"},"numbers_formatted":{"type":"string","example":"8-1-2"},"observed_draw_date":{"type":"string","format":"date","example":"2026-06-24"},"first_seen_at":{"type":"string","format":"date-time"}}}}}},"links":{"type":"object","description":"Compact customer navigation links for public pages and API follow-up requests.","required":["canonical","lottery","api","api_docs","api_integration","schedule_api"],"properties":{"canonical":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"},"lottery":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/results/latest/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/results"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=md-pick3-midday&date=2026-05-25"},"history":{"type":"string","example":"/v1/results/history?date=2026-05-25&game_code=md-pick3-midday"},"history_page":{"type":"string","example":"/results/md-pick3-midday/2026-05-25"}}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"404":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/lotteries/{game_code}/draw-years":{"get":{"operationId":"getLotteryDrawYears","summary":"Get available draw years for one lottery","x-required-scopes":["lotteries:read"],"parameters":[{"name":"game_code","in":"path","required":true,"schema":{"type":"string"},"example":"md-pick3-midday"}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"years":{"type":"array","items":{"type":"integer"},"example":[2026,2025]},"limited":{"type":"boolean"},"source":{"type":"string","enum":["indexed_history","sandbox"],"example":"indexed_history"},"date_range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"draw_count":{"type":"integer"},"message":{"type":"string"}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter or request body."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"404":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/results/years":{"get":{"operationId":"getResultDrawYears","summary":"Get available draw years for one lottery","description":"Compatibility query endpoint for draw-year pickers. Prefer /lotteries/{game_code}/draw-years for canonical integrations; both paths use the same bounded drawYears read model and lotteries:read scope.","x-required-scopes":["lotteries:read"],"parameters":[{"name":"game_code","in":"query","required":true,"schema":{"type":"string"},"example":"md-pick3-midday"}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","properties":{"game_code":{"type":"string","example":"md-pick3-midday"},"years":{"type":"array","items":{"type":"integer"},"example":[2026,2025]},"limited":{"type":"boolean"},"source":{"type":"string","enum":["indexed_history","sandbox"],"example":"indexed_history"},"date_range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"draw_count":{"type":"integer"},"message":{"type":"string"}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"404":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/schedules":{"get":{"operationId":"listLotterySchedules","summary":"List draw schedules for customer-visible lotteries","description":"Returns compact stored schedule metadata for customer-visible Pick 3, Pick 4, and Pick 5 lotteries. The endpoint preserves timezone IDs and date-aware local and UTC labels for integration planning.","x-required-scopes":["lotteries:read"],"parameters":[{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"example":"2026-05-25"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"example":"US"},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"example":"MD"},{"name":"ball_count","in":"query","required":false,"schema":{"type":"integer"},"example":3},{"name":"game_code","in":"query","required":false,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"q","in":"query","required":false,"description":"Case-insensitive public search across lottery names, game codes, states, and country labels where supported.","schema":{"type":"string"},"example":"Pick 3"},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"title":"PublicScheduleList","type":"object","required":["filters","count","returned_count","total_count","limit","has_more","data"],"properties":{"generated_at":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","example":2,"description":"Backward-compatible alias for returned_count."},"returned_count":{"type":"integer","example":2,"description":"Number of rows returned in this response after applying limit."},"total_count":{"type":"integer","example":27,"description":"Total rows available after filters and access rules before applying limit."},"limit":{"type":"integer","example":100,"description":"Maximum rows requested or applied by the endpoint."},"has_more":{"type":"boolean","example":true,"description":"True when total_count is greater than returned_count."},"data":{"type":"array","items":{"type":"object","required":["game_code","name","state","state_code","country","links","draw_schedule"],"properties":{"game_code":{"type":"string","example":"tn-pick3-evening"},"name":{"type":"string","example":"Tennessee Cash 3 Evening"},"state":{"type":"string","example":"Tennessee"},"state_code":{"type":"string","example":"TN"},"country":{"type":"string","example":"US"},"ball_count":{"type":"integer","example":3},"links":{"type":"object","description":"Compact customer navigation links for catalog pages and lottery metadata API calls.","required":["canonical","latest_result","api","api_docs","api_integration","schedule_api","schedule_api","schedule_docs"],"properties":{"canonical":{"type":"string","example":"/lotteries/md-pick3-midday"},"latest_result":{"type":"string","example":"/lotteries/md-pick3-midday"},"api":{"type":"string","example":"/v1/lotteries/md-pick3-midday"},"api_docs":{"type":"string","example":"/api-docs/lotteries"},"api_integration":{"type":"string","example":"/lotteries/md-pick3-midday/api-integration"},"schedule_api":{"type":"string","example":"/v1/schedules?game_code=tn-pick3-evening&date=2026-06-21"},"schedule_docs":{"type":"string","example":"/api-docs/schedules"}}},"draw_schedule":{"type":"object","description":"Compact public draw schedule summary. Timezone IDs are preserved when known so clients can handle DST correctly.","properties":{"local_time":{"type":"string","example":"12:27 PM ET"},"utc_time":{"type":"string","example":"16:27 UTC"},"days":{"type":"string","example":"Every day"},"description":{"type":"string","example":"Every day. On Sunday, only the evening draw runs."},"timezone":{"type":"string","example":"America/New_York"},"next_draw":{"type":"object","description":"Next scheduled draw derived from normalized schedule metadata. Dates are local to the lottery timezone; UTC fields support timezone-safe integrations.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"local_time":{"type":"string","example":"6:28 PM CDT"},"utc_time":{"type":"string","example":"23:28 UTC"},"local_datetime":{"type":"string","example":"2026-06-21T18:28:00"},"utc_datetime":{"type":"string","format":"date-time","example":"2026-06-21T23:28:00Z"},"timezone":{"type":"string","example":"America/Chicago"},"days_until":{"type":"integer","example":0},"polling_window":{"type":"object","description":"Recommended bounded result-check window derived from scheduled draw time. It is a polling hint, not proof that the official result is published.","properties":{"first_check_after_utc":{"type":"string","format":"date-time","example":"2026-06-21T23:38:00Z"},"retry_until_utc":{"type":"string","format":"date-time","example":"2026-06-22T01:28:00Z"},"first_check_delay_minutes":{"type":"integer","example":10},"retry_window_minutes":{"type":"integer","example":120},"label":{"type":"string","example":"Start result checks at 2026-06-21T23:38:00Z; keep retries bounded until 2026-06-22T01:28:00Z unless your plan or source policy says otherwise."}}},"label":{"type":"string","example":"Next scheduled draw on Sunday, June 21, 2026 at 6:28 PM CDT (23:28 UTC)."}}},"note":{"type":"string","example":"On Sunday, only the evening draw runs."},"source":{"type":"object","properties":{"label":{"type":"string","example":"Maryland Lottery rules"},"url":{"type":"string","format":"uri","example":"https://www.mdlottery.com/"}}}}},"date_context":{"type":"object","description":"Present when date=YYYY-MM-DD is supplied. Status is derived from normalized public schedule text when safe.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"status":{"type":"string","enum":["scheduled","not_scheduled","unknown"],"example":"scheduled"},"label":{"type":"string","example":"Scheduled on Sunday. Every day. On Sunday, only the evening draw runs."}}},"next_draw":{"type":"object","description":"Next scheduled draw derived from normalized schedule metadata. Dates are local to the lottery timezone; UTC fields support timezone-safe integrations.","properties":{"date":{"type":"string","format":"date","example":"2026-06-21"},"local_time":{"type":"string","example":"6:28 PM CDT"},"utc_time":{"type":"string","example":"23:28 UTC"},"local_datetime":{"type":"string","example":"2026-06-21T18:28:00"},"utc_datetime":{"type":"string","format":"date-time","example":"2026-06-21T23:28:00Z"},"timezone":{"type":"string","example":"America/Chicago"},"days_until":{"type":"integer","example":0},"polling_window":{"type":"object","description":"Recommended bounded result-check window derived from scheduled draw time. It is a polling hint, not proof that the official result is published.","properties":{"first_check_after_utc":{"type":"string","format":"date-time","example":"2026-06-21T23:38:00Z"},"retry_until_utc":{"type":"string","format":"date-time","example":"2026-06-22T01:28:00Z"},"first_check_delay_minutes":{"type":"integer","example":10},"retry_window_minutes":{"type":"integer","example":120},"label":{"type":"string","example":"Start result checks at 2026-06-21T23:38:00Z; keep retries bounded until 2026-06-22T01:28:00Z unless your plan or source policy says otherwise."}}},"label":{"type":"string","example":"Next scheduled draw on Sunday, June 21, 2026 at 6:28 PM CDT (23:28 UTC)."}}},"latest_draw":{"type":"object","properties":{"draw_date":{"type":"string","format":"date"},"source":{"type":"string"},"status":{"type":"string"},"inserted_at":{"type":"string","format":"date-time"},"source_confidence":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"provenance":{"type":"object","description":"Compact customer-visible provenance summary with reviewed source labels and roles.","required":["label","role","display"],"properties":{"label":{"type":"string","example":"Maryland Lottery"},"role":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"source":{"type":"string","example":"mdlottery.com"},"provider":{"type":"string","example":"mdlottery.com"},"display":{"type":"string","example":"mdlottery.com published this result."}}}}}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/lotteries/{game_code}/frequency":{"get":{"operationId":"getLotteryFrequency","summary":"Get number frequency preview for one lottery","x-required-scopes":["results:read"],"parameters":[{"name":"game_code","in":"path","required":true,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"example":"2026-05-25"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"example":"2026-05-25","description":"Backward-compatible end-date alias. Use either date or to, not both."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","1y"]},"description":"Optional bounded published-history window. Ignored when date is supplied. Access is capped by freshness level: F1=7d, F2=30d, F3=90d, and F4-F7=1y. Unsupported values return INVALID_WINDOW; windows above the current access level return STATISTICS_WINDOW_REQUIRES_UPGRADE. When history is unavailable, the API fails closed instead of scanning archived feed files."},{"name":"include","in":"query","required":false,"schema":{"type":"string","example":"details"},"description":"Optional comma-separated bounded detail projection. Use include=details for patterns, longest gaps, top pairs, and top combinations. Default compact responses omit detail tables and access metadata."},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string"},"game_code":{"type":"string"},"range":{"type":"object","properties":{"date":{"type":"string","format":"date"},"source":{"type":"string","enum":["request_date","latest_visible_draw"]},"window":{"type":"string","enum":["7d","30d","90d","1y"]}}},"date_range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"draw_count":{"type":"integer","example":1},"excluded_draw_count":{"type":"integer","example":0,"description":"Customer-visible rows excluded from the aggregate because they are not official or verified source-confidence rows."},"source_confidence_summary":{"type":"object","properties":{"primary":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"levels":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"count":{"type":"integer","example":1}}}},"classified_draws":{"type":"integer","example":1},"unclassified_draws":{"type":"integer","example":0}}},"quality":{"type":"object","description":"Compact sample-quality guidance for interpreting descriptive statistics without treating small windows as predictions.","properties":{"level":{"type":"string","enum":["empty","limited","stable"],"example":"stable"},"label":{"type":"string","example":"Stable trusted sample"},"minimum_recommended_draws":{"type":"integer","example":5},"description":{"type":"string","example":"18 official source rows are included, meeting the minimum sample threshold for a stable descriptive statistics response."}}},"disclaimer":{"type":"string"},"response_shape":{"type":"string","enum":["compact"],"description":"Detailed pattern, gap, pair, and combination tables are omitted unless requested with an explicit bounded include value."},"included_fields":{"type":"array","items":{"type":"string","enum":["patterns","longest_gaps","top_pairs","top_combinations"]},"description":"Bounded detail fields explicitly included through include=patterns,gaps,pairs,combinations or include=details."},"omitted_fields":{"type":"array","items":{"type":"string","enum":["patterns","longest_gaps","top_pairs","top_combinations","access"]},"description":"Fields intentionally excluded from the compact default response shape."},"full_shape_hint":{"type":"string","description":"Human-readable hint for requesting bounded detail tables."},"summary":{"type":"object","properties":{"total_numbers":{"type":"integer","example":54},"unique_numbers":{"type":"integer","example":10},"odd_count":{"type":"integer","example":28},"even_count":{"type":"integer","example":26},"average_sum":{"type":"number","example":12.4},"min_sum":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":4},"max_sum":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":22}}},"patterns":{"type":"object","description":"Detailed descriptive patterns computed from the same trusted bounded draw window as summary and frequency rows. Returned by include=patterns or include=details. Historical statistics only; not predictive.","properties":{"parity":{"type":"object","properties":{"odd_count":{"type":"integer","example":28},"even_count":{"type":"integer","example":26},"odd_percent":{"type":"number","example":51.85},"even_percent":{"type":"number","example":48.15},"balance":{"type":"string","enum":["more_odd","more_even","balanced","none"],"example":"more_odd"}}},"sums":{"type":"object","properties":{"average":{"type":"number","example":12.4},"min":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":4},"max":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":22},"distribution":{"type":"array","items":{"type":"object","properties":{"sum":{"type":"integer","example":11},"count":{"type":"integer","example":3},"percent":{"type":"number","example":16.67}}}}}}}},"longest_gaps":{"type":"array","description":"Detailed observed gap table returned by include=gaps or include=details.","items":{"type":"object","properties":{"number":{"type":"string","example":"7"},"count":{"type":"integer","example":2},"last_seen_draws_ago":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":12}}}},"top_pairs":{"type":"array","description":"Bounded adjacent-position pair counts for the selected trusted draw window. Returned by include=pairs or include=details. Historical statistics only; not predictive.","items":{"type":"object","properties":{"pair":{"type":"string","example":"2-3"},"positions":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"integer"},"example":[1,2]},"count":{"type":"integer","example":4},"last_seen_draws_ago":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":2}}}},"top_combinations":{"type":"array","description":"Bounded ordered full-number combination counts for the selected trusted draw window. Returned by include=combinations or include=details. Historical statistics only; not predictive.","items":{"type":"object","properties":{"numbers":{"type":"array","items":{"type":"string"},"example":["2","3","6"]},"numbers_formatted":{"type":"string","example":"2-3-6"},"count":{"type":"integer","example":2},"last_seen_draws_ago":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":0}}}},"numbers":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"count":{"type":"integer"}}}},"access":{"type":"object","required":["audience","authenticated","service_level","service_level_label","delay_minutes","delay_label","ingestion_target_minutes","plan_delivery_delay_minutes","withheld_results","disclosure"],"properties":{"audience":{"type":"string","example":"api-key"},"authenticated":{"type":"boolean","example":true},"service_level":{"type":"string","enum":["F1","F2","F3","F4","F5","F6","F7","public-demo","sandbox"],"description":"Live access level, public-demo delivery policy, or sandbox fixture. Sandbox and public-demo values are not production ingestion claims.","example":"F3"},"service_level_label":{"type":"string","example":"F3 2h"},"delay_minutes":{"type":"integer","example":120},"delay_label":{"type":"string","example":"2 hours"},"ingestion_target_minutes":{"type":["integer","null"],"minimum":0,"description":"Live ingestion target after reviewed official publication. Null for fixtures and public demo access."},"plan_delivery_delay_minutes":{"type":"integer","minimum":0,"description":"Access-level delay after the feed first stores or observes a result."},"withheld_results":{"type":"integer","example":0},"disclosure":{"type":"string"}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/stats/{game_code}":{"get":{"operationId":"getLotteryStats","summary":"Get compact descriptive statistics for one lottery","description":"Short alias for /lotteries/{game_code}/frequency. It uses the same bounded trusted-row read model, request parameters, response shape, and results:read scope.","x-required-scopes":["results:read"],"parameters":[{"name":"game_code","in":"path","required":true,"schema":{"type":"string"},"example":"md-pick3-midday"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"example":"2026-05-25"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"example":"2026-05-25","description":"Backward-compatible end-date alias. Use either date or to, not both."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","1y"]},"description":"Optional bounded published-history window. Ignored when date is supplied. Access is capped by freshness level: F1=7d, F2=30d, F3=90d, and F4-F7=1y. Unsupported values return INVALID_WINDOW; windows above the current access level return STATISTICS_WINDOW_REQUIRES_UPGRADE. When history is unavailable, the API fails closed instead of scanning archived feed files."},{"name":"include","in":"query","required":false,"schema":{"type":"string","example":"details"},"description":"Optional comma-separated bounded detail projection. Use include=details for patterns, longest gaps, top pairs, and top combinations. Default compact responses omit detail tables and access metadata."},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","description":"Same compact public number-frequency payload returned by /lotteries/{game_code}/frequency. Additional bounded detail fields are returned only when requested with include=....","properties":{"generated_at":{"type":"string"},"game_code":{"type":"string"},"range":{"type":"object","properties":{"date":{"type":"string","format":"date"},"source":{"type":"string","enum":["request_date","latest_visible_draw"]},"window":{"type":"string","enum":["7d","30d","90d","1y"]}}},"date_range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"draw_count":{"type":"integer","example":18},"excluded_draw_count":{"type":"integer","example":2},"source_confidence_summary":{"type":"object","properties":{"primary":{"type":"object","required":["level","label","policy"],"properties":{"level":{"type":"string","enum":["official","verified","observer","fallback","manual","unknown"],"example":"official"},"label":{"type":"string","example":"Official source"},"policy":{"type":"string","example":"Numbers were published from the official or canonical lottery source."},"source":{"type":"string","example":"mdlottery.com"}}},"classified_draws":{"type":"integer","example":18},"unclassified_draws":{"type":"integer","example":0}}},"quality":{"type":"object","properties":{"level":{"type":"string","enum":["empty","limited","stable"],"example":"stable"},"label":{"type":"string","example":"Stable trusted sample"},"minimum_recommended_draws":{"type":"integer","example":5},"description":{"type":"string"}}},"disclaimer":{"type":"string"},"response_shape":{"type":"string","enum":["compact"]},"summary":{"type":"object","properties":{"total_numbers":{"type":"integer","example":54},"unique_numbers":{"type":"integer","example":10},"odd_count":{"type":"integer","example":28},"even_count":{"type":"integer","example":26},"average_sum":{"type":"number","example":12.4},"min_sum":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":4},"max_sum":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":22}}},"numbers":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"count":{"type":"integer"}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/countries":{"get":{"operationId":"listCountries","summary":"List supported countries","x-required-scopes":["lotteries:read"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"title":"PublicCountryList","type":"object","required":["filters","count","returned_count","total_count","limit","has_more","data"],"properties":{"generated_at":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","example":2,"description":"Backward-compatible alias for returned_count."},"returned_count":{"type":"integer","example":2,"description":"Number of rows returned in this response after applying limit."},"total_count":{"type":"integer","example":27,"description":"Total rows available after filters and access rules before applying limit."},"limit":{"type":"integer","example":100,"description":"Maximum rows requested or applied by the endpoint."},"has_more":{"type":"boolean","example":true,"description":"True when total_count is greater than returned_count."},"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"US"},"name":{"type":"string","example":"United States"},"state_count":{"type":"integer"},"lottery_count":{"type":"integer"}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter or request body."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/states":{"get":{"operationId":"listStates","summary":"List supported states/provinces","x-required-scopes":["lotteries:read"],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"example":"US"},{"name":"q","in":"query","required":false,"description":"Case-insensitive public search across lottery names, game codes, states, and country labels where supported.","schema":{"type":"string"},"example":"Pick 3"},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"title":"PublicStateList","type":"object","required":["filters","count","returned_count","total_count","limit","has_more","data"],"properties":{"generated_at":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","example":2,"description":"Backward-compatible alias for returned_count."},"returned_count":{"type":"integer","example":2,"description":"Number of rows returned in this response after applying limit."},"total_count":{"type":"integer","example":27,"description":"Total rows available after filters and access rules before applying limit."},"limit":{"type":"integer","example":100,"description":"Maximum rows requested or applied by the endpoint."},"has_more":{"type":"boolean","example":true,"description":"True when total_count is greater than returned_count."},"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"MD"},"name":{"type":"string","example":"Maryland"},"country":{"type":"string","example":"US"},"lottery_count":{"type":"integer"}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter or request body."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"401":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key is required, invalid, or expired."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"403":{"description":"FORBIDDEN, FORBIDDEN_GAME_CODE, FREE_BETA_ENDPOINT_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","FORBIDDEN_GAME_CODE","FREE_BETA_ENDPOINT_UNAVAILABLE"],"example":"FORBIDDEN"},"message":{"type":"string","example":"API key is missing the required scope."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"forbidden":{"value":{"error":{"code":"FORBIDDEN","message":"API key is missing the required scope.","details":[]},"request_id":"req_1234567890"}},"forbidden_game_code":{"value":{"error":{"code":"FORBIDDEN_GAME_CODE","message":"API key is not allowed to access the requested lottery game.","details":[]},"request_id":"req_1234567890"}},"free_beta_endpoint_unavailable":{"value":{"error":{"code":"FREE_BETA_ENDPOINT_UNAVAILABLE","message":"This endpoint or history date is not available in the Free Beta.","details":[]},"request_id":"req_1234567890"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"429":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"API key request quota has been exhausted."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"503":{"description":"AUTH_STORE_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, FEED_SNAPSHOT_UNAVAILABLE, FREE_BETA_API_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_STORE_UNAVAILABLE","RATE_LIMIT_UNAVAILABLE","FEED_SNAPSHOT_UNAVAILABLE","FREE_BETA_API_UNAVAILABLE"],"example":"AUTH_STORE_UNAVAILABLE"},"message":{"type":"string","example":"API key validation is temporarily unavailable."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}},"examples":{"auth_store_unavailable":{"value":{"error":{"code":"AUTH_STORE_UNAVAILABLE","message":"API key validation is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"rate_limit_unavailable":{"value":{"error":{"code":"RATE_LIMIT_UNAVAILABLE","message":"Rate-limit enforcement is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"feed_snapshot_unavailable":{"value":{"error":{"code":"FEED_SNAPSHOT_UNAVAILABLE","message":"Lottery result data is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}},"free_beta_api_unavailable":{"value":{"error":{"code":"FREE_BETA_API_UNAVAILABLE","message":"Free Beta API access is temporarily unavailable.","details":[]},"request_id":"req_1234567890"}}}}}}}}},"/status":{"get":{"operationId":"getFeedStatus","summary":"Get feed health summary","description":"Compact feed health, source-health, freshness policy, and public incident summary. This public status smoke endpoint does not require a bearer key.","security":[],"parameters":[{"name":"include","in":"query","required":false,"description":"Use include=games only for bounded customer diagnostics. Returned game rows are scoped to customer-visible Pick 3, Pick 4, and Pick 5 number games; other collected rows are not part of this public API.","schema":{"type":"string","enum":["games"]}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return from bounded list endpoints. Defaults to 100 and is capped at 1000; use total_count and has_more to detect truncation.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"offset","in":"query","required":false,"description":"Zero-based offset for /v1/status?include=games. Use the games_next continuation URL instead of raising limit for large status screens.","schema":{"type":"integer","minimum":0,"maximum":1000,"default":0},"example":0},{"name":"short","in":"query","required":false,"description":"Explicit short-response alias for the compact public read model. Use short=1 in copy-paste integrations when you want to make the compact contract obvious.","schema":{"type":"boolean","default":false}},{"name":"compact","in":"query","required":false,"description":"When true, returns the compact public response shape. Compact is also the default response shape.","schema":{"type":"boolean","default":true}},{"name":"shape","in":"query","required":false,"description":"Response projection. Public APIs use the compact customer-safe projection.","schema":{"type":"string","enum":["compact"],"default":"compact"}}],"responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"coverage":{"type":"object","description":"Canonical coverage snapshot. Catalog support is independent from result visibility; access delay may hide numbers without removing supported games.","required":["policy","snapshot_id","generated_at","source_generated_at","evaluated_at","access_context","catalog_games","operationally_tracked_games","active_games","paused_games","games_with_any_result","games_with_fresh_result","games_visible_at_current_access_level","results_delayed_for_access","late_games","blocked_or_failing_games","official_source_rows","verified_source_rows","observer_or_fallback_rows","jurisdictions","countries"],"properties":{"policy":{"type":"string","enum":["public_coverage_snapshot_v1"]},"snapshot_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"source_generated_at":{"type":["string","null"],"format":"date-time","description":"Timestamp supplied by the source snapshot when available."},"evaluated_at":{"type":"string","format":"date-time","description":"Timestamp when access and freshness counts were evaluated."},"access_context":{"type":"object","required":["audience","authenticated","service_level","service_level_label","delay_minutes","delay_label","ingestion_target_minutes","plan_delivery_delay_minutes","withheld_results","disclosure"],"properties":{"audience":{"type":"string","example":"api-key"},"authenticated":{"type":"boolean","example":true},"service_level":{"type":"string","enum":["F1","F2","F3","F4","F5","F6","F7","public-demo","sandbox"],"description":"Live access level, public-demo delivery policy, or sandbox fixture. Sandbox and public-demo values are not production ingestion claims.","example":"F3"},"service_level_label":{"type":"string","example":"F3 2h"},"delay_minutes":{"type":"integer","example":120},"delay_label":{"type":"string","example":"2 hours"},"ingestion_target_minutes":{"type":["integer","null"],"minimum":0,"description":"Live ingestion target after reviewed official publication. Null for fixtures and public demo access."},"plan_delivery_delay_minutes":{"type":"integer","minimum":0,"description":"Access-level delay after the feed first stores or observes a result."},"withheld_results":{"type":"integer","example":0},"disclosure":{"type":"string"}}},"catalog_games":{"type":"integer","minimum":0,"description":"Supported customer-visible catalog games."},"operationally_tracked_games":{"type":"integer","minimum":0,"description":"Catalog games with one recognised collection status row."},"active_games":{"type":"integer","minimum":0,"description":"Tracked games not explicitly paused, disabled, or inactive."},"paused_games":{"type":"integer","minimum":0},"games_with_any_result":{"type":"integer","minimum":0,"description":"Catalog games with a complete stored result."},"games_with_fresh_result":{"type":"integer","minimum":0,"description":"Catalog games whose complete stored draw date is no more than two UTC calendar days old."},"games_visible_at_current_access_level":{"type":"integer","minimum":0,"description":"Complete stored results visible to the current access scope and delivery-delay policy."},"results_delayed_for_access":{"type":"integer","minimum":0,"description":"In-scope complete stored results withheld only by the current access delivery delay."},"late_games":{"type":"integer","minimum":0},"blocked_or_failing_games":{"type":"integer","minimum":0},"official_source_rows":{"type":"integer","minimum":0,"description":"Complete results with verified official-source evidence."},"verified_source_rows":{"type":"integer","minimum":0,"description":"Complete results from reviewed independent sources."},"observer_or_fallback_rows":{"type":"integer","minimum":0},"jurisdictions":{"type":"integer","minimum":0},"countries":{"type":"integer","minimum":0}}},"tracked_games":{"type":"integer","description":"Number of customer-visible public number games represented by this status projection when complete game rows are available."},"status_counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Status bucket counts for the public status projection."},"source_health":{"type":"object","description":"Public source-health summary derived from customer-visible collection status buckets.","required":["score","grade","label","description","evidence","policy"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100,"example":84},"grade":{"type":"string","enum":["strong","watch","degraded"],"example":"watch"},"label":{"type":"string","example":"Source watch"},"description":{"type":"string"},"evidence":{"type":"array","items":{"type":"object","required":["label","value","tone"],"properties":{"label":{"type":"string","example":"Blocked or failing"},"value":{"type":"integer","example":3},"tone":{"type":"string","enum":["success","info","warning","danger","muted"],"example":"danger"}}}},"policy":{"type":"object","description":"Customer-safe explanation of source health calculation and public incident promotion rules.","required":["headline","summary","inputs","incidentRule","links"],"properties":{"headline":{"type":"string","example":"Source health uses public collection buckets only"},"summary":{"type":"string"},"inputs":{"type":"array","items":{"type":"object","required":["label","text"],"properties":{"label":{"type":"string","example":"Blocked or failing"},"text":{"type":"string"}}}},"incidentRule":{"type":"string"},"links":{"type":"array","items":{"type":"object","required":["label","href"],"properties":{"label":{"type":"string","example":"Status API docs"},"href":{"type":"string","example":"/api-docs/status"}}}}}}}},"freshness_policy":{"type":"object","description":"Compact public explanation of plan delivery delay, separate ingestion timing, and cache refresh. It is not an SLA guarantee.","required":["headline","summary","bullets","links"],"properties":{"headline":{"type":"string","example":"Plan delivery delays are separate from ingestion and uptime"},"summary":{"type":"string"},"bullets":{"type":"array","items":{"type":"object","required":["label","text"],"properties":{"label":{"type":"string","example":"Clock start"},"text":{"type":"string"}}}},"links":{"type":"array","items":{"type":"object","required":["label","href"],"properties":{"label":{"type":"string","example":"Compare delivery plans"},"href":{"type":"string","example":"/pricing"}}}}}},"data_freshness":{"type":"object","description":"Customer-safe schedule freshness derived from expected draw-window states. Latest dates are context only; the signal is not an SLA verdict.","required":["status","label","summary","latest_draw_date","latest_age_days","checked_games","current_games","degraded_games","unknown_games","examples","disclosure"],"properties":{"status":{"type":"string","enum":["current","degraded","unknown"],"example":"degraded"},"label":{"type":"string","example":"Some scheduled results need attention"},"summary":{"type":"string"},"latest_draw_date":{"type":["string","null"],"format":"date","example":"2026-06-20"},"latest_age_days":{"type":["integer","null"],"example":5},"checked_games":{"type":"integer","example":182},"current_games":{"type":"integer","example":170},"degraded_games":{"type":"integer","example":12},"unknown_games":{"type":"integer","example":0},"examples":{"type":"array","maxItems":3,"items":{"type":"object","required":["name","latest_draw_date","age_days","status","status_label"],"properties":{"name":{"type":"string","example":"Maryland Pick 3 Midday"},"latest_draw_date":{"type":["string","null"],"format":"date","example":"2026-06-20"},"age_days":{"type":["integer","null"],"example":5},"status":{"type":"string","example":"late"},"status_label":{"type":"string","example":"Late"}}}},"disclosure":{"type":"string"}}},"live_channel":{"type":"object","description":"Customer-safe availability summary for push and polling integration options.","required":["status","label","can_subscribe","summary","safe_alternatives"],"properties":{"status":{"type":"string","enum":["not_available"],"example":"not_available"},"label":{"type":"string","example":"Streaming subscriptions are not currently available"},"can_subscribe":{"type":"boolean","example":false},"summary":{"type":"string"},"safe_alternatives":{"type":"array","maxItems":4,"items":{"type":"object","required":["label","href","detail"],"properties":{"label":{"type":"string","example":"Poll latest results"},"href":{"type":"string","example":"/api-docs/results"},"detail":{"type":"string"}}}}}},"incident_history":{"type":"object","description":"Bounded customer-visible incident lifecycle summary with retention limits and no storage implementation details.","required":["source_label","configured","updated_at","total_incidents","open_incidents","resolved_incidents","latest_started_at","max_rows","disclosure"],"properties":{"source_label":{"type":"string","example":"Published incident log"},"configured":{"type":"boolean","example":true},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-06-25T12:16:00.000Z"},"total_incidents":{"type":"integer","example":2},"open_incidents":{"type":"integer","example":1},"resolved_incidents":{"type":"integer","example":1},"latest_started_at":{"type":["string","null"],"format":"date-time","example":"2026-06-25T11:00:00.000Z"},"max_rows":{"type":"integer","example":12},"disclosure":{"type":"string"}}},"incidents":{"type":"array","items":{"type":"object","description":"Customer-visible status incident. Private source diagnostics, raw provider payloads, credentials, and request logs are not included.","required":["id","title","status","severity","startedAt","summary","impact","customerAction"],"properties":{"id":{"type":"string","example":"active-source-access-degradation"},"title":{"type":"string","example":"Source access degradation under review"},"status":{"type":"string","enum":["resolved","monitoring","identified"],"example":"identified"},"severity":{"type":"string","enum":["notice","minor","major"],"example":"minor"},"startedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":"string","format":"date-time"},"summary":{"type":"string"},"impact":{"type":"string"},"customerAction":{"type":"string"}}}},"service_level":{"type":"object","required":["code","label","target","classification_intro","measurement_basis","current_subscription","disclosure","official_delay_disclaimer","near_realtime_disclosure","levels"],"properties":{"code":{"type":"string","example":"F3"},"label":{"type":"string","example":"F3 2h"},"target":{"type":"string","example":"after a 2-hour plan delivery delay"},"classification_intro":{"type":"string"},"measurement_basis":{"type":"string"},"current_subscription":{"type":"string"},"disclosure":{"type":"string"},"official_delay_disclaimer":{"type":"string"},"near_realtime_disclosure":{"type":"string"},"levels":{"type":"array","items":{"type":"object","required":["code","label","target","ingestion_target_minutes","plan_delivery_delay_minutes","note","standard","enterprise"],"properties":{"code":{"type":"string","example":"F7"},"label":{"type":"string","example":"F7 5m"},"target":{"type":"string","example":"within 5 minutes"},"ingestion_target_minutes":{"type":["integer","null"],"minimum":0,"description":"Published ingestion target from reviewed official publication to storage and processing. Null while no numeric public ingestion target is claimed."},"plan_delivery_delay_minutes":{"type":"integer","minimum":0,"description":"Access-level delay after the feed first stores or observes a result."},"note":{"type":"string"},"standard":{"type":"boolean"},"enterprise":{"type":"boolean"}}}}}},"games_count":{"type":"integer","example":1},"games_total_count":{"type":"integer","example":2},"games_limit":{"type":"integer","example":1},"games_offset":{"type":"integer","example":0},"games_has_more":{"type":"boolean","example":true},"games_next":{"type":"string","description":"Relative continuation URL for the next bounded status game slice when games_has_more is true.","example":"/v1/status?include=games&limit=1&offset=1"},"games":{"type":"array","items":{"type":"object","description":"Bounded customer-visible status row for one supported game.","required":["game_code","name","status","status_label","tone"],"properties":{"game_code":{"type":"string","example":"on-pick3-midday"},"name":{"type":"string","example":"Ontario Pick 3 Midday"},"status":{"type":"string","example":"blocked"},"status_label":{"type":"string","example":"Source access blocked"},"latest_draw_date":{"type":"string","format":"date","example":"2026-06-20"},"tone":{"type":"string","enum":["success","info","warning","danger","muted"],"example":"danger"}}}}}}}}},"400":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid query parameter."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"405":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"METHOD_NOT_ALLOWED"},"message":{"type":"string","example":"The HTTP method is not supported for this endpoint."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}},"500":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","example":"The API request could not be completed."},"details":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","enum":["INVALID_FORMAT","OUT_OF_RANGE","UNSUPPORTED_VALUE","DUPLICATE_PARAMETER"],"example":"OUT_OF_RANGE"},"message":{"type":"string","example":"limit must be between 1 and 1000."}}}},"game_code":{"type":"string","example":"tx-pick3-day","description":"Present on lottery allowlist denials so generated clients can show which game_code was blocked."},"rate_limit":{"type":"object","description":"Machine-readable retry evidence for HTTP 429 quota exhaustion and rate-limit enforcement HTTP 503 responses. Values are scoped to the authenticated API key, Free Beta workspace, or sandbox client and exclude account identifiers.","required":["scope","window","limit","remaining","retry_after_seconds","hint"],"properties":{"scope":{"type":"string","enum":["api_key","workspace","sandbox_client"],"example":"api_key"},"window":{"type":"string","enum":["utc_day","utc_month","sliding_window"],"example":"utc_day"},"limit":{"type":"integer","example":3000},"used":{"type":"integer","example":3000},"remaining":{"type":"integer","example":0},"reset_at":{"type":"string","format":"date-time","example":"2026-05-27T00:00:00.000Z"},"retry_after_seconds":{"type":"integer","example":3600},"hint":{"type":"string","example":"Pause requests until reset_at. Free Beta limits are shared by every API key in the workspace."}}}}},"request_id":{"type":"string","example":"req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Use a workspace API key for live data. Reserved lf_sandbox_* tokens and the exact legacy lf_test_demo_sandbox token return deterministic fixtures and do not read live feed data; arbitrary lf_test_* values are not sandbox credentials."}}}}