{
  "openapi": "3.1.0",
  "info": {
    "title": "Lotto Millionaire public API",
    "version": "2.0.0",
    "description": "Independent lottery game information and random picks for entertainment only. Not official winning results or predictions. No tickets are sold. Rules may be wrong or change; consult the supplied official sources.",
    "contact": {
      "email": "contact@lottomillionairenumbers.com"
    },
    "termsOfService": "https://lottomillionairenumbers.com/terms"
  },
  "servers": [
    {
      "url": "https://lottomillionairenumbers.com"
    }
  ],
  "paths": {
    "/api/v1/states": {
      "get": {
        "operationId": "listStates",
        "summary": "List all 50 U.S. states and D.C. with lottery availability",
        "responses": {
          "200": {
            "description": "Successful response. Rules may change; verify official sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["states", "disclaimer"],
                  "properties": {
                    "states": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LotteryState"
                      }
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/games": {
      "get": {
        "operationId": "listGames",
        "summary": "List concise game summaries; fetch a game by ID for full rules",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "california"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Rules may change; verify official sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["games", "disclaimer"],
                  "properties": {
                    "games": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GameSummary"
                      }
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/games/{id}": {
      "get": {
        "operationId": "getGameRules",
        "summary": "Get game selection rules and official sources",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "powerball"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Rules may change; verify official sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["game", "disclaimer"],
                  "properties": {
                    "game": {
                      "$ref": "#/components/schemas/Game"
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/generate": {
      "post": {
        "operationId": "generateNumbers",
        "summary": "Generate random entertainment picks, never winning results",
        "description": "No ticket entry, purchase, prediction or improvement in odds. Origin, if sent, must be an approved site or exact local development origin. Requests without Origin are supported for server clients. Responses are not cached.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["gameId"],
                "properties": {
                  "gameId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 90,
                    "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 1
                  },
                  "spots": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 80,
                    "description": "Only for games with pickCount. Bounds are game-specific."
                  }
                }
              },
              "example": {
                "gameId": "powerball",
                "count": 2
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Rules may change; verify official sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "gameId",
                    "gameName",
                    "picks",
                    "generatedAt",
                    "rulesVerifiedAt",
                    "officialUrl",
                    "sources",
                    "disclaimer"
                  ],
                  "properties": {
                    "gameId": {
                      "type": "string"
                    },
                    "gameName": {
                      "type": "string"
                    },
                    "picks": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 10,
                      "items": {
                        "$ref": "#/components/schemas/GeneratedPick"
                      }
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "rulesVerifiedAt": {
                      "type": "string",
                      "format": "date"
                    },
                    "officialUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Source"
                      }
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Invalid request or unavailable resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Source": {
        "type": "object",
        "required": ["url", "title"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          }
        }
      },
      "NumberPool": {
        "type": "object",
        "required": ["id", "label", "count", "min", "max", "unique", "ordered"],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 80
          },
          "min": {
            "type": "integer"
          },
          "max": {
            "type": "integer"
          },
          "unique": {
            "type": "boolean"
          },
          "ordered": {
            "type": "boolean"
          },
          "accent": {
            "type": "boolean"
          },
          "line": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "description": "One-based line within a complete base play, when applicable."
          }
        }
      },
      "Game": {
        "type": "object",
        "required": [
          "id",
          "name",
          "kind",
          "tagline",
          "description",
          "pools",
          "rules",
          "officialUrl",
          "sources",
          "verifiedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "balls",
              "digits",
              "keno",
              "race",
              "calendar",
              "symbols",
              "info"
            ]
          },
          "tagline": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "pools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NumberPool"
            }
          },
          "rules": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "officialUrl": {
            "type": "string",
            "format": "uri"
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "verifiedAt": {
            "type": "string",
            "format": "date"
          },
          "notes": {
            "type": "string"
          },
          "numberLabels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pickCount": {
            "type": "object",
            "required": ["min", "max", "default"],
            "properties": {
              "min": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              },
              "default": {
                "type": "integer"
              }
            }
          },
          "play": {
            "type": "object",
            "required": ["lineCount"],
            "properties": {
              "lineCount": {
                "type": "integer",
                "minimum": 2,
                "maximum": 15
              },
              "terminalFromLine": {
                "type": "integer",
                "minimum": 2,
                "maximum": 15,
                "description": "First line simulated in place of a terminal-assigned official line."
              }
            }
          }
        }
      },
      "LotteryState": {
        "type": "object",
        "required": [
          "id",
          "code",
          "name",
          "hasLottery",
          "description",
          "gameIds",
          "sources",
          "verifiedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "hasLottery": {
            "type": "boolean"
          },
          "officialUrl": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          },
          "gameIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "verifiedAt": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "GeneratedPool": {
        "type": "object",
        "required": ["id", "label", "numbers", "ordered"],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "ordered": {
            "type": "boolean"
          },
          "accent": {
            "type": "boolean"
          },
          "line": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "description": "One-based line within a complete base play, when applicable."
          }
        }
      },
      "GeneratedPick": {
        "type": "object",
        "required": ["gameId", "pools"],
        "properties": {
          "gameId": {
            "type": "string"
          },
          "pools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeneratedPool"
            }
          }
        },
        "description": "One generated selection, containing every line of a base play for multi-line games. These practice selections are not purchased tickets."
      },
      "GameSummary": {
        "type": "object",
        "required": [
          "id",
          "name",
          "kind",
          "tagline",
          "officialUrl",
          "verifiedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "balls",
              "digits",
              "keno",
              "race",
              "calendar",
              "symbols",
              "info"
            ]
          },
          "tagline": {
            "type": "string"
          },
          "officialUrl": {
            "type": "string",
            "format": "uri"
          },
          "verifiedAt": {
            "type": "string",
            "format": "date"
          }
        }
      }
    }
  }
}
