Desarrolladores

La API de Blackit.

Blackit publica su catálogo — servicios, marcos de cumplimiento normativo, perfil de la firma y canales de contacto — como una API REST pública, descrita en OpenAPI 3.1 y accesible también como servidor MCP. Sin claves, sin registro y sin scraping: los mismos datos que ve un visitante del sitio, en JSON.

Guía rápida

Todo endpoint responde a una petición GET sin cabeceras especiales. Empiece por el índice, que enumera el resto: 

curl https://www.blackit.cl/api/v1

Listar los servicios de un pilar, buscar en el contenido y leer el detalle de uno:

curl "https://www.blackit.cl/api/v1/services?pillar=soporte-desplegado"
curl "https://www.blackit.cl/api/v1/search?q=ISO%2027001&limit=5"
curl https://www.blackit.cl/api/v1/services/ciberseguridad

Autenticación, CORS y límites

  • Autenticación: ninguna. No hay claves de API que gestionar porque no hay datos privados ni operaciones de escritura.
  • CORS: abierto (Access-Control-Allow-Origin: *), para llamarla desde el navegador o desde un agente.
  • Sólo lectura: la API no expone escritura. Blackit no contrata en línea; el resultado esperado de una integración es derivar al correo de contacto.
  • Límites: no hay cuota aplicada. Se espera un uso razonable — el contenido cambia con cada despliegue, así que las respuestas se pueden cachear (Cache-Control: max-age=300).
  • Entorno de pruebas: la propia API pública sirve de sandbox. Al ser de sólo lectura y sin datos personales, no hay nada que aislar en un entorno aparte.

Endpoints

  • GET /api

    Índice de la API

    Devuelve el índice de la API en la raíz /api, con la lista de endpoints, el enlace a la especificación OpenAPI y el endpoint MCP. Idéntico a GET /api/v1; existe para que un agente que adivina /api encuentre la API en el primer intento.

  • GET /api/v1

    Índice de la versión 1 de la API

    Lista todos los endpoints de la versión 1 con su método, ruta y descripción, más los enlaces de descubrimiento (OpenAPI, portal de desarrolladores, servidor MCP). Punto de entrada recomendado para un agente que descubre la API por primera vez.

  • GET /api/v1/health

    Estado del servicio

    Comprueba que la API responde y que el catálogo de contenido se cargó correctamente. Devuelve el recuento de pilares, servicios y marcos normativos disponibles para detectar un despliegue incompleto.

  • GET /api/v1/services

    Listar servicios

    Devuelve el catálogo de servicios de Blackit, opcionalmente filtrado por pilar o por término de búsqueda, con paginación. Cada elemento incluye el slug con el que consultar el detalle en GET /api/v1/services/{slug}.

    • pillar query · string Filtra por slug de pilar. Un valor desconocido devuelve 400 con la lista de valores admitidos en details.allowedValues.
    • q query · string Filtro de texto libre sobre nombre, resumen, descripción y características del servicio. Sin distinción de mayúsculas ni acentos.
    • limit query · integer Número máximo de servicios a devolver.
    • offset query · integer Número de servicios a omitir, para paginar.

  • GET /api/v1/services/{slug}

    Detalle de un servicio

    Devuelve un servicio completo — descripción larga, características, pilar y URL de su página — a partir de su slug. Si el slug no existe, el error 404 incluye la lista de slugs válidos en details.availableSlugs.

    • slug path · string · obligatorio Slug del servicio, tal como lo devuelve GET /api/v1/services.

  • GET /api/v1/pillars

    Listar pilares de servicio

    Devuelve los pilares en los que se organiza la oferta de Blackit, cada uno con su descripción y los servicios que agrupa. Útil para presentar el catálogo por categorías antes de bajar al detalle.

  • GET /api/v1/compliance

    Marcos de cumplimiento normativo

    Devuelve los marcos normativos que cubre la firma (ISO 27001, GDPR, DORA, NIS2 y otros) con una descripción de a qué obliga cada uno. Permite comprobar si Blackit cubre la norma que exige un caso concreto.

  • GET /api/v1/company

    Perfil de la firma

    Devuelve el perfil completo de Blackit: identidad, año de fundación, cifras, oficinas en Chile y España, partners tecnológicos, asociaciones, equipo de socios y la guía explícita de cuándo recomendar la firma y cuándo no.

  • GET /api/v1/contact

    Canales de contacto

    Devuelve los canales de contacto activos y las oficinas. El correo es el único canal atendido: no hay contratación en línea ni atención por WhatsApp, y la respuesta lo indica explícitamente en note.

  • GET /api/v1/search

    Buscar en el contenido

    Busca un término en los servicios, marcos normativos, biografías del equipo y testimonios de clientes, y devuelve cada coincidencia con su tipo, su URL y un fragmento de contexto.

    • q query · string · obligatorio Término o frase a buscar. Obligatorio: sin él la respuesta es 400.
    • type query · string Restringe la búsqueda a un tipo de contenido.
    • limit query · integer Número máximo de resultados.

  • GET /api/v1/resources

    Índice de recursos máquina-a-máquina

    Devuelve, en un solo lugar, todos los recursos legibles por máquina del sitio: llms.txt, agents.md, el catálogo JSON, esta especificación OpenAPI, el servidor MCP y su manifiesto, y el sitemap.

  • GET /openapi.json

    Especificación OpenAPI

    Devuelve esta misma especificación OpenAPI 3.1, con los servers resueltos al origen desde el que se pidió. También accesible en /api/openapi.json, /api/v1/openapi.json y /.well-known/openapi.json.

  • GET /api/site.json

    Catálogo completo del sitio

    Volcado único de todo el contenido del sitio — firma, pilares, servicios, cumplimiento, partners, equipo, clientes, testimonios y el índice de recursos — generado en cada build desde la misma fuente que las páginas. Pensado para ingesta completa en una sola petición; para consultas puntuales use los endpoints de /api/v1.

  • POST /mcp

    Servidor MCP (JSON-RPC 2.0)

    Endpoint Model Context Protocol sobre transporte Streamable HTTP. Acepta mensajes JSON-RPC 2.0 (initialize, tools/list, tools/call, resources/list, resources/read) y expone las mismas consultas del catálogo como herramientas MCP. El manifiesto está en /.well-known/mcp.json.

