Blck Alpaca API y recursos para desarrolladores
Todo lo que este sitio ofrece en formato legible por máquina: especificación OpenAPI, versiones en Markdown del contenido, llms.txt. Sin registro, sin claves.
Qué es esto y qué no
Estos endpoints sirven a los formularios y al buscador de este sitio web. No son una API de producto. No hay nada que integrar, ni cuenta, ni garantía de disponibilidad.
Aun así están documentados, por una razón: quien lee el sitio de forma automatizada no debería tener que reconstruir los endpoints a partir del código del frontend. Y quien choca con un límite de peticiones debería saber de antemano dónde está.
Los endpoints internos no aparecen en la especificación a propósito: invalidación de caché, mapa de redirecciones, campos de la protección antispam.
Recursos
URL fijas. No cambian.
| URL | Finalidad |
|---|---|
| /mcp | Servidor MCP para la base de conocimiento y la comprobación de sitios web. Streamable HTTP, revisión 2026-07-28 y 2025-11-25 o anteriores, solo POST. |
| /openapi.json | OpenAPI 3.1, JSON. Todos los endpoints públicos con esquemas, operationId y códigos de error. |
| /api/openapi.yaml | La misma especificación en YAML. |
| /llms.txt | Estructura del sitio en prosa: servicios, base de conocimiento, estudios, por idioma. |
| /llms-full.txt | Versión extensa con un resumen del contenido en lugar de una simple lista de enlaces. |
| /sitemap-index.xml | Lista completa de URL, dividida en partes. |
| /feed.xml | RSS de las entradas del blog. |
| /robots.txt | Reglas para crawlers, incluida la señal Content-Signal (ai-train=no). |
Autenticación
Ninguna. Los endpoints públicos no tienen claves, tokens ni cuentas.
Aun así, dos de ellos no se pueden automatizar con sentido: el formulario de contacto y la auditoría SEO exigen un token que solo genera la página en el navegador. La especificación los marca como browser-only. Además, ahí un 200 no significa que la petición se haya procesado. Las peticiones detectadas como automatizadas reciben la misma respuesta que las reales.
Cuotas
Los endpoints con límite de peticiones muestran su estado en cada respuesta, no solo en el 429. Si lees las cabeceras, no tienes que chocar contra el muro para conocer el límite.
Se envían dos formatos en paralelo: RateLimit y RateLimit-Policy según el borrador del IETF draft-ietf-httpapi-ratelimit-headers-11, y además las cabeceras heredadas RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, que leen la mayoría de las bibliotecas cliente. A agosto de 2026, el borrador no es un RFC.
Si se aplica más de una cuota, como en el chat por IP y por sesión, las dos primeras cabeceras las indican todas. Las cabeceras heredadas solo indican la más restrictiva.
Cabeceras de respuesta de una llamada al chat
RateLimit-Policy: "chat-ip";q=50;w=86400, "chat-session";q=20;w=86400
RateLimit: "chat-ip";r=49;t=86399, "chat-session";r=19;t=86399
RateLimit-Limit: 20
RateLimit-Remaining: 19
RateLimit-Reset: 86399- q
- Peticiones permitidas en la ventana.
- w
- Duración de la ventana en segundos.
- r
- Peticiones que quedan.
- t
- Segundos hasta el reinicio. Un delta, no una marca de tiempo.
Servidor MCP
La base de conocimiento y la comprobación de sitios web también están disponibles como servidor MCP, en POST /mcp. Un asistente que lo conecte busca en los artículos, obtiene los textos completos sin analizar HTML y comprueba si los sitios web públicos están preparados para agentes de IA.
El transporte es Streamable HTTP. El endpoint atiende dos generaciones del protocolo en la misma URL. La revisión 2026-07-28 dejó el núcleo sin estado: sin handshake initialize, sin ID de sesión, sin endpoint GET. Cada petición es un POST independiente y lleva su versión del protocolo en la cabecera MCP-Protocol-Version. Además son obligatorias Mcp-Method y, en tools/call, Mcp-Name; si no coinciden con el cuerpo, la petición se rechaza.
Los clientes que usan 2025-11-25, 2025-06-18 o 2025-03-26 empiezan, en cambio, con initialize y omiten las cabeceras nuevas. El SDK oficial sigue en 2025-11-25 en su versión 1.30.0, así que hoy esa es la vía habitual. Tampoco ahí se crea una sesión: el servidor no emite ningún Mcp-Session-Id y cada POST va por su cuenta. Una versión que no figure en ninguna de las dos listas se rechaza con -32022 y la lista de revisiones compatibles.
Sin registro. Se aplica la misma cuota que en los demás endpoints, y el contenido se puede usar citando la fuente.
| Herramienta | Descripción |
|---|---|
| search_knowledge_base | Búsqueda de texto completo en el título, la definición breve y la palabra clave principal de los artículos de la base de conocimiento de Blck Alpaca (SEO, GEO, agentes de IA, automatización de marketing). Devuelve resultados con URL y tripleta de ruta; el texto completo lo obtiene get_knowledge_article. |
| list_knowledge_categories | Devuelve la estructura de la base de conocimiento: todas las categorías con sus temas, cada uno con slug y URL. Es el punto de partida cuando no se conoce ningún término de búsqueda. |
| list_knowledge_topic_articles | Todos los artículos publicados de un tema. El slug de la categoría y el del tema tienen que corresponderse y proceder del mismo idioma; si no, la respuesta explica por qué. |
| get_knowledge_article | Texto completo de un artículo de la base de conocimiento en Markdown, junto con la definición breve, las ideas clave, estadísticas con su fuente y las preguntas frecuentes. La tripleta de ruta procede de search_knowledge_base o list_knowledge_topic_articles. |
| audit_website | Comprueba si un sitio web público está preparado para agentes y para GEO: ¿pueden los agentes de IA llegar a él, leerlo, entenderlo y trabajar con él? Carga el sitio como lo haría un agente (solo GET, sin iniciar sesión, sin cambios) y evalúa cinco áreas. Devuelve la puntuación total, las puntuaciones por área, los tres hallazgos con más impacto con la guía correspondiente, todas las comprobaciones individuales y un enlace al informe completo. No es una evaluación jurídica. |
Listar las herramientas
curl -X POST "https://blckalpaca.at/mcp" \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/list" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Listado en Official MCP Registry at.blckalpaca/knowledge-base · Smithery blckalpaca/knowledge-base
Conéctalo a tu asistente de IA
Una dirección para todos: https://blckalpaca.at/mcp, sin registro y sin clave. Después tendrás en el asistente las herramientas de la base de conocimiento y la comprobación de sitios web (audit_website).
Las rutas de menú proceden de la documentación de cada proveedor, a octubre de 2026. Si un proveedor cambia su interfaz, prevalece su documentación.
Claude (web y escritorio)
- Abre Customize → Connectors, haz clic en «+ Add» y luego en «Add custom connector».
- Introduce «Blck Alpaca» como nombre y https://blckalpaca.at/mcp como URL, confirma dos veces con «Continue» y termina con «Add». No hace falta autenticación.
- En el chat, abre «+» → «Connectors» y activa el interruptor de Blck Alpaca.
Disponible en todos los planes; el plan Free permite un conector personalizado. En Team y Enterprise, primero lo añade un Owner en Organization settings → Connectors.
Claude Code
claude mcp add --transport http blckalpaca https://blckalpaca.at/mcp- Ejecútalo en la terminal. Dentro de una sesión, /mcp muestra si la conexión está activa.
ChatGPT
- En ChatGPT Plugins, haz clic en «+» y luego en «Add custom MCP server».
- Introduce nombre y descripción, indica la URL https://blckalpaca.at/mcp en «Connection», no selecciones ninguna autenticación y termina con «Create as a plugin».
- En el chat, escribe «@» y selecciona Blck Alpaca.
Perplexity
- En los ajustes de tu cuenta, abre «Connectors», haz clic en «+ Custom connector» y elige «Remote».
- Introduce un nombre y la URL https://blckalpaca.at/mcp, con autenticación «None».
Para cuentas Pro, Max y Enterprise. En Enterprise, un administrador tiene que habilitar antes los conectores personalizados.
Grok
- Abre grok.com/connectors, elige «New Connector» y luego «Custom».
- Introduce la URL https://blckalpaca.at/mcp. Grok detecta las herramientas por sí mismo y las usa cuando una pregunta encaja.
En Grok Business y Enterprise, un administrador añade primero el conector en la consola de xAI.
Antigravity (CLI, IDE y 2.0)
{
"mcpServers": {
"blckalpaca": {
"serverUrl": "https://blckalpaca.at/mcp"
}
}
}- Añade la entrada en ~/.gemini/config/mcp_config.json o, para un solo proyecto, en .agents/mcp_config.json. La CLI, el IDE y Antigravity 2.0 leen el mismo formato.
- Sin tocar el archivo: en la CLI, /mcp abre el gestor de MCP; en Antigravity 2.0, ve a Settings → Customizations → Installed MCP Servers → Add MCP.
Antigravity exige «serverUrl». Los campos «url» y «httpUrl» de Gemini CLI no son compatibles. Desde el 18 de junio de 2026, Antigravity CLI (agy) sustituye a Gemini CLI en las cuentas gratuitas y en las suscripciones de Google One como Google AI Pro.
Gemini CLI
gemini mcp add --transport http -s user blckalpaca https://blckalpaca.at/mcp- Ejecútalo en la terminal. Sin «-s user», la entrada solo vale para el proyecto actual. Dentro de una sesión, /mcp muestra el estado.
Ya solo para cuentas Enterprise y uso con una clave de API de pago; el resto usa Antigravity. Si editas settings.json a mano: la entrada en mcpServers necesita «httpUrl», no «url». «url» está pensado para el antiguo transporte SSE.
Otros clientes
- Funciona cualquier cliente con Streamable HTTP: tipo de servidor HTTP, dirección https://blckalpaca.at/mcp, sin cabeceras. Los clientes que solo dominan el antiguo transporte SSE no son compatibles.
Solución de problemas
Los tropiezos más habituales al conectar, con su causa y su solución.
- El asistente dice que la configuración ha fallado.
- El servidor solo habla Streamable HTTP con POST, a partir de la revisión 2025-03-26 de MCP. Los clientes que esperan un endpoint GET o el antiguo transporte SSE fallan aquí. La URL tiene que ser exactamente https://blckalpaca.at/mcp: con barra al final, el servidor responde con una redirección que no todos los clientes siguen.
- Respuesta 403 o una página de verificación en lugar de JSON.
- La protección contra bots de Cloudflare ha interceptado la petición. Les pasa de vez en cuando a programas que llaman desde centros de datos. Escribe a office@blckalpaca.at con la hora y el cliente, y revisamos los registros.
- Respuesta 429.
- Cada dirección IP tiene 240 peticiones por hora. Cuánto tienes que esperar lo indica la cabecera Retry-After; el estado de la cuota lo da RateLimit en cada respuesta. La comprobación de sitios web tiene sus propios límites: diez comprobaciones por hora para el mismo sitio y 60 en total. Si se superan, la herramienta responde con rate_limited.
- Faltan herramientas o muestran descripciones antiguas.
- Muchos asistentes guardan la lista de herramientas al conectar. Desconecta el conector y vuelve a conectarlo.
- La comprobación de sitios web rechaza una dirección.
- Solo se comprueban sitios web públicos por http o https. Las direcciones IP privadas, los nombres de host internos, los nombres sin extensión de dominio y las direcciones que no se pueden resolver se rechazan con target_not_allowed.
- Un sitio con protección contra bots puntúa mal en acceso.
- Si su protección contra bots bloquea nuestra comprobación, normalmente también bloquea a los agentes de IA. Eso es un hallazgo, no un fallo de la herramienta.
- Falta un artículo en español.
- El servidor omite el contenido sin traducir en lugar de servirlo en alemán. Con locale «de» encuentras el artículo en su idioma original.
Endpoints
Tabla generada a partir de la misma especificación que se sirve en /openapi.json. No puede quedarse desactualizada.
| Endpoint | operationId | Descripción |
|---|---|---|
| GET /api/knowledge-search | searchKnowledgeBase | Buscar en la base de conocimientoBúsqueda de texto completo en el título, la definición y la palabra clave principal de los artículos de la base de conocimiento. |
| GET /api/health | getHealth | Estado de la aplicaciónPara monitorización. |
| POST /api/contact | submitContactForm | Enviar una solicitud de contactoEnvía un correo de confirmación con doble opt-in. |
| POST /api/newsletter/subscribe | subscribeNewsletter | Suscribirse a la newsletterDoble opt-in. |
| POST /api/newsletter/unsubscribe | unsubscribeNewsletter | Darse de baja de la newsletterEspera el token del enlace de baja del correo. |
| GET /api/newsletter/unsubscribe/validate | validateUnsubscribeToken | Comprobar un token de bajaComprueba si un token de baja es válido sin ejecutar la baja. |
| GET /api/newsletter/verify | verifyNewsletterSubscription | Confirmar la suscripción a la newsletterDestino del enlace del correo de confirmación. |
| GET /api/contact/verify | verifyContactRequest | Confirmar una solicitud de contactoDestino del enlace del correo de confirmación. |
| GET /api/chat | getChatSession | Consultar el historial de una sesión de chat (solo equipo editorial)Requiere iniciar sesión en el CMS. |
| POST /api/chat | sendChatMessage | Mensaje al asistente del sitio webLímite de peticiones por IP y, además, por sesión. |
| GET /api/agentic-check | runAgenticCheck | Comprobar si un sitio web está preparado para agentesComprueba un sitio web de acceso público en cinco áreas ponderadas: acceso 30, comprensión 25, descubrimiento 20, transparencia UE y privacidad 15, capacidad de acción 10. |
| POST /api/agentic-check | runAgenticCheckPost | Comprobar si un sitio web está preparado para agentes (vía formulario)Igual que GET, pero con los datos en el cuerpo. |
| GET /api/agentic-check/result/{token} | getAgenticCheckResult | Consultar un resultado guardadoDevuelve de nuevo un resultado ya generado sin volver a generar carga en los servidores comprobados. |
| POST /api/agentic-check/report | requestAgenticReport | Solicitar el informe detallado por correo (solo navegador)Requiere un challenge token del formulario. |
| POST /api/seo-audit | requestSeoAudit | Solicitar una auditoría SEO gratuita (solo navegador)Requiere un challenge token que se genera en el navegador al cargar el formulario. |
Respuestas de error
Todos los errores tienen la misma forma: error lleva un código estable, message el texto para personas, hint dice qué hacer. Los códigos nunca se renombran ni se reutilizan para otra cosa. Puedes basar en ellos la lógica de tu código.
| Código | Estado | Sugerencia |
|---|---|---|
| VALIDATION_ERROR | 400 | Revisa `fields` en esta respuesta: ahí aparece el error concreto de cada campo. |
| INVALID_REQUEST | 400 | Casi siempre falta el challenge token o ha caducado. Recarga la página y vuelve a enviar. |
| MISSING_FIELDS | 400 | Completa los campos indicados en `fields` y vuelve a enviar la petición. |
| MISSING_EMAIL | 400 | Incluye `email` en el cuerpo JSON. |
| FIELD_TOO_LONG | 400 | Acorta el campo indicado en `fields`. |
| MALFORMED_BODY | 400 | Envía JSON válido y establece `Content-Type: application/json`. |
| INVALID_EMAIL | 400 | Se espera una dirección del tipo nombre@dominio.tld. |
| INVALID_EMAIL_DOMAIN | 400 | El dominio no tiene registros MX. Usa otra dirección. |
| DISPOSABLE_EMAIL | 400 | Usa una dirección permanente. No reintentes con la misma. |
| ALREADY_SUBSCRIBED | 400 | No hace falta reintentar: el estado ya es el que querías. |
| INVALID_URL | 400 | Se espera una URL absoluta con http:// o https://. |
| INVALID_WEBSITE | 400 | Se espera un dominio accesible. |
| GDPR_REQUIRED | 400 | Pon `gdprConsent` a true. Sin consentimiento no se puede guardar nada. |
| INVALID_TOKEN | 400 | Los tokens son de un solo uso. Solicita uno nuevo. |
| TOKEN_EXPIRED | 410 | Solicita un token nuevo a través del endpoint original. |
| METHOD_NOT_ALLOWED | 405 | Los métodos permitidos están en la cabecera `Allow` de esta respuesta. |
| NOT_FOUND | 404 | Revisa la ruta. Tienes un resumen del sitio en /llms.txt. |
| UNAUTHORIZED | 401 | Este endpoint es interno y espera un secreto válido. |
| RATE_LIMIT | 429 | Espera los segundos indicados en la cabecera `Retry-After`. `RateLimit` indica la cuota restante; esa cabecera también aparece en las respuestas satisfactorias. |
| EMAIL_LIMIT | 429 | El límite se aplica por dirección, no por IP. Cambiar de IP no sirve. Este límite no figura a propósito en la cabecera `RateLimit`. |
| SPAM_REJECTED | 400 | No reintentes. Si crees que es un error, avísanos por correo a office@blckalpaca.at. |
| UPSTREAM_UNAVAILABLE | 503 | Temporal. Tiene sentido reintentar con backoff exponencial. |
| INTERNAL_ERROR | 500 | No lo ha causado tu petición. Vuelve a intentarlo más tarde. |
Ejemplos
Dos llamadas que funcionan sin navegador.
Buscar en la base de conocimiento
curl "https://blckalpaca.at/api/knowledge-search?q=schema&locale=es"Consultar el estado
curl -i "https://blckalpaca.at/api/health"Falta algo o hay un error
Si un endpoint responde de forma distinta a lo descrito aquí, el error está en la descripción. Basta con un mensaje breve.
Contacto