Saltar a contenido

Visión general de la API

Especificación OpenAPI 3.1 de la API pública: https://api.hodeishield.com/v1/openapi.json (sin autenticación). Referencia navegable: Referencia completa.

Tu primera llamada

Crea una clave de API en la consola (Configuración › Integraciones y desarrollo › Integraciones › API Key) y guárdala en una variable de entorno. Una clave de inquilino empieza por hsk_. GET /v1/me no exige ningún ámbito y te dice con qué credencial has entrado.

export HODEISHIELD_API_KEY="hsk_..."   # tu clave; nunca en el código

curl -sS https://api.hodeishield.com/v1/me \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY"

Después, una lista paginada de proveedores (ámbito supply_risk:read):

curl -sS "https://api.hodeishield.com/v1/vendors?per_page=10" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY"

La respuesta trae data y pagination (page, per_page, total, total_pages). Cada respuesta autenticada incluye las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Un 401 significa clave ausente, revocada, caducada o desconocida; un 403, que falta el ámbito. Más en Autenticación y Errores.

Los filtros comparan por igualdad exacta. Si el valor de severity (alertas), domain o status (riesgos) o status (controles de cumplimiento) no es uno de los publicados, la respuesta sigue siendo 200 con lo que coincide, y añade meta.warnings[] (param, value, known) y la cabecera X-HS-Unknown-Filter, para que un error de escritura no parezca «sin resultados». La category de los proveedores es texto libre y no se comprueba. Detalle en Versionado.

Disponibilidad

La API pública /v1 se sirve en api.hodeishield.com. Su contrato está congelado y versionado: la versión actual del contrato es 2026-11-21 (campo info.version del documento OpenAPI). Para usarla necesitas una credencial con los ámbitos de cada operación y una licencia en vigor en tu inquilino; sin licencia en vigor, la API responde 403 (ver Errores). Consulta la política de versionado, la política de deprecación y los límites de uso.

Plan

El acceso de lectura a /v1 forma parte de tu licencia de HodeiShield. Las peticiones están sujetas a límites de uso que se aplican por clave y por inquilino.

Qué es /v1

/v1 es el contrato público y versionado de HodeiShield (versión 1 del contrato): un conjunto de operaciones de sólo lectura sobre los datos de tu inquilino (proveedores, alertas, riesgos, cumplimiento, evidencias y endpoints), más dos escrituras sobre alertas (reconocer y resolver), pensado para que sistemas externos —un SIEM, un data warehouse, un panel propio— consuman tus datos sin depender de la sesión de usuario de la consola.

No es un espejo de todo lo que hace la consola: es la superficie que se compromete a no romper sin abrir una versión nueva (/v2).

Operaciones

Operación Método y ruta Ámbito requerido
Proveedores GET /v1/vendors, GET /v1/vendors/{id} supply_risk:read
Alertas GET /v1/alerts, GET /v1/alerts/{id} supply_risk:read
Reconocer una alerta POST /v1/alerts/{id}/acknowledge alerts:write
Resolver una alerta POST /v1/alerts/{id}/resolve alerts:write
Riesgos GET /v1/risks, GET /v1/risks/{id} supply_risk:read
Controles de cumplimiento GET /v1/compliance/controls?framework=… compliance.<marco>:read
Postura por marco GET /v1/compliance/frameworks/{framework} compliance.<marco>:read
Evidencias GET /v1/evidence, GET /v1/evidence/{id} evidence:read
Endpoints GET /v1/endpoints endpoints:read
Informes GET /v1/reports, GET /v1/reports/{id}, GET /v1/reports/{id}/download (fichero PDF o XLSX) reports:read
Cambios GET /v1/changes (registro de gestión de cambios; se sirve cuando al menos un marco de cumplimiento está activado en el inquilino) changes:read
Incidentes GET /v1/incidents, GET /v1/incidents/{id} (registro de incidentes con sus plazos de notificación regulatoria) incidents:read
Sistemas de IA GET /v1/ai-systems, GET /v1/ai-systems/{id} (registro de sistemas de IA) ai_systems:read
Quién soy GET /v1/me ninguno (cualquier credencial válida)
Inquilinos de la cartera GET /v1/portfolio/tenants (sólo clave de cartera MSSP) portfolio:read
Documento OpenAPI GET /v1/openapi.json ninguno

El resto de operaciones son GET. Cualquier método que una ruta no sirve responde 405 Method Not Allowed, con Allow indicando el que sí. Las únicas escrituras de /v1 son las dos operaciones de alertas de arriba, bajo el ámbito separado alerts:write (ver Reconocer y resolver alertas), y POST /v1/act/proposals, disponible sólo para tokens OAuth del servidor MCP con el ámbito act:propose, que registra una propuesta que una persona de tu organización aprueba en la consola.

Forma común de la respuesta

Paginación — todas las colecciones aceptan page (desde 1) y per_page (1–200, 50 por defecto), y devuelven:

{
  "data": [ /* … */ ],
  "pagination": { "page": 1, "per_page": 50, "total": 213, "total_pages": 5 }
}

Errores — siempre el mismo sobre:

{ "error": { "code": "not_found", "message": "…", "request_id": "…", "details": {} } }

Ver el vocabulario completo en Errores.

Siguiente paso

Descargas

  • Colección de Postman (v2.1): una petición por operación. Impórtala en Postman y define la variable de colección api_key con tu credencial; base_url apunta a https://api.hodeishield.com. No contiene ninguna clave.
  • Documento OpenAPI 3.1 en bruto: GET https://api.hodeishield.com/v1/openapi.json (sin autenticación; ver Especificación OpenAPI).