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:
Ver el vocabulario completo en Errores.
Siguiente paso¶
- Autenticación y claves de API
- Referencia completa de las operaciones
- Especificación OpenAPI en bruto
- Versionado y deprecación
- Política de deprecación
- Límites de uso
- Resolución de problemas
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_keycon tu credencial;base_urlapunta ahttps://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).