{
  "openapi": "3.1.0",
  "info": {
    "title": "w33t.io TRNG API",
    "version": "1.0.0",
    "description": "Public hardware-backed true random number generator API powered by an Infinite Noise TRNG and served from w33t.io.",
    "contact": {
      "url": "https://w33t.io/trng"
    }
  },
  "servers": [
    {
      "url": "https://w33t.io"
    }
  ],
  "tags": [
    {
      "name": "TRNG",
      "description": "Hardware-backed random generation endpoints."
    }
  ],
  "paths": {
    "/api/trng/generate": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Generate random bytes",
        "parameters": [
          {
            "name": "bytes",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 1024, "default": 32 }
          },
          {
            "name": "format",
            "in": "query",
            "schema": { "type": "string", "enum": ["hex", "base64", "raw"], "default": "hex" }
          }
        ],
        "responses": {
          "200": {
            "description": "Random bytes returned successfully.",
            "headers": {
              "X-RateLimit-Limit": { "schema": { "type": "string" } },
              "X-RateLimit-Remaining": { "schema": { "type": "string" } },
              "X-RateLimit-Reset": { "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bytes": { "type": "integer" },
                    "format": { "type": "string" },
                    "data": { "type": "string" },
                    "generatedAt": { "type": "string", "format": "date-time" },
                    "source": { "type": "string" }
                  }
                }
              },
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/PoolEmpty" }
        },
        "x-rateLimit": {
          "policy": "100 requests per minute per IP"
        }
      }
    },
    "/api/trng/uuid": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Generate UUID v4 values",
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "UUIDs generated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "uuids": { "type": "array", "items": { "type": "string", "format": "uuid" } },
                    "generatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/PoolEmpty" }
        },
        "x-rateLimit": {
          "policy": "100 requests per minute per IP"
        }
      }
    },
    "/api/trng/integer": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Generate a random integer in a range",
        "parameters": [
          { "name": "min", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "max", "in": "query", "schema": { "type": "integer", "default": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Random integer generated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "min": { "type": "integer" },
                    "max": { "type": "integer" },
                    "value": { "type": "integer" },
                    "generatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid range." },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/PoolEmpty" }
        },
        "x-rateLimit": {
          "policy": "100 requests per minute per IP"
        }
      }
    },
    "/api/trng/dice": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Roll one or more dice",
        "parameters": [
          { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 2 } },
          { "name": "sides", "in": "query", "schema": { "type": "integer", "minimum": 2, "maximum": 100, "default": 6 } }
        ],
        "responses": {
          "200": {
            "description": "Dice rolled successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "sides": { "type": "integer" },
                    "rolls": { "type": "array", "items": { "type": "integer" } },
                    "total": { "type": "integer" },
                    "generatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/PoolEmpty" }
        },
        "x-rateLimit": {
          "policy": "100 requests per minute per IP"
        }
      }
    },
    "/api/trng/coin": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Flip one or more coins",
        "parameters": [
          { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Coin flips generated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "flips": { "type": "array", "items": { "type": "string", "enum": ["heads", "tails"] } },
                    "heads": { "type": "integer" },
                    "tails": { "type": "integer" },
                    "generatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/PoolEmpty" }
        },
        "x-rateLimit": {
          "policy": "100 requests per minute per IP"
        }
      }
    },
    "/api/trng/key": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Generate a 128-bit or 256-bit key",
        "parameters": [
          { "name": "bits", "in": "query", "schema": { "type": "integer", "enum": [128, 256], "default": 256 } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["hex", "base64"], "default": "hex" } }
        ],
        "responses": {
          "200": {
            "description": "Key generated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bits": { "type": "integer" },
                    "format": { "type": "string" },
                    "value": { "type": "string" },
                    "generatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/PoolEmpty" }
        },
        "x-rateLimit": {
          "policy": "100 requests per minute per IP"
        }
      }
    },
    "/api/trng/stats": {
      "get": {
        "tags": ["TRNG"],
        "summary": "Read public pool and health statistics",
        "responses": {
          "200": {
            "description": "Current TRNG service statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalBytesServed": { "type": "integer" },
                    "totalRequestsServed": { "type": "integer" },
                    "poolBytesAvailable": { "type": "integer" },
                    "lastRefillAt": { "type": ["string", "null"], "format": "date-time" },
                    "online": { "type": "boolean" },
                    "onlineThresholdSeconds": { "type": "integer" },
                    "health": {
                      "type": ["object", "null"],
                      "properties": {
                        "entropyPerBit": { "type": "number" },
                        "estimatedK": { "type": "number" },
                        "numOnesPct": { "type": ["number", "null"] },
                        "evenMisfiresPct": { "type": ["number", "null"] },
                        "oddMisfiresPct": { "type": ["number", "null"] },
                        "reportedAt": { "type": "string", "format": "date-time" },
                        "source": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimited": {
        "description": "The caller exceeded the current IP-based request budget.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string" },
                "retryAfterSeconds": { "type": "integer" }
              }
            }
          }
        }
      },
      "PoolEmpty": {
        "description": "The hardware-backed entropy pool is temporarily empty.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}