{
  "openapi": "3.1.0",
  "info": {
    "title": "KusiAI GEO & Agentic Web API",
    "description": "API oficial de KusiAI para auditorías forenses de Generative Engine Optimization (GEO), medición de Citation Share e integración con modelos generativos.",
    "version": "1.0.0",
    "contact": {
      "name": "KusiAI Engineering Support",
      "email": "hola@kusiai.es",
      "url": "https://kusiai.es/developers"
    },
    "x-versioning": {
      "strategy": "uri-path",
      "current_version": "v1",
      "supported_versions": [
        "v1"
      ],
      "default_version": "v1"
    },
    "x-deprecation-policy": {
      "notice_period_days": 90,
      "headers": [
        "Sunset",
        "Deprecation",
        "Link"
      ],
      "rfc": "RFC 8594 / RFC 9745"
    }
  },
  "servers": [
    {
      "url": "https://kusiai.es/api/v1",
      "description": "Servidor de Producción v1 (Oficial)"
    },
    {
      "url": "https://kusiai.es/api",
      "description": "Servidor de Producción Apex"
    }
  ],
  "paths": {
    "/v1/audit": {
      "post": {
        "summary": "Ejecutar Auditoría Forense KusiGEO",
        "description": "Analiza la visibilidad, bloqueos WAF y presencia de una URL en los principales modelos de lenguaje (ChatGPT, Gemini, Perplexity, Claude, DeepSeek, Qwen).",
        "operationId": "runGeoAudit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Informe forense generado con éxito",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResponse"
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida o parámetros incorrectos",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Límite de tasa excedido",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Segundos que el cliente debe esperar antes de reintentar"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/v1/citation-share": {
      "get": {
        "summary": "Consultar Citation Share de una Marca",
        "description": "Calcula el ratio entre apariciones ganadas y total de prompts evaluados en la categoría comercial.",
        "operationId": "getCitationShare",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Dominio o nombre de la marca a evaluar",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Métricas de cuota de citación",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationShareResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Búsqueda Semántica Vectorial",
        "description": "Recupera fragmentos de investigación y conocimiento sobre GEO y Agent Readiness indexados en el grafo semántico de KusiAI.",
        "operationId": "searchKnowledgeBase",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Texto o concepto técnico a buscar",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resultados de búsqueda semántica",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/audit": {
      "post": {
        "summary": "Ejecutar Auditoría Forense KusiGEO",
        "description": "Analiza la visibilidad, bloqueos WAF y presencia de una URL en los principales modelos de lenguaje (ChatGPT, Gemini, Perplexity, Claude, DeepSeek, Qwen).",
        "operationId": "runGeoAudit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Informe forense generado con éxito",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResponse"
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida o parámetros incorrectos",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Límite de tasa excedido",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Segundos que el cliente debe esperar antes de reintentar"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/citation-share": {
      "get": {
        "summary": "Consultar Citation Share de una Marca",
        "description": "Calcula el ratio entre apariciones ganadas y total de prompts evaluados en la categoría comercial.",
        "operationId": "getCitationShare",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Dominio o nombre de la marca a evaluar",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Métricas de cuota de citación",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationShareResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search": {
      "get": {
        "summary": "Búsqueda Semántica Vectorial",
        "description": "Recupera fragmentos de investigación y conocimiento sobre GEO y Agent Readiness indexados en el grafo semántico de KusiAI.",
        "operationId": "searchKnowledgeBase",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Texto o concepto técnico a buscar",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resultados de búsqueda semántica",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit-Limit": {
        "schema": {
          "type": "integer",
          "example": 120
        },
        "description": "Número máximo de peticiones permitidas en la ventana de tiempo (60s)"
      },
      "RateLimit-Remaining": {
        "schema": {
          "type": "integer",
          "example": 118
        },
        "description": "Número de peticiones restantes en la ventana actual"
      },
      "RateLimit-Reset": {
        "schema": {
          "type": "integer",
          "example": 42
        },
        "description": "Segundos hasta que la cuota se reinicie"
      }
    },
    "schemas": {
      "AuditRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL completa del sitio web a auditar",
            "example": "https://empresa.com"
          },
          "market": {
            "type": "string",
            "default": "ES",
            "description": "Código de país de dos letras para el contexto de búsqueda (ej. ES, MX, US)"
          }
        }
      },
      "AuditResponse": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "global_score": {
            "type": "number",
            "example": 88.5
          },
          "recognition_share": {
            "type": "number",
            "example": 100.0
          },
          "discovery_share": {
            "type": "number",
            "example": 75.0
          },
          "citation_gap": {
            "type": "number",
            "example": 25.0
          },
          "waf_block_detected": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "CitationShareResponse": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "citation_share_percent": {
            "type": "number",
            "example": 82.4
          },
          "sample_size": {
            "type": "integer",
            "example": 50
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "snippet": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "description": "Detalles de problema conformes a RFC 9457",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "URI que identifica el tipo de problema",
            "example": "https://kusiai.es/errors/not-found"
          },
          "title": {
            "type": "string",
            "description": "Resumen corto y legible del error",
            "example": "Endpoint Not Found"
          },
          "status": {
            "type": "integer",
            "description": "Código de estado HTTP",
            "example": 404
          },
          "detail": {
            "type": "string",
            "description": "Explicación legible del fallo",
            "example": "The requested API endpoint does not exist on this server."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "URI del recurso específico donde ocurrió el error"
          },
          "code": {
            "type": "string",
            "description": "Código de máquina específico de la aplicación",
            "example": "api_route_not_found"
          },
          "resolution_hint": {
            "type": "string",
            "description": "Instrucciones automáticas para agentes",
            "example": "Consult the OpenAPI specification at https://kusiai.es/openapi.json for valid endpoints."
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Autenticación estándar mediante token Bearer obtenido en /auth/token."
      }
    }
  }
}