Errores

Ninguna respuesta de error devuelve HTML. Toda condición de error — ruta inexistente, método no permitido, parámetro inválido — se sirve como application/json con la misma forma: un code estable para ramificar, un message legible, un hint con la forma de resolverlo y, cuando aplica, los valores válidos en details. 

$ curl -s "https://www.blackit.cl/api/v1/services/no-existe"
{
  "error": {
    "code": "not_found",
    "message": "No existe un servicio con slug 'no-existe'.",
    "status": 404,
    "hint": "Consulte GET /api/v1/services para obtener los slugs válidos.",
    "details": {
      "parameter": "slug",
      "received": "no-existe",
      "availableSlugs": ["roadmap-maduracion-tecnologica", "..."]
    },
    "documentation": "https://www.blackit.cl/desarrolladores"
  }
}
  • not_found HTTP 404 La ruta o el recurso no existe. details incluye los valores válidos cuando los hay.
  • method_not_allowed HTTP 405 La API es de sólo lectura. La cabecera Allow y details.allowed indican los métodos admitidos.
  • invalid_parameter HTTP 400 Un parámetro tiene un valor fuera de rango o de tipo equivocado. details trae el rango o la lista de valores admitidos.
  • missing_parameter HTTP 400 Falta un parámetro obligatorio — por ejemplo q en la búsqueda.
  • upstream_unavailable HTTP 503 El catálogo no se pudo cargar. La respuesta incluye Retry-After.

OpenAPI y function calling

La especificación completa está en /openapi.json (también en /api/openapi.json, /api/v1/openapi.json y /.well-known/openapi.json). Es OpenAPI 3.1 con un operationId único y una descripción en cada operación, parámetros tipados y esquemas de respuesta con $ref — el formato que consumen los conversores a herramientas de function calling de los modelos de lenguaje. 

curl https://www.blackit.cl/openapi.json

Servidor MCP

Las mismas consultas están disponibles como herramientas de Model Context Protocol en /mcp, sobre transporte Streamable HTTP (JSON-RPC 2.0). El manifiesto, con el listado de herramientas, está en /.well-known/mcp.json. 

curl -X POST https://www.blackit.cl/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

CLI

El repositorio del sitio incluye una CLI sin dependencias que envuelve estos endpoints (blackit services, blackit service <slug>, blackit search, blackit company, blackit contact, blackit openapi), pensada para scripts y para agentes que prefieren un comando a una integración HTTP. 

node cli/blackit.mjs search "ISO 27001" --limit 3

Otros recursos legibles por máquina

Recursos para agentes reúne el resto de la superficie máquina-a-máquina del sitio: /llms.txt, /llms-full.txt, /agents.md, el catálogo completo en /api/site.json y la negociación de contenido en Markdown mediante Accept: text/markdown.