{
  "openapi": "3.1.0",
  "info": {
    "title": "Neoriris Clock Tower API",
    "version": "0.3.0",
    "description": "Public read-only Clock Tower and Minecraft status plus authenticated, validated tower controls. Authorization requires a recognized player to receive a short-lived challenge code in game."
  },
  "servers": [
    {
      "url": "https://sol.system42.one"
    }
  ],
  "paths": {
    "/api/neoriris-clock-tower": {
      "get": {
        "operationId": "discoverNeoririsClockTowerApi",
        "summary": "List API routes and documentation",
        "responses": {
          "200": {
            "description": "API discovery document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Discovery"
                }
              }
            }
          }
        }
      }
    },
    "/api/neoriris-clock-tower/health": {
      "get": {
        "operationId": "getNeoririsClockTowerHealth",
        "summary": "Check API and Minecraft server reachability",
        "responses": {
          "200": {
            "description": "API health and Minecraft status-ping details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "minecraft": {
                      "$ref": "#/components/schemas/MinecraftStatus"
                    }
                  },
                  "required": [
                    "ok",
                    "service",
                    "version",
                    "minecraft"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/neoriris-clock-tower/status": {
      "get": {
        "operationId": "getNeoririsClockTowerStatus",
        "summary": "Read the live seven-segment tower and Minecraft server state",
        "security": [
          {},
          {
            "bearerAuth": []
          },
          {
            "tokenHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Live read-only state. A valid optional token adds authorized_as.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TowerStatus"
                }
              }
            }
          },
          "503": {
            "description": "The API is reachable, but live tower state could not be read before timeout."
          }
        }
      }
    },
    "/api/neoriris-clock-tower/authorize": {
      "post": {
        "operationId": "authorizeNeoririsClockTower",
        "summary": "Request or complete an in-game login challenge",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "description": "Recognized Neoriris player name. The player must be online and not AFK when requesting a code."
                  },
                  "code": {
                    "type": "string",
                    "description": "Code delivered in game. Omit this field on the first request."
                  }
                },
                "required": [
                  "username"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Challenge sent, or access token issued when a valid code is supplied."
          },
          "401": {
            "description": "Unknown, offline, AFK, expired, or invalid player challenge."
          }
        }
      }
    },
    "/api/neoriris-clock-tower/set": {
      "post": {
        "operationId": "setNeoririsClockTower",
        "summary": "Apply an authenticated, validated tower control",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "tokenHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "raw",
                      "face",
                      "action",
                      "bridge"
                    ],
                    "default": "raw"
                  },
                  "bits": {
                    "type": "string",
                    "pattern": "^[01]{7}$"
                  },
                  "manual": {
                    "type": "boolean"
                  },
                  "power": {
                    "type": "boolean"
                  },
                  "rotate": {
                    "type": "boolean"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "enter_manual",
                      "exit_manual",
                      "pulse_rotation"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated control applied and resulting state returned."
          },
          "400": {
            "description": "Invalid mode, action, or bit pattern."
          },
          "401": {
            "description": "Missing, expired, or invalid access token."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "tokenHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Neoriris-Access-Token"
      }
    },
    "schemas": {
      "Discovery": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "project": {
            "type": "string"
          },
          "openapi": {
            "type": "string"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "required": [
          "ok",
          "service",
          "version",
          "project",
          "openapi",
          "endpoints"
        ]
      },
      "MinecraftStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "port": {
            "type": "integer"
          },
          "players_online": {
            "type": "integer"
          },
          "players_max": {
            "type": "integer"
          },
          "version": {
            "type": "string"
          },
          "latency_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "ping_ok": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "TowerStatus": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "authorized_as": {
            "type": "string"
          },
          "state": {
            "type": "object",
            "additionalProperties": true
          },
          "server": {
            "$ref": "#/components/schemas/MinecraftStatus"
          },
          "coords": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "ok",
          "state",
          "server",
          "coords"
        ]
      }
    }
  }
}