{
  "openapi": "3.1.0",
  "info": {
    "title": "BoraGame Public API",
    "version": "1.0.0",
    "summary": "Endpoints públicos do site boragame.app para agentes e integrações.",
    "description": "API pública de primeira parte servida por https://boragame.app. Descreve os endpoints que agentes e integrações podem consultar sem autenticação. A gestão da arena (reservas, filas, torneios, financeiro) é feita no aplicativo em https://app.boragame.app; a API operacional dessa plataforma é autenticada e não faz parte deste documento. Para uma visão em linguagem natural de quando usar o BoraGame, veja https://boragame.app/llms.txt.",
    "termsOfService": "https://app.boragame.app/termos-de-uso",
    "contact": {
      "name": "BoraGame",
      "email": "contato@boragame.app",
      "url": "https://boragame.app/contato"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://boragame.app/privacidade"
    }
  },
  "servers": [
    {
      "url": "https://boragame.app",
      "description": "Produção"
    }
  ],
  "externalDocs": {
    "description": "Documentação para desenvolvedores",
    "url": "https://boragame.app/desenvolvedores"
  },
  "tags": [
    {
      "name": "Meta",
      "description": "Metadados do serviço e verificação de disponibilidade."
    }
  ],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getServiceStatus",
        "summary": "Status e metadados do serviço",
        "description": "Retorna o status de disponibilidade do site BoraGame e metadados básicos (nome, versão, links de documentação). Não requer autenticação. Útil para um agente confirmar que o serviço está no ar e descobrir os recursos disponíveis.",
        "tags": ["Meta"],
        "responses": {
          "200": {
            "description": "Serviço disponível.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceStatus"
                },
                "example": {
                  "name": "BoraGame",
                  "status": "ok",
                  "version": "1.0.0",
                  "site": "https://boragame.app",
                  "app": "https://app.boragame.app",
                  "docs": "https://boragame.app/desenvolvedores",
                  "openapi": "https://boragame.app/openapi.json",
                  "llms": "https://boragame.app/llms.txt",
                  "contact": "contato@boragame.app"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimitLimit": {
        "description": "Número máximo de requisições permitidas na janela atual (RFC 9331).",
        "schema": { "type": "integer", "example": 120 }
      },
      "RateLimitRemaining": {
        "description": "Requisições restantes na janela atual.",
        "schema": { "type": "integer", "example": 119 }
      },
      "RateLimitReset": {
        "description": "Segundos até a janela de rate limit reiniciar.",
        "schema": { "type": "integer", "example": 60 }
      },
      "RetryAfter": {
        "description": "Segundos que o cliente deve aguardar antes de tentar de novo.",
        "schema": { "type": "integer", "example": 60 }
      }
    },
    "schemas": {
      "ServiceStatus": {
        "type": "object",
        "description": "Status de disponibilidade e metadados do serviço BoraGame.",
        "required": ["name", "status", "version", "site"],
        "properties": {
          "name": { "type": "string", "description": "Nome do serviço.", "example": "BoraGame" },
          "status": {
            "type": "string",
            "description": "Estado de saúde do serviço.",
            "enum": ["ok", "degraded", "down"],
            "example": "ok"
          },
          "version": { "type": "string", "description": "Versão publicada do site.", "example": "1.0.0" },
          "site": { "type": "string", "format": "uri", "description": "URL do site institucional." },
          "app": { "type": "string", "format": "uri", "description": "URL do aplicativo de gestão." },
          "docs": { "type": "string", "format": "uri", "description": "URL da documentação para desenvolvedores." },
          "openapi": { "type": "string", "format": "uri", "description": "URL deste documento OpenAPI." },
          "llms": { "type": "string", "format": "uri", "description": "URL do resumo em linguagem natural para LLMs." },
          "contact": { "type": "string", "description": "E-mail de contato.", "example": "contato@boragame.app" }
        }
      },
      "Error": {
        "type": "object",
        "description": "Resposta de erro estruturada, legível por agentes.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Código de erro estável e legível por máquina.",
                "example": "not_found"
              },
              "message": {
                "type": "string",
                "description": "Mensagem legível por humanos.",
                "example": "Endpoint não encontrado."
              },
              "hint": {
                "type": "string",
                "description": "Sugestão de como resolver.",
                "example": "Consulte https://boragame.app/openapi.json para os endpoints disponíveis."
              },
              "status": {
                "type": "integer",
                "description": "Código de status HTTP.",
                "example": 404
              }
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Erro genérico em JSON.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "internal_error",
                "message": "Ocorreu um erro inesperado.",
                "hint": "Tente novamente em instantes ou escreva para contato@boragame.app.",
                "status": 500
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Limite de requisições excedido.",
        "headers": {
          "Retry-After": { "$ref": "#/components/headers/RetryAfter" },
          "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
          "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
          "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Muitas requisições.",
                "hint": "Aguarde o número de segundos em Retry-After antes de tentar de novo.",
                "status": 429
              }
            }
          }
        }
      }
    }
  }
}