{
    "openapi": "3.1.0",
    "info": {
        "title": "Revista Travel — API de contenidos para agentes",
        "description": "Artículos de viajes en español disponibles en JSON y Markdown para agentes de IA, motores de respuesta y llamadas de herramientas. Cite siempre la URL original devuelta en cada resultado.",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "https://revista.travel"
        }
    ],
    "paths": {
        "/ai/search.json": {
            "get": {
                "operationId": "searchArticles",
                "summary": "Busca artículos por texto libre.",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Consulta en lenguaje natural o palabras clave."
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0
                        }
                    },
                    {
                        "name": "content",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Incluye el texto completo en Markdown de cada resultado."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resultados",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        },
                                        "results": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "integer"
                                                    },
                                                    "title": {
                                                        "type": "string"
                                                    },
                                                    "slug": {
                                                        "type": "string"
                                                    },
                                                    "url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    },
                                                    "markdown_url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    },
                                                    "summary": {
                                                        "type": "string"
                                                    },
                                                    "language": {
                                                        "type": "string"
                                                    },
                                                    "category": {
                                                        "type": "object"
                                                    },
                                                    "author": {
                                                        "type": "object"
                                                    },
                                                    "published_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "updated_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "image": {
                                                        "type": "string",
                                                        "format": "uri",
                                                        "nullable": true
                                                    },
                                                    "tags": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "faq": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object"
                                                        }
                                                    },
                                                    "content_markdown": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ai/posts.json": {
            "get": {
                "operationId": "listArticles",
                "summary": "Lista los artículos más recientes, opcionalmente por categoría.",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug de categoría."
                    },
                    {
                        "name": "content",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        },
                                        "results": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "integer"
                                                    },
                                                    "title": {
                                                        "type": "string"
                                                    },
                                                    "slug": {
                                                        "type": "string"
                                                    },
                                                    "url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    },
                                                    "markdown_url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    },
                                                    "summary": {
                                                        "type": "string"
                                                    },
                                                    "language": {
                                                        "type": "string"
                                                    },
                                                    "category": {
                                                        "type": "object"
                                                    },
                                                    "author": {
                                                        "type": "object"
                                                    },
                                                    "published_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "updated_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "image": {
                                                        "type": "string",
                                                        "format": "uri",
                                                        "nullable": true
                                                    },
                                                    "tags": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "faq": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object"
                                                        }
                                                    },
                                                    "content_markdown": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ai/post/{slug}.json": {
            "get": {
                "operationId": "getArticle",
                "summary": "Devuelve un artículo completo con su contenido en Markdown.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Artículo",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "title": {
                                            "type": "string"
                                        },
                                        "slug": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string",
                                            "format": "uri"
                                        },
                                        "markdown_url": {
                                            "type": "string",
                                            "format": "uri"
                                        },
                                        "summary": {
                                            "type": "string"
                                        },
                                        "language": {
                                            "type": "string"
                                        },
                                        "category": {
                                            "type": "object"
                                        },
                                        "author": {
                                            "type": "object"
                                        },
                                        "published_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "updated_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "image": {
                                            "type": "string",
                                            "format": "uri",
                                            "nullable": true
                                        },
                                        "tags": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "faq": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "content_markdown": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado"
                    }
                }
            }
        },
        "/ai/categories.json": {
            "get": {
                "operationId": "listCategories",
                "summary": "Árbol de destinos y secciones editoriales.",
                "responses": {
                    "200": {
                        "description": "Categorías"
                    }
                }
            }
        },
        "/ai/category/{slug}.json": {
            "get": {
                "operationId": "getCategory",
                "summary": "Devuelve una categoría con sus subcategorías y sus artículos.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Categoría"
                    },
                    "404": {
                        "description": "No encontrada"
                    }
                }
            }
        },
        "/ai/tags.json": {
            "get": {
                "operationId": "listTags",
                "summary": "Etiquetas más usadas con su endpoint JSON.",
                "responses": {
                    "200": {
                        "description": "Etiquetas"
                    }
                }
            }
        },
        "/ai/tag/{slug}.json": {
            "get": {
                "operationId": "getTag",
                "summary": "Artículos de una etiqueta.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Etiqueta"
                    },
                    "404": {
                        "description": "No encontrada"
                    }
                }
            }
        },
        "/ai/authors.json": {
            "get": {
                "operationId": "listAuthors",
                "summary": "Autores con artículos publicados.",
                "responses": {
                    "200": {
                        "description": "Autores"
                    }
                }
            }
        },
        "/ai/author/{slug}.json": {
            "get": {
                "operationId": "getAuthor",
                "summary": "Perfil de autor y sus artículos.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Autor"
                    },
                    "404": {
                        "description": "No encontrado"
                    }
                }
            }
        },
        "/ai/pages.json": {
            "get": {
                "operationId": "listPages",
                "summary": "Páginas institucionales (quiénes somos, política editorial, contacto).",
                "responses": {
                    "200": {
                        "description": "Páginas"
                    }
                }
            }
        },
        "/ai/page/{slug}.json": {
            "get": {
                "operationId": "getPage",
                "summary": "Contenido de una página institucional en Markdown.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Página"
                    },
                    "404": {
                        "description": "No encontrada"
                    }
                }
            }
        },
        "/ai/urls.json": {
            "get": {
                "operationId": "listUrls",
                "summary": "Índice de todas las URLs públicas con su gemelo JSON y Markdown.",
                "responses": {
                    "200": {
                        "description": "Índice de URLs"
                    }
                }
            }
        },
        "/ai/resolve.json": {
            "get": {
                "operationId": "resolveUrl",
                "summary": "Resuelve cualquier URL del sitio (artículo, categoría, página, etiqueta o autor) y devuelve su payload.",
                "parameters": [
                    {
                        "name": "url",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Ruta o URL completa del sitio."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso resuelto"
                    },
                    "404": {
                        "description": "No encontrado"
                    }
                }
            }
        },
        "/ai/stats.json": {
            "get": {
                "operationId": "getStats",
                "summary": "Tamaño y frescura del corpus editorial.",
                "responses": {
                    "200": {
                        "description": "Estadísticas"
                    }
                }
            }
        },
        "/ai/dataset.json": {
            "get": {
                "operationId": "getDataset",
                "summary": "Descripción schema.org Dataset del corpus, con sus distribuciones.",
                "responses": {
                    "200": {
                        "description": "Dataset (JSON-LD)"
                    }
                }
            }
        },
        "/ai/license.json": {
            "get": {
                "operationId": "getLicense",
                "summary": "Política de uso legible por máquina (permisos, condiciones y restricciones).",
                "responses": {
                    "200": {
                        "description": "Política de uso"
                    }
                }
            }
        },
        "/feed.json": {
            "get": {
                "operationId": "getJsonFeed",
                "summary": "JSON Feed 1.1 con los artículos más recientes.",
                "responses": {
                    "200": {
                        "description": "JSON Feed"
                    }
                }
            }
        },
        "/{slug}.json": {
            "get": {
                "operationId": "getUrlTwin",
                "summary": "Gemelo JSON de cualquier URL pública: añade .json al enlace.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso"
                    },
                    "404": {
                        "description": "No encontrado"
                    }
                }
            }
        },
        "/{slug}.md": {
            "get": {
                "operationId": "getUrlMarkdown",
                "summary": "Gemelo Markdown de cualquier URL pública: añade .md al enlace.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Texto en Markdown"
                    },
                    "404": {
                        "description": "No encontrado"
                    }
                }
            }
        },
        "/mcp": {
            "post": {
                "operationId": "mcpRpc",
                "summary": "Servidor MCP (JSON-RPC 2.0): initialize, tools/list, tools/call, resources/list, resources/read.",
                "responses": {
                    "200": {
                        "description": "Respuesta JSON-RPC"
                    }
                }
            }
        }
    }
}