{
  "openapi": "3.0.3",
  "info": {
    "title": "agentes.ai API",
    "description": "API pública de agentes.ai — Directorio de agencias de IA y agentes AI. Acceso programático a agencias, blog, reseñas y noticias. Base URL: https://www.agentes.ai/api",
    "version": "1.0.0",
    "contact": {
      "name": "agentes.ai",
      "url": "https://www.agentes.ai",
      "email": "contacto@agentes.ai"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://www.agentes.ai/api",
      "description": "Producción (vía CloudFront)"
    },
    {
      "url": "https://nz0piekbg3.execute-api.eu-central-1.amazonaws.com/dev",
      "description": "API Gateway directo"
    }
  ],
  "tags": [
    { "name": "agencies", "description": "Directorio de agencias de IA" },
    { "name": "blog", "description": "Blog IA — análisis diario" },
    { "name": "reviews", "description": "Reseñas de herramientas IA" },
    { "name": "news", "description": "Noticias de IA" },
    { "name": "system", "description": "Sistema y metadatos" }
  ],
  "paths": {
    "/agencies": {
      "get": {
        "tags": ["agencies"],
        "summary": "Listar agencias",
        "description": "Lista agencias publicadas con filtros opcionales. Las agencias con plan gratuito vencido se ocultan automáticamente a menos que el admin las reactive manualmente. Resultados ordenados: premium primero, luego estándar, luego free.",
        "parameters": [
          { "name": "q", "in": "query", "description": "Búsqueda por nombre, expertise o categoría", "required": false, "schema": { "type": "string" } },
          { "name": "category", "in": "query", "description": "Filtrar por categoría", "required": false, "schema": { "type": "string", "enum": ["Automatización", "Agentes Autónomos", "Integraciones", "Agentes de Voz", "Consultoría IA", "Desarrollo a medida"] } },
          { "name": "department", "in": "query", "description": "Filtrar por departamento", "required": false, "schema": { "type": "string" } },
          { "name": "premium", "in": "query", "description": "Solo premium", "required": false, "schema": { "type": "boolean" } },
          { "name": "limit", "in": "query", "description": "Límite (1-200, default 200)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 } }
        ],
        "responses": {
          "200": {
            "description": "Lista de agencias",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agencies": { "type": "array", "items": { "$ref": "#/components/schemas/Agency" } }
                  }
                },
                "example": {
                  "agencies": [
                    {
                      "agencyId": "agency-rakaty",
                      "name": "Rakaty Automatizaciones",
                      "location": "Madrid (Alcobendas), España",
                      "expertise": "Automatización de procesos con IA para PYMEs",
                      "website": "https://rakaty.com/",
                      "contactEmail": "contacto@rakaty.com",
                      "category": "Automatización",
                      "priceFrom": "Desde 900€",
                      "isPremium": true,
                      "plan": "premium"
                    }
                  ]
                }
              }
            },
            "headers": {
              "Cache-Control": { "description": "Cache pública 120s", "schema": { "type": "string" } },
              "Vary": { "description": "Vary header para negociación de contenido", "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/agencies/{agencyId}/click": {
      "post": {
        "tags": ["agencies"],
        "summary": "Registrar click outbound",
        "description": "Fire-and-forget beacon para tracking de clicks a webs de agencias. Usa sendBeacon o fetch con keepalive. No requiere auth.",
        "parameters": [
          { "name": "agencyId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source": { "type": "string", "description": "Origen del click,ej: home, directorio, ciudad:madrid", "example": "home" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Click registrado" },
          "400": { "description": "agencyId inválido" }
        }
      }
    },
    "/news": {
      "get": {
        "tags": ["news"],
        "summary": "Listar noticias",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Lista de noticias",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "news": { "type": "array", "items": { "$ref": "#/components/schemas/NewsItem" } },
                    "next_cursor": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/blog": {
      "get": {
        "tags": ["blog"],
        "summary": "Listar posts del blog",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["Modelos", "Herramientas", "Empresas", "Regulación", "Investigación", "Aplicaciones"] } },
          { "name": "tag", "in": "query", "schema": { "type": "string" } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Lista de posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostLight" } },
                    "next_cursor": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/blog/{slug}": {
      "get": {
        "tags": ["blog"],
        "summary": "Obtener post por slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Post encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "post": { "$ref": "#/components/schemas/BlogPost" }
                  }
                }
              }
            }
          },
          "404": { "description": "Post no encontrado" }
        }
      }
    },
    "/reviews": {
      "get": {
        "tags": ["reviews"],
        "summary": "Listar reseñas",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["Agentes", "Automatización", "Chatbots", "Productividad", "Desarrollo", "Marketing", "Análisis"] } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Lista de reseñas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewLight" } },
                    "next_cursor": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/reviews/{slug}": {
      "get": {
        "tags": ["reviews"],
        "summary": "Obtener reseña por slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Reseña encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "review": { "$ref": "#/components/schemas/Review" },
                    "related": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewLight" } }
                  }
                }
              }
            }
          },
          "404": { "description": "Reseña no encontrada" }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["system"],
        "summary": "OpenAPI spec (este documento)",
        "responses": {
          "200": {
            "description": "OpenAPI JSON",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    },
    "schemas": {
      "Agency": {
        "type": "object",
        "properties": {
          "agencyId": { "type": "string" },
          "name": { "type": "string", "example": "Rakaty Automatizaciones" },
          "location": { "type": "string", "example": "Madrid (Alcobendas), España" },
          "expertise": { "type": "string" },
          "website": { "type": "string", "format": "uri" },
          "contactEmail": { "type": "string", "format": "email" },
          "category": { "type": "string" },
          "department": { "type": "string" },
          "priceFrom": { "type": "string" },
          "isPremium": { "type": "boolean" },
          "plan": { "type": "string", "enum": ["free", "standard", "premium"] },
          "status": { "type": "string", "enum": ["active", "PENDING_REVIEW", "PENDING_PAYMENT"] },
          "freeUntil": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "BlogPostLight": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "published_at": { "type": "string", "format": "date-time" },
          "og_image_url": { "type": "string", "format": "uri" },
          "reading_time_min": { "type": "integer" }
        }
      },
      "BlogPost": {
        "allOf": [
          { "$ref": "#/components/schemas/BlogPostLight" },
          {
            "type": "object",
            "properties": {
              "content_html": { "type": "string" },
              "content_md": { "type": "string" },
              "updated_at": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "ReviewLight": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "tool_name": { "type": "string" },
          "category": { "type": "string" },
          "rating": { "type": "number", "minimum": 1, "maximum": 5 },
          "published_at": { "type": "string", "format": "date-time" },
          "og_image_url": { "type": "string" }
        }
      },
      "Review": {
        "allOf": [
          { "$ref": "#/components/schemas/ReviewLight" },
          {
            "type": "object",
            "properties": {
              "content_html": { "type": "string" },
              "content_md": { "type": "string" },
              "tool_url": { "type": "string", "format": "uri" },
              "affiliate_url": { "type": "string", "format": "uri" },
              "pricing_summary": { "type": "string" },
              "pros": { "type": "array", "items": { "type": "string" } },
              "cons": { "type": "array", "items": { "type": "string" } }
            }
          }
        ]
      },
      "NewsItem": {
        "type": "object",
        "properties": {
          "date": { "type": "string" },
          "newsid": { "type": "string" },
          "titulo": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "fuente": { "type": "string" }
        }
      }
    }
  }
}