{
  "openapi": "3.1.0",
  "info": {
    "title": "ORAK Public Surface & Agent API",
    "version": "1.0.0",
    "description": "Especificación de superficies públicas y endpoints de ORAK (https://orak.es) optimizada para agentes de inteligencia artificial, buscadores y desarrolladores.",
    "contact": {
      "name": "ORAK Team",
      "url": "https://orak.es/contact",
      "email": "contacto@orak.es"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://orak.es/legal-notice"
    }
  },
  "servers": [
    {
      "url": "https://orak.es",
      "description": "Servidor de Producción ORAK"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getLandingPage",
        "summary": "Página Principal / Landing Web",
        "description": "Devuelve la aplicación cliente interactiva o el resumen semántico en Markdown si se solicita mediante la cabecera Accept: text/markdown.",
        "responses": {
          "200": {
            "description": "Aplicación web o contenido markdown",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/about": {
      "get": {
        "operationId": "getAboutInfo",
        "summary": "Información Semántica y Arquitectura de ORAK",
        "description": "Página semántica con descripción completa de la plataforma de cine, arquitectura, características y FAQs.",
        "responses": {
          "200": {
            "description": "Página HTML semántica o Markdown de ORAK",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/contact": {
      "get": {
        "operationId": "getContactPage",
        "summary": "Página de Contacto y Soporte Oficial",
        "description": "Devuelve la información de contacto oficial, canales de soporte al cliente, reporte de incidencias y dirección de ORAK.",
        "responses": {
          "200": {
            "description": "Página HTML semántica o Markdown de contacto",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/developers": {
      "get": {
        "operationId": "getDeveloperPortal",
        "summary": "Portal de Desarrolladores y Documentación de Agentes",
        "description": "Guía de integración, documentación de endpoints de la API, especificación OpenAPI e instrucciones para LLMs y herramientas autónomas.",
        "responses": {
          "200": {
            "description": "Portal de desarrolladores en HTML o Markdown",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/movie/{id}": {
      "get": {
        "operationId": "getPublicMovieOpenGraph",
        "summary": "Ficha Pública de Película o Serie",
        "description": "Devuelve la ficha pública de una película o serie de TV con etiquetas OpenGraph enriquecidas, póster, sinopsis y enlaces para agentes.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador numérico de la película o serie en el catálogo (TMDB ID)",
            "schema": {
              "type": "integer",
              "example": 550
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página HTML con metadatos OpenGraph de la película o serie",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Título no encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Title not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/list/{id}": {
      "get": {
        "operationId": "getRecommendationList",
        "summary": "Lista Pública de Recomendaciones",
        "description": "Devuelve la vista pública de una lista de recomendaciones de cine y series generada en ORAK.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador UUID de la lista",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "123e4567-e89b-12d3-a456-426614174000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de la lista con metadatos de las películas",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Lista no encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "List not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/priority-list/{id}": {
      "get": {
        "operationId": "getPriorityList",
        "summary": "Lista Pública Prioritaria con Ranking ELO",
        "description": "Devuelve la vista pública de una lista prioritaria clasificada mediante enfrentamientos ELO cara a cara.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador UUID de la lista prioritaria",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "123e4567-e89b-12d3-a456-426614174000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de la lista prioritaria con OpenGraph enriquecido",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Lista prioritaria no encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Priority list not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "checkServerHealth",
        "summary": "Diagnóstico de Salud del Servidor",
        "description": "Verifica el estado del servicio, conectividad y tiempo de actividad (uptime) en segundos.",
        "responses": {
          "200": {
            "description": "Estado operativo del servidor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "uptime": {
                      "type": "number",
                      "example": 1243.5
                    }
                  },
                  "required": [
                    "status",
                    "uptime"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsManifest",
        "summary": "Manifiesto estándar para Modelos de Lenguaje",
        "description": "Archivo en formato de texto plano con descripción estructurada, guías When to use this y enlaces de documentación para agentes.",
        "responses": {
          "200": {
            "description": "Manifiesto llms.txt",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}