{
  "openapi": "3.1.0",
  "info": {
    "title": "API pública de estado · XtreamCast",
    "version": "1.0.0",
    "summary": "Estado operativo en tiempo real e histórico de disponibilidad.",
    "description": "API pública y sin autenticación que expone el estado operativo de los servicios de XtreamCast.\n\nTodas las respuestas son JSON con marcas temporales en ISO-8601 UTC y permiten CORS desde cualquier origen.\nLa disponibilidad se calcula sobre el tiempo real de indisponibilidad de cada servicio, no sobre el\nporcentaje de sondas fallidas, y las incidencias solapadas se fusionan para no contabilizarse dos veces.\n\nLos datos se publican bajo licencia CC BY 4.0; al citarlos conviene incluir el campo `generatedAt`.",
    "contact": {
      "name": "Soporte técnico XtreamCast",
      "email": "soporte@xtreamcast.co",
      "url": "https://xtreamcast.co"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://status.xtreamcast.co/api/v1",
      "description": "Producción"
    }
  ],
  "tags": [
    {
      "name": "estado",
      "description": "Estado global y por servicio"
    },
    {
      "name": "incidencias",
      "description": "Historial de eventos operativos"
    },
    {
      "name": "documentos",
      "description": "Documentos legibles por máquinas y modelos de lenguaje"
    }
  ],
  "paths": {
    "/status": {
      "get": {
        "tags": [
          "estado"
        ],
        "operationId": "getStatus",
        "summary": "Snapshot completo del estado de la plataforma",
        "description": "Devuelve estado global, métricas agregadas, todos los componentes con su histórico diario y las incidencias recientes.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "description": "Ventana de histórico en días (1-90).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot público",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          }
        }
      }
    },
    "/status/summary": {
      "get": {
        "tags": [
          "estado"
        ],
        "operationId": "getStatusSummary",
        "summary": "Resumen compacto del estado global",
        "description": "Payload mínimo pensado para widgets, badges y comprobaciones automatizadas.",
        "responses": {
          "200": {
            "description": "Resumen del estado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Summary"
                }
              }
            }
          }
        }
      }
    },
    "/components": {
      "get": {
        "tags": [
          "estado"
        ],
        "operationId": "listComponents",
        "summary": "Servicios monitoreados",
        "responses": {
          "200": {
            "description": "Listado de servicios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "components": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Component"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/components/{component}": {
      "get": {
        "tags": [
          "estado"
        ],
        "operationId": "getComponent",
        "summary": "Detalle de un servicio",
        "parameters": [
          {
            "name": "component",
            "in": "path",
            "required": true,
            "description": "Identificador legible (slug) o id numérico del servicio.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Servicio encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Component"
                }
              }
            }
          },
          "404": {
            "description": "El servicio no existe o no es público"
          }
        }
      }
    },
    "/incidents": {
      "get": {
        "tags": [
          "incidencias"
        ],
        "operationId": "listIncidents",
        "summary": "Historial de incidencias",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por estado.",
            "schema": {
              "type": "string",
              "enum": [
                "resolved",
                "investigating"
              ]
            }
          },
          {
            "name": "component",
            "in": "query",
            "description": "Filtra por slug o id de servicio.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha ISO-8601 mínima de inicio.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha ISO-8601 máxima de inicio.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incidencias",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "incidents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Incident"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/history": {
      "get": {
        "tags": [
          "estado"
        ],
        "operationId": "getHistory",
        "summary": "Serie diaria de disponibilidad por servicio",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Histórico diario",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "days": {
                      "type": "integer"
                    },
                    "components": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "daily": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/DailyUptime"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "documentos"
        ],
        "operationId": "getLlmsTxt",
        "summary": "Índice del sitio para modelos de lenguaje (llmstxt.org)",
        "responses": {
          "200": {
            "description": "Documento Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "tags": [
          "documentos"
        ],
        "operationId": "getLlmsFullTxt",
        "summary": "Informe completo en Markdown con estado, métricas e histórico",
        "responses": {
          "200": {
            "description": "Documento Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/feed.xml": {
      "get": {
        "tags": [
          "documentos"
        ],
        "operationId": "getFeed",
        "summary": "Feed RSS 2.0 de incidencias",
        "responses": {
          "200": {
            "description": "Feed RSS",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ComponentStatus": {
        "type": "string",
        "enum": [
          "operational",
          "degraded_performance",
          "major_outage",
          "unknown"
        ],
        "description": "Estado operativo de un servicio."
      },
      "Availability": {
        "type": "object",
        "properties": {
          "days": {
            "type": "integer"
          },
          "uptimePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "downtimeSeconds": {
            "type": "integer"
          },
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DailyUptime": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Día en UTC (YYYY-MM-DD)."
          },
          "uptimePercent": {
            "type": "number"
          },
          "downtimeSeconds": {
            "type": "integer"
          },
          "partial": {
            "type": "boolean",
            "description": "true si el día aún está en curso."
          }
        }
      },
      "Incident": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "componentId": {
            "type": "integer"
          },
          "componentSlug": {
            "type": "string"
          },
          "componentName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "resolved",
              "investigating"
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "resolvedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "durationSeconds": {
            "type": "integer"
          },
          "durationText": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          }
        }
      },
      "Component": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "$ref": "#/components/schemas/ComponentStatus"
          },
          "statusLabel": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "checkType": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "enum": [
                  "ping",
                  "hls",
                  "shoutcast"
                ]
              },
              "label": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          },
          "host": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sólo se publica si el administrador lo marcó como visible."
          },
          "availability": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Availability"
            },
            "description": "Ventanas móviles: 1d, 7d, 30d y 90d."
          },
          "history": {
            "type": "object",
            "properties": {
              "days": {
                "type": "integer"
              },
              "daily": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DailyUptime"
                }
              }
            }
          },
          "responseTime": {
            "type": "object",
            "properties": {
              "windowDays": {
                "type": "integer"
              },
              "averageMs": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "minimumMs": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "maximumMs": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "samples": {
                "type": "integer"
              }
            }
          },
          "ssl": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "validUntil": {
                "type": "string",
                "format": "date-time"
              },
              "daysRemaining": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "issuer": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "healthy": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          },
          "incidentCount": {
            "type": "integer"
          },
          "incidents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Incident"
            }
          }
        }
      },
      "Summary": {
        "type": "object",
        "properties": {
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "page": {
            "type": "object"
          },
          "status": {
            "type": "object",
            "properties": {
              "indicator": {
                "type": "string",
                "enum": [
                  "none",
                  "minor",
                  "major",
                  "critical"
                ]
              },
              "description": {
                "type": "string"
              },
              "operationalComponents": {
                "type": "integer"
              },
              "totalComponents": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Snapshot": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "string"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "page": {
            "type": "object"
          },
          "status": {
            "$ref": "#/components/schemas/Summary/properties/status"
          },
          "metrics": {
            "type": "object"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            }
          },
          "incidents": {
            "type": "object",
            "properties": {
              "active": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Incident"
                }
              },
              "recent": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Incident"
                }
              }
            }
          }
        }
      }
    }
  }
}