openapi: "3.0.3"
info:
  title: "RANLOTTO Gemini Tools"
  version: "1.0.0"
  description: "Narrow tool contract for Thai Government Lottery results and historical statistics. All responses use the agent envelope { success, data, facts, statistics, methodology, limitations, sources, sample_size, generated_at, timezone }. Historical statistics do not predict or guarantee future results."
servers:
  -
    url: "https://api.ranlotto.com"
    description: "Production API"
paths:
  "/api/public/v1/lottery/result/latest":
    get:
      operationId: "get_latest_lottery_result"
      tags:
        - "Results"
      summary: "Get the latest published lottery result using the agent envelope."
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentEnvelope"
        "400":
          description: "Invalid request"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "404":
          description: "Not found"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "409":
          description: "Data unavailable or incomplete"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "429":
          description: "Rate limit exceeded"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "500":
          description: "Server error"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
  "/api/public/v1/lottery/result/{date}":
    get:
      operationId: "get_lottery_result_by_date"
      tags:
        - "Results"
      summary: "Get one draw by date and its publication state."
      parameters:
        -
          name: "date"
          in: "path"
          required: true
          schema:
            type: "string"
            format: "date"
            pattern: "^\\d{4}-\\d{2}-\\d{2}$"
          description: "Draw date in YYYY-MM-DD."
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentEnvelope"
        "400":
          description: "Invalid request"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "404":
          description: "Not found"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "409":
          description: "Data unavailable or incomplete"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "429":
          description: "Rate limit exceeded"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "500":
          description: "Server error"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
  "/api/public/v1/lottery/check-number":
    get:
      operationId: "check_lottery_number"
      tags:
        - "Results"
      summary: "Check a 2, 3, or 6 digit number against a draw."
      parameters:
        -
          name: "number"
          in: "query"
          required: true
          schema:
            type: "string"
            pattern: "^(\\d{2}|\\d{3}|\\d{6})$"
        -
          name: "date"
          in: "query"
          schema:
            type: "string"
            default: "latest"
          description: "YYYY-MM-DD or latest."
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentEnvelope"
        "400":
          description: "Invalid request"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "404":
          description: "Not found"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "409":
          description: "Data unavailable or incomplete"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "429":
          description: "Rate limit exceeded"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "500":
          description: "Server error"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
  "/api/public/v1/lottery/number/{num}":
    get:
      operationId: "get_number_statistics"
      tags:
        - "Statistics"
      summary: "Get frequency, rank, gap, and match history for one number."
      parameters:
        -
          name: "num"
          in: "path"
          required: true
          schema:
            type: "string"
            pattern: "^\\d{2,6}$"
          description: "2-6 digits. String form preserves leading zeros."
        -
          name: "year"
          in: "query"
          schema:
            type: "integer"
          description: "Gregorian or Buddhist year; auto-detected."
        -
          name: "era"
          in: "query"
          schema:
            type: "string"
            enum:
              - "CE"
              - "BE"
              - "auto"
            default: "auto"
        -
          name: "from"
          in: "query"
          schema:
            type: "string"
            format: "date"
        -
          name: "to"
          in: "query"
          schema:
            type: "string"
            format: "date"
        -
          name: "latest"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
          description: "Restrict to the most recent N draws."
        -
          name: "exclude_disputed"
          in: "query"
          schema:
            type: "boolean"
            default: false
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentEnvelope"
        "400":
          description: "Invalid request"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "404":
          description: "Not found"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "409":
          description: "Data unavailable or incomplete"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "429":
          description: "Rate limit exceeded"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "500":
          description: "Server error"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
  "/api/public/v1/lottery/compare":
    get:
      operationId: "compare_numbers"
      tags:
        - "Statistics"
      summary: "Compare 2-20 numbers over one filtered dataset."
      parameters:
        -
          name: "numbers"
          in: "query"
          required: true
          schema:
            type: "string"
          example: "53,55,88"
        -
          name: "year"
          in: "query"
          schema:
            type: "integer"
          description: "Gregorian or Buddhist year; auto-detected."
        -
          name: "era"
          in: "query"
          schema:
            type: "string"
            enum:
              - "CE"
              - "BE"
              - "auto"
            default: "auto"
        -
          name: "from"
          in: "query"
          schema:
            type: "string"
            format: "date"
        -
          name: "to"
          in: "query"
          schema:
            type: "string"
            format: "date"
        -
          name: "latest"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
          description: "Restrict to the most recent N draws."
        -
          name: "exclude_disputed"
          in: "query"
          schema:
            type: "boolean"
            default: false
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentEnvelope"
        "400":
          description: "Invalid request"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "404":
          description: "Not found"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "409":
          description: "Data unavailable or incomplete"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "429":
          description: "Rate limit exceeded"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "500":
          description: "Server error"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
  "/api/public/v1/lottery/next-draw":
    get:
      operationId: "get_next_draw"
      tags:
        - "Schedule"
      summary: "Get the next scheduled draw date. Future draws never include result data."
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentEnvelope"
        "400":
          description: "Invalid request"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "404":
          description: "Not found"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "409":
          description: "Data unavailable or incomplete"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "429":
          description: "Rate limit exceeded"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
        "500":
          description: "Server error"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AgentError"
components:
  schemas:
    Source:
      type: "object"
      properties:
        name:
          type: "string"
        name_th:
          type: "string"
        url:
          type: "string"
          format: "uri"
        type:
          type: "string"
        source_published_at:
          type: "string"
          nullable: true
        retrieved_at:
          type: "string"
          format: "date-time"
    Methodology:
      type: "object"
      properties:
        description:
          type: "string"
        timezone:
          type: "string"
          enum:
            - "Asia/Bangkok"
        calculation_version:
          type: "string"
    AgentEnvelope:
      type: "object"
      required:
        - "success"
        - "generated_at"
        - "timezone"
      properties:
        success:
          type: "boolean"
          enum:
            - true
        data:
          type: "object"
          additionalProperties: true
        facts:
          type: "object"
          additionalProperties: true
        statistics:
          type: "object"
          additionalProperties: true
        observations:
          type: "array"
          items:
            type: "string"
        methodology:
          "$ref": "#/components/schemas/Methodology"
        limitations:
          type: "array"
          items:
            type: "string"
        sources:
          type: "array"
          items:
            "$ref": "#/components/schemas/Source"
        sample_size:
          type: "integer"
        filters:
          type: "object"
          additionalProperties: true
        disclaimer:
          type: "string"
        license:
          type: "string"
        generated_at:
          type: "string"
          format: "date-time"
        timezone:
          type: "string"
          enum:
            - "Asia/Bangkok"
    AgentError:
      type: "object"
      required:
        - "success"
        - "error"
      properties:
        success:
          type: "boolean"
          enum:
            - false
        error:
          type: "object"
          required:
            - "code"
            - "message"
          properties:
            code:
              type: "string"
            message:
              type: "string"
        generated_at:
          type: "string"
          format: "date-time"
        timezone:
          type: "string"
          enum:
            - "Asia/Bangkok"