Saltar a contenido

Referencia completa de /v1

Esta referencia se genera a partir de la especificación OpenAPI 3.1 de la API, así que describe exactamente las operaciones que el servicio publica. Si prefieres la especificación en bruto (para importarla en un cliente o generar código), está en GET /v1/openapi.json: ver Especificación OpenAPI.

Todas las operaciones son de sólo lectura (GET) salvo las dos escrituras de alertas (POST, ámbito alerts:write), la transición de riesgos (POST, ámbito risks:write), POST /v1/act/proposals, que sólo registra una propuesta que una persona aprueba en la consola, y las dos decisiones sobre propuestas (aprobar y rechazar, ámbito act:decide; aprobar no ejecuta nada). Devuelven 404 si el recurso no existe, 403 si falta el ámbito, y comparten la paginación y el vocabulario de error descritos en Visión general y Errores. Los valores de los ejemplos de esta página son ficticios.

Operaciones

Listar proveedores

GET /v1/vendors

El inventario de terceros del inquilino, más recientes primero por defecto. Los proveedores eliminados (soft-delete) nunca se devuelven.

Ámbito requerido: supply_risk:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(created_at, updated_at, name) Campo de ordenación. Uno de: created_at, updated_at, name.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
q query no string Subcadena, sin distinguir mayúsculas, del nombre o del dominio.
category query no string Coincidencia exacta de categoría, tal como la escribió el inquilino (distingue mayúsculas). La categoría es texto libre SIN vocabulario cerrado, así que no hay lista de valores que publicar: lee category en GET /v1/vendors. Para filtrar por el tipo de tercero, lee vendor_type (x-hs-known-values).
active query no string Filtra por el indicador operativo.
business_criticality query no enum(low, medium, high, critical) Coincidencia exacta de criticidad.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Ejemplo Cloud Provider S.L.",
      "legal_name": "Ejemplo Cloud Provider Sociedad Limitada",
      "domain": "ejemplo-cloud.example",
      "category": "Infraestructura cloud",
      "vendor_type": "cloud",
      "access_level": "critical",
      "business_criticality": "critical",
      "risk_score": 72,
      "created_at": "2026-01-15T09:00:00Z",
      "updated_at": "2026-09-20T11:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 213,
    "total_pages": 5
  }
}

Obtener un proveedor

GET /v1/vendors/{id}

El mismo objeto que la colección, para un único proveedor por id.

Ámbito requerido: supply_risk:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del proveedor.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Ejemplo Cloud Provider S.L.",
    "legal_name": "Ejemplo Cloud Provider Sociedad Limitada",
    "domain": "ejemplo-cloud.example",
    "category": "Infraestructura cloud",
    "vendor_type": "cloud",
    "access_level": "critical",
    "business_criticality": "critical",
    "risk_score": 72,
    "created_at": "2026-01-15T09:00:00Z",
    "updated_at": "2026-09-20T11:30:00Z"
  }
}

Listar alertas

GET /v1/alerts

Alertas de la cadena de suministro del inquilino: degradaciones de puntuación, CVEs críticas, brechas.

Ámbito requerido: supply_risk:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1. No se puede combinar con cursor.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
cursor query no string Cursor opaco de paginación por clave: pasa el next_cursor de la página anterior, con los mismos sort, order y filtros. No se puede combinar con page.
sort query no enum(created_at, updated_at) Campo de ordenación. Uno de: created_at, updated_at.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
status query no enum(open, acknowledged, resolved) Filtra por el estado derivado.
severity query no string Coincidencia exacta de severidad, en el vocabulario de la respuesta (critical
vendor_id query no string Sólo alertas de este proveedor.
since query no string Sólo alertas creadas en este instante RFC 3339 o después.
updated_since query no string Sólo alertas modificadas por última vez en este instante RFC 3339 o después (updated_at), incluidas las creadas mucho antes. Para seguir los cambios, usa sort=updated_at&order=asc.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "vendor_id": "11111111-1111-4111-8111-111111111111",
      "type": "critical_cve",
      "severity": "critical",
      "status": "open",
      "summary": "CVE-2026-99999 detectada en un activo declarado",
      "created_at": "2026-09-25T08:12:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 8,
    "total_pages": 1
  }
}

Obtener una alerta

GET /v1/alerts/{id}

El mismo objeto que la colección, para una única alerta por id.

Ámbito requerido: supply_risk:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la alerta.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "vendor_id": "11111111-1111-4111-8111-111111111111",
    "type": "critical_cve",
    "severity": "critical",
    "status": "open",
    "summary": "CVE-2026-99999 detectada en un activo declarado",
    "created_at": "2026-09-25T08:12:00Z"
  }
}

Listar riesgos

GET /v1/risks

El registro de riesgos del inquilino.

Ámbito requerido: supply_risk:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(created_at, updated_at, inherent_score, residual_score) Campo de ordenación. Uno de: created_at, updated_at, inherent_score, residual_score.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
status query no string Coincidencia exacta de estado. Valores conocidos: identified, assessed, treatment_planned, treatment_implemented, closed. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
domain query no string Coincidencia exacta de dominio. Valores conocidos: vendor, cyber, data, operational, compliance, concentration, strategic, legal, financial, reputational. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
vendor_id query no string Sólo riesgos vinculados a este proveedor.
min_inherent_score query no integer Sólo riesgos cuya puntuación inherente sea al menos ésta.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "title": "Concentración de subprocesadores en un mismo cuarto-parte",
      "status": "accepted",
      "severity": "high",
      "ale_eur": 185000,
      "created_at": "2026-05-02T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 14,
    "total_pages": 1
  }
}

Obtener un riesgo

GET /v1/risks/{id}

El mismo objeto que la colección, para una única entrada de riesgo por id.

Ámbito requerido: supply_risk:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del riesgo.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "title": "Concentración de subprocesadores en un mismo cuarto-parte",
    "status": "accepted",
    "severity": "high",
    "ale_eur": 185000,
    "created_at": "2026-05-02T10:00:00Z"
  }
}

Listar el estado de los controles de un marco

GET /v1/compliance/controls

Requiere el parámetro framework (por ejemplo ens, nis2, iso27001) y el ámbito compliance.<marco>:read de ese marco concreto.

Ámbito requerido: compliance.<framework>:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(control_code, last_evaluated_at) Campo de ordenación. Uno de: control_code, last_evaluated_at.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
framework query sí string Identificador del marco. Uno de: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.
status query no string Coincidencia exacta de estado. Valores conocidos: covered, partial, missing. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "control_ref": "op.acc.5",
      "framework": "ens",
      "title": "Mecanismo de autenticación",
      "status": "implemented",
      "evidence_count": 3
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 74,
    "total_pages": 2
  }
}

Resumen de postura de un marco

GET /v1/compliance/frameworks/{framework}

Porcentaje de controles cubiertos, con evidencia caducada, y sin ninguna, para el marco indicado en la ruta.

Ámbito requerido: compliance.<framework>:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
framework path sí string Identificador del marco. Uno de: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "framework": "ens",
    "controls_total": 74,
    "controls_covered": 61,
    "controls_evidence_expired": 4,
    "controls_without_evidence": 9,
    "updated_at": "2026-09-24T07:00:00Z"
  }
}

Listar evidencias

GET /v1/evidence

Piezas de evidencia del inquilino: propietario, fecha de validez, estado.

Ámbito requerido: evidence:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(created_at, valid_until) Campo de ordenación. Uno de: created_at, valid_until.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
evidence_type query no string Coincidencia exacta de tipo.
source_type query no string Coincidencia exacta de productor.
vendor_id query no string Sólo evidencias de este proveedor.
expiring_before query no string Sólo evidencias con valid_until estrictamente anterior a esta fecha YYYY-MM-DD.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "title": "Política de cifrado en tránsito",
      "evidence_type": "policy",
      "status": "current",
      "owner_email": "seguridad@ejemplo-cliente.example",
      "valid_until": "2027-03-01"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 132,
    "total_pages": 3
  }
}

Obtener una evidencia

GET /v1/evidence/{id}

El mismo objeto que la colección, para una única evidencia por id.

Ámbito requerido: evidence:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la evidencia.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "title": "Política de cifrado en tránsito",
    "evidence_type": "policy",
    "status": "current",
    "owner_email": "seguridad@ejemplo-cliente.example",
    "valid_until": "2027-03-01"
  }
}

Listar endpoints inscritos

GET /v1/endpoints

La flota de endpoints con el agente instalado, con su postura de seguridad agregada.

Ámbito requerido: endpoints:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(enrolled_at, last_seen_at, producer) Campo de ordenación. Uno de: enrolled_at, last_seen_at, producer.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
status query no enum(active, revoked) Coincidencia exacta de estado.
silent_since query no string Agentes vistos por última vez antes de este instante RFC 3339, o nunca vistos.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "hostname": "portatil-ejemplo-042",
      "os_family": "linux",
      "posture_score": 88,
      "last_seen_at": "2026-09-27T06:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 340,
    "total_pages": 7
  }
}

Listar los inquilinos de una cartera MSSP

GET /v1/portfolio/tenants

Los inquilinos cliente que puede seleccionar la clave de cartera (hsp_…) presentada, con la cabecera X-HS-Tenant: los inquilinos propios del MSSP (incluido el interno) y los de sus organizaciones cliente activas, activos o no, con licencia o sin ella, limitados al subconjunto de clientes de la clave si lo tiene. La pertenencia se evalúa en cada petición. Sólo una clave de cartera puede llamar a esta operación, que nunca acepta X-HS-Tenant. Un inquilino es legible cuando active es true y licence_status no es inactive.

Ámbito requerido: portfolio:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(name, slug) Campo de ordenación. Uno de: name, slug.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e",
      "name": "Cliente Ejemplo Logística",
      "slug": "cliente-ejemplo-logistica",
      "organization": {
        "id": "5d0c9e1f-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
        "name": "Grupo Ejemplo"
      },
      "internal": false,
      "active": true,
      "licence_status": "in_force"
    },
    {
      "id": "7e4a1c90-3b2d-4f6e-a1b2-c3d4e5f60718",
      "name": "MSSP Ejemplo — Interno",
      "slug": "mssp-ejemplo-interno",
      "organization": {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "MSSP Ejemplo"
      },
      "internal": true,
      "active": true,
      "licence_status": "grace"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 2,
    "total": 4,
    "total_pages": 2
  }
}

Describir la credencial que llama

GET /v1/me

Quién es la credencial presentada: su tipo y sus ámbitos, y el inquilino y la organización que lee (una clave de API de inquilino o un token OAuth), o la organización MSSP a la que pertenece y cuántos inquilinos alcanza (una clave de cartera; los inquilinos están en GET /v1/portfolio/tenants). Describe sólo a quien llama: ningún otro inquilino, ningún secreto, nunca la clave ni su hash. Cualquier credencial válida puede llamarla: NO requiere ámbito, y usa la misma autenticación y los mismos límites de tasa que el resto de operaciones. Nunca acepta X-HS-Tenant.

Ámbito requerido: ninguno

Parámetros:

Sin parámetros.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "credential": {
      "type": "tenant",
      "prefix": null,
      "scopes": [
        "supply_risk:read"
      ]
    },
    "tenant": {
      "id": "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e",
      "name": "Cliente Ejemplo Logística",
      "type": "direct"
    },
    "organization": {
      "id": "5d0c9e1f-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Grupo Ejemplo",
      "type": "direct"
    },
    "portfolio": null
  }
}

Listar informes generados

GET /v1/reports

Los informes generados para el inquilino, más recientes primero por defecto. Sólo metadatos: el contenido del informe se obtiene como fichero con downloadReport cuando su status es completed. Para recoger los nuevos, usa since con order=asc.

Ámbito requerido: reports:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(created_at, period_end) Campo de ordenación. Uno de: created_at, period_end.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
report_type query no string Coincidencia exacta de tipo. Valores conocidos: monthly, vendor_risk, nis2_compliance, ens, cyberbrief, compliance, security_posture, board_report. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada.
status query no string Coincidencia exacta de estado. Valores conocidos: generating, completed, failed. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada.
since query no string Sólo informes creados en este instante RFC 3339 o después.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "report_type": "board_report",
      "title": "Informe del consejo T3",
      "period_start": "2026-07-01",
      "period_end": "2026-09-30",
      "status": "completed",
      "created_at": "2026-10-01T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 12,
    "total_pages": 1
  }
}

Obtener un informe

GET /v1/reports/{id}

El mismo objeto que la colección, para un único informe por id, más los formatos en que puede descargarse ahora (download_formats): vacío mientras no está completed o si su contenido no tiene renderizador (en ese caso, descárgalo desde la consola como Markdown o JSON).

Ámbito requerido: reports:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del informe.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "report_type": "board_report",
    "title": "Informe del consejo T3",
    "period_start": "2026-07-01",
    "period_end": "2026-09-30",
    "status": "completed",
    "created_at": "2026-10-01T08:00:00Z",
    "download_formats": [
      "pdf",
      "xlsx"
    ]
  }
}

Descargar el fichero de un informe

GET /v1/reports/{id}/download

El informe como fichero (PDF o XLSX), en el cuerpo de la respuesta con Content-Disposition: attachment; nunca un enlace. Cada entrega queda en el registro de auditoría del inquilino con la credencial que la recibió. Responde 409 con error.details.code: REPORT_NOT_READY si el informe aún se está generando o falló (error.details.status), FORMAT_UNSUPPORTED si su contenido no tiene renderizador para ese formato (error.details.formats lista los que tiene) y FILE_TOO_LARGE si el fichero supera el tamaño máximo que sirve la operación (error.details.limit_bytes, 20 MiB); en ninguno de los tres se envía el fichero.

Ámbito requerido: reports:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del informe.
format query no enum(pdf, xlsx) Formato del fichero, uno de: pdf, xlsx. Por defecto, pdf. getReport indica en qué formatos puede servirse un informe (download_formats).
locale query no enum(es, en, de, fr, it, eu) Idioma del fichero, uno de: es, en, de, fr, it, eu. Por defecto, en.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Respuesta (200, valores ficticios): El cuerpo es el fichero binario, no JSON. Cabeceras de ejemplo:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="Informe_del_consejo_T3.pdf"
Content-Length: 184213
X-HS-Tenant: 0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e

Listar solicitudes de cambio

GET /v1/changes

El registro de gestión de cambios del inquilino: estado, tipo, riesgo, fechas previstas y de ejecución, el resultado de la revisión y cuántas decisiones de aprobación tiene cada cambio. Sólo lectura; el texto libre y las personas no se publican. Se sirve cuando hay al menos un marco de cumplimiento activado para el inquilino.

Ámbito requerido: changes:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(created_at, planned_start_at, implemented_at) Campo de ordenación. Uno de: created_at, planned_start_at, implemented_at.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
status query no enum(draft, submitted, approved, rejected, scheduled, implementing, implemented, failed, rolled_back, in_review, closed, cancelled) Coincidencia exacta de estado.
change_type query no enum(normal, emergency) Coincidencia exacta de tipo.
category query no enum(infrastructure, application, configuration, access, vendor, other) Coincidencia exacta de categoría.
created_from query no string Sólo cambios creados en esta fecha YYYY-MM-DD (UTC) o después.
created_to query no string Sólo cambios creados en esta fecha YYYY-MM-DD (UTC) o antes.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "99999999-9999-4999-8999-999999999999",
      "ref": "CHG-2026-0042",
      "title": "Actualización del cortafuegos perimetral",
      "status": "closed",
      "change_type": "normal",
      "category": "infrastructure",
      "risk_level": "medium",
      "planned_start_at": "2026-10-10T22:00:00Z",
      "planned_end_at": "2026-10-11T02:00:00Z",
      "implemented_at": "2026-10-10T23:15:00Z",
      "closed_at": "2026-10-14T09:00:00Z",
      "outcome": "successful",
      "approved_without_second_person": false,
      "external_ref": null,
      "approvals": {
        "approved": 2,
        "rejected": 0
      },
      "created_at": "2026-10-05T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 37,
    "total_pages": 1
  }
}

Listar incidentes

GET /v1/incidents

El registro de incidentes del inquilino: tipo, severidad, estado, las fechas clave y, por incidente, sus plazos de notificación regulatoria (DORA, NIS2, RGPD, Ley de IA) en notifications, cada uno con su etapa, su estado (calculado en cada lectura, como en la consola), su vencimiento y la fecha en que se presentó el informe que lo cumplió. Sólo lectura; no se publican el texto libre, salvo el título, ni las personas. Se sirve mientras el inquilino tiene el módulo supply_risk.

Ámbito requerido: incidents:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(detected_at, created_at, updated_at) Campo de ordenación. Uno de: detected_at, created_at, updated_at.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
status query no string Coincidencia exacta de estado. Valores conocidos: open, investigating, contained, resolved, closed. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
severity query no string Coincidencia exacta de severidad. Valores conocidos: critical, high, medium, low. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
type query no string Coincidencia exacta de tipo. Valores conocidos: cybersecurity, service_disruption, data_breach, system_failure, third_party, fraud, physical, compliance. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "reference": "INC-2026-0007",
      "title": "Cifrado de ficheros en el servidor de nóminas",
      "type": "cybersecurity",
      "severity": "high",
      "status": "investigating",
      "phase": "response",
      "occurred_at": "2026-11-10T06:40:00Z",
      "detected_at": "2026-11-10T07:15:00Z",
      "classified_major_at": null,
      "contained_at": "2026-11-10T11:00:00Z",
      "recovered_at": null,
      "resolved_at": null,
      "closed_at": null,
      "personal_data_breached": true,
      "cross_border": false,
      "ai_system_involved": false,
      "aiact_role": null,
      "gdpr_role": "controller",
      "vendor_id": null,
      "notifications": [
        {
          "framework": "gdpr",
          "stage": "dpa_notification",
          "status": "met",
          "anchor": "awareness",
          "due_at": "2026-11-13T07:15:00Z",
          "submitted_at": "2026-11-12T16:30:00Z"
        },
        {
          "framework": "nis2",
          "stage": "early_warning",
          "status": "met",
          "anchor": "awareness",
          "due_at": "2026-11-11T07:15:00Z",
          "submitted_at": "2026-11-10T18:00:00Z"
        },
        {
          "framework": "nis2",
          "stage": "notification",
          "status": "pending",
          "anchor": "awareness",
          "due_at": "2026-11-13T07:15:00Z",
          "submitted_at": null
        },
        {
          "framework": "nis2",
          "stage": "final",
          "status": "awaiting",
          "anchor": "previous_submission",
          "due_at": null,
          "submitted_at": null
        }
      ],
      "created_at": "2026-11-10T07:20:00Z",
      "updated_at": "2026-11-12T16:31:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 3,
    "total_pages": 1
  }
}

Obtener un incidente

GET /v1/incidents/{id}

El mismo objeto que la colección, para un único incidente por id. Un id de otro inquilino responde 404, como uno que no existe.

Ámbito requerido: incidents:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del incidente.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "reference": "INC-2026-0007",
    "title": "Cifrado de ficheros en el servidor de nóminas",
    "type": "cybersecurity",
    "severity": "high",
    "status": "investigating",
    "phase": "response",
    "occurred_at": "2026-11-10T06:40:00Z",
    "detected_at": "2026-11-10T07:15:00Z",
    "classified_major_at": null,
    "contained_at": "2026-11-10T11:00:00Z",
    "recovered_at": null,
    "resolved_at": null,
    "closed_at": null,
    "personal_data_breached": true,
    "cross_border": false,
    "ai_system_involved": false,
    "aiact_role": null,
    "gdpr_role": "controller",
    "vendor_id": null,
    "notifications": [
      {
        "framework": "gdpr",
        "stage": "dpa_notification",
        "status": "met",
        "anchor": "awareness",
        "due_at": "2026-11-13T07:15:00Z",
        "submitted_at": "2026-11-12T16:30:00Z"
      },
      {
        "framework": "nis2",
        "stage": "early_warning",
        "status": "met",
        "anchor": "awareness",
        "due_at": "2026-11-11T07:15:00Z",
        "submitted_at": "2026-11-10T18:00:00Z"
      },
      {
        "framework": "nis2",
        "stage": "notification",
        "status": "pending",
        "anchor": "awareness",
        "due_at": "2026-11-13T07:15:00Z",
        "submitted_at": null
      },
      {
        "framework": "nis2",
        "stage": "final",
        "status": "awaiting",
        "anchor": "previous_submission",
        "due_at": null,
        "submitted_at": null
      }
    ],
    "created_at": "2026-11-10T07:20:00Z",
    "updated_at": "2026-11-12T16:31:00Z"
  }
}

Listar sistemas de IA

GET /v1/ai-systems

El registro de sistemas de IA del inquilino: clase de riesgo según la Ley de IA, estado del ciclo de vida, tipo, unidad responsable, proveedor y categorías de datos que trata cada uno. Sólo lectura; no se publican el texto libre (finalidad, justificación) ni las personas. El registro no guarda el rol de la Ley de IA (proveedor o responsable del despliegue) ni una fecha de revisión por sistema, así que no se publican. Se sirve mientras el inquilino tiene el módulo ai_governance.

Ámbito requerido: ai_systems:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(created_at, updated_at, name) Campo de ordenación. Uno de: created_at, updated_at, name.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, desc.
risk_class query no string Coincidencia exacta de clase de riesgo. Valores conocidos: prohibited, high_risk, transparency, minimal. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
lifecycle_status query no string Coincidencia exacta de estado del ciclo de vida. Valores conocidos: planned, pilot, in_use, retired. Vocabulario abierto: cualquier otro valor se compara tal cual y no coincide con nada, y la respuesta lleva entonces una entrada en meta.warnings y la cabecera X-HS-Unknown-Filter.
vendor_id query no string Sólo sistemas suministrados por este proveedor.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "Asistente de atención al cliente",
      "risk_class": "transparency",
      "lifecycle_status": "in_use",
      "system_type": "llm",
      "department": "Atención al cliente",
      "vendor_id": "66666666-6666-4666-8666-666666666666",
      "data_categories": [
        "customer",
        "personal"
      ],
      "created_at": "2026-09-30T10:00:00Z",
      "updated_at": "2026-10-21T08:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 4,
    "total_pages": 1
  }
}

Obtener un sistema de IA

GET /v1/ai-systems/{id}

El mismo objeto que la colección, para un único sistema por id. Un id de otro inquilino responde 404, como uno que no existe.

Ámbito requerido: ai_systems:read

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del sistema de IA.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "55555555-5555-4555-8555-555555555555",
    "name": "Asistente de atención al cliente",
    "risk_class": "transparency",
    "lifecycle_status": "in_use",
    "system_type": "llm",
    "department": "Atención al cliente",
    "vendor_id": "66666666-6666-4666-8666-666666666666",
    "data_categories": [
      "customer",
      "personal"
    ],
    "created_at": "2026-09-30T10:00:00Z",
    "updated_at": "2026-10-21T08:45:00Z"
  }
}

Reconocer una alerta

POST /v1/alerts/{id}/acknowledge

Marca una alerta abierta como tomada («alguien está en ello»). Sigue sin resolverse. Repetirlo sobre una alerta ya reconocida devuelve su estado actual con changed: false y no escribe nada; si la alerta ya está resuelta responde 409 ALERT_RESOLVED. La clave actúa con el rol del usuario que la creó, leído en cada petición, y no hace falta confirmación interactiva. Una clave de cartera MSSP (hsp_…) nombra el inquilino cliente con X-HS-Tenant; un inquilino fuera de su conjunto responde 404 (TENANT_NOT_FOUND). Las escrituras tienen su propio presupuesto de peticiones por clave (error.details.scope: "write_key"), separado del de lectura, y se rechazan mientras la licencia está en periodo de gracia. Cada cambio escribe una entrada en la auditoría del inquilino con el id de la clave (nunca el secreto), el usuario que actúa, el estado anterior y el nuevo, y el motivo. El cuerpo es un objeto JSON; una clave desconocida es un 400.

Ámbito requerido: alerts:write

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la alerta.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Cuerpo de la petición: JSON. reason es opcional (500 caracteres como máximo). Una clave desconocida es un 400.

Ejemplo (curl):

curl -X POST "https://api.hodeishield.com/v1/alerts/33333333-3333-4333-8333-333333333333/acknowledge" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Triaged by the SOAR playbook PB-114"}'

Con una clave de cartera hsp_… añade -H "X-HS-Tenant: <id del inquilino>".

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "acknowledged",
    "acknowledged_at": "2026-11-12T10:15:00Z",
    "resolved_at": null,
    "resolution_reason": null,
    "updated_at": "2026-11-12T10:15:00Z"
  },
  "changed": true
}

Resolver una alerta

POST /v1/alerts/{id}/resolve

Cierra una alerta abierta o reconocida, con el motivo. Repetirlo sobre una alerta ya resuelta devuelve su estado actual con changed: false y no escribe nada (se conserva el primer motivo). Una alerta crítica o alta sólo la cierra una clave cuyo creador podría cerrarla en la consola: la clave de un analista MSSP cierra sólo alertas medias y bajas (403 ROLE_NOT_PERMITTED). La clave actúa con el rol del usuario que la creó, leído en cada petición, y no hace falta confirmación interactiva. Una clave de cartera MSSP (hsp_…) nombra el inquilino cliente con X-HS-Tenant; un inquilino fuera de su conjunto responde 404 (TENANT_NOT_FOUND). Las escrituras tienen su propio presupuesto de peticiones por clave (error.details.scope: "write_key"), separado del de lectura, y se rechazan mientras la licencia está en periodo de gracia. Cada cambio escribe una entrada en la auditoría del inquilino con el id de la clave (nunca el secreto), el usuario que actúa, el estado anterior y el nuevo, y el motivo. Un cambio concurrente entre la lectura y la escritura responde 409 ALERT_STATE_CHANGED.

Ámbito requerido: alerts:write

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la alerta.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Cuerpo de la petición: JSON. reason es obligatorio (al menos dos caracteres no vacíos, 500 como máximo).

Ejemplo (curl):

curl -X POST "https://api.hodeishield.com/v1/alerts/33333333-3333-4333-8333-333333333333/resolve" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Patched in the vendor tenant; verified by the SOAR playbook PB-114"}'

Con una clave de cartera hsp_… añade -H "X-HS-Tenant: <id del inquilino>".

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "resolved",
    "acknowledged_at": "2026-11-12T10:15:00Z",
    "resolved_at": "2026-11-12T10:42:00Z",
    "resolution_reason": "Patched in the vendor tenant; verified by the SOAR playbook PB-114",
    "updated_at": "2026-11-12T10:42:00Z"
  },
  "changed": true
}

Proponer una acción que una persona aprueba en la consola

POST /v1/act/proposals

Registra una PROPUESTA de una clase de acción. Nada cambia hasta que una persona del inquilino la aprueba en la consola, que la ejecuta con el rol propio del aprobador; una propuesta que nadie decide caduca a los 7 días. Sólo puede llamarla un token de acceso OAuth emitido para el servidor MCP de HodeiShield, con act:propose: cualquier otra credencial recibe 403 CREDENTIAL_NOT_ALLOWED. El proponente es el usuario del token y la propuesta queda ligada a la concesión del token (aplicación, usuario e inquilino); una petición no puede nombrar otra. Una persona de tu organización la aprueba en la consola. El mismo contenido propuesto otra vez por la misma concesión responde 200 con la propuesta existente.

Ámbito requerido: act:propose + the read scope of the class's module (supply_risk:read for schedule_vendor_scan and request_vendor_evidence; none for create_task)

Parámetros:

Parámetro En Obligatorio Tipo Descripción
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "id": "3c9d1e2f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "status": "proposed",
  "expires_at": "2026-11-22T09:00:00Z"
}

Estado de una propuesta hecha por esta aplicación

GET /v1/act/proposals/{id}

El estado de una propuesta hecha por ESTA concesión (la misma aplicación, usuario e inquilino). Nunca el contenido ni quién la decidió. Un id que esta concesión no propuso responde 404, igual que uno que no existe. Sólo puede llamarla un token de acceso OAuth emitido para el servidor MCP de HodeiShield, con act:propose.

Ámbito requerido: act:propose

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la propuesta, tal como lo devolvió createActProposal.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "status": "refused",
  "refusal_reason": "grant_revoked",
  "executed_at": null
}

Mover un riesgo en su ciclo de vida

POST /v1/risks/{id}/transition

Cambia el estado del ciclo de vida de una entrada del registro de riesgos, igual que la consola: sólo las transiciones que el ciclo permite (identified → assessed; assessed → treatment_planned; treatment_planned → treatment_implemented; treatment_implemented → closed; closed → assessed); cualquier otra es un 409 TRANSITION_NOT_ALLOWED que nombra el estado actual y a dónde puede ir. Pedir el estado que la entrada ya tiene devuelve su estado actual con changed: false y no escribe nada. La clave actúa con el rol del usuario que la creó, leído en cada petición: sólo un rol de administrador del inquilino puede mover un riesgo (403 ROLE_NOT_PERMITTED en otro caso), y un creador degradado, suspendido, eliminado o retirado del inquilino le quita el poder a la clave (403 WRITE_ACTOR_UNRESOLVED o ROLE_NOT_PERMITTED). Una clave de inquilino (hsk_…) escribe en su propio inquilino. Una clave de cartera MSSP (hsp_…) nombra el inquilino cliente con X-HS-Tenant, igual que en las lecturas: un inquilino fuera de su conjunto es un 404 (TENANT_NOT_FOUND); sólo un administrador de la organización MSSP puede conceder risks:write a una clave de cartera. Las escrituras tienen su propio presupuesto de peticiones por clave (error.details.scope: "write_key"), separado del de lectura, y se rechazan mientras la licencia está en periodo de gracia. Cada cambio escribe la fila de historial del registro (estado anterior, nuevo, nota y usuario que actúa) y una entrada en la auditoría del inquilino con el id de la clave (nunca el secreto). Un id de otro inquilino responde el mismo 404 que uno que no existe. El cuerpo es un objeto JSON; una clave desconocida es un 400.

Ámbito requerido: risks:write

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador del riesgo.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Cuerpo de la petición: JSON. to_status es obligatorio; note es opcional (2000 caracteres como máximo). Una clave desconocida es un 400.

Ejemplo (curl):

curl -X POST "https://api.hodeishield.com/v1/risks/33333333-3333-4333-8333-333333333333/transition" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to_status":"assessed","note":"Scored after the vendor review"}'

Con una clave de cartera hsp_… añade -H "X-HS-Tenant: <id del inquilino>".

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "assessed",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "changed": true
}

Propuestas pendientes de decisión

GET /v1/act/inbox

Las propuestas ACT del inquilino que QUIEN LLAMA puede aprobar: aún pendientes de decisión (estado proposed, sin caducar) y admitidas por las reglas de aprobación de la propia consola para esa persona (el rol que exigen la clase de acción y la política del inquilino, el módulo que necesita la clase, el doble control, y no una propuesta hecha a través del MCP, que la consola todavía no puede aprobar). Una propuesta que quien llama no podría aprobar no aparece, y pagination.total cuenta sólo lo listado. Mientras las acciones están en pausa una propuesta listada se rechaza igualmente al aprobar (ACTIONS_PAUSED), como en la consola. Por defecto, la que caduca antes primero, cada una con EXACTAMENTE lo que escribiría (payload) y por qué se propuso. Aprobar no la ejecuta: la ejecución sigue siendo un paso aparte en la consola. Igual que una decisión, la bandeja exige un inicio de sesión confirmado en los últimos 15 minutos (403 STEP_UP_REQUIRED en otro caso). Sólo puede llamarla un token de acceso de usuario de la CLI de HodeiShield con act:decide (un ámbito sólo OAuth, desactivado salvo que el servidor lo habilite): una clave de API de inquilino, una clave de cartera MSSP, un token emitido para el servidor MCP de HodeiShield y cualquier otra aplicación reciben 403 CREDENTIAL_NOT_ALLOWED.

Ámbito requerido: act:decide

Parámetros:

Parámetro En Obligatorio Tipo Descripción
page query no integer Número de página (empieza en 1). Por defecto, 1.
per_page query no integer Elementos por página, 1..200. Por defecto, 50.
sort query no enum(expires_at, created_at) Campo de ordenación. Uno de: expires_at, created_at.
order query no enum(asc, desc) Dirección de ordenación. Por defecto, asc (primero la propuesta que caduca antes).
class query no enum(create_risk_entry, create_task, request_vendor_evidence, schedule_vendor_scan, set_vendor_criticality, open_vendor_review, add_roadmap_item) Sólo propuestas de esta clase de acción. Una de: create_risk_entry, create_task, request_vendor_evidence, schedule_vendor_scan, set_vendor_criticality, open_vendor_review, add_roadmap_item.
module query no string Sólo propuestas cuya clase de acción necesita este módulo (supply_risk, …). Un módulo que ninguna clase necesita no coincide con nada.
expires_before query no string RFC 3339. Sólo propuestas que dejan de poder decidirse antes de este instante.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": [
    {
      "id": "3c9d1e2f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "class": "create_task",
      "module": "supply_risk",
      "payload_kind": "create_task",
      "payload": {
        "title": "Review the vendor’s new subprocessor list"
      },
      "rationale": "A new subprocessor appeared in the vendor’s latest notice.",
      "confidence": 0.8,
      "proposed_via": "agent.vendor-watch",
      "proposed_by_you": false,
      "created_at": "2026-11-19T08:00:00Z",
      "expires_at": "2026-11-26T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1
  }
}

Aprobar una propuesta

POST /v1/act/proposals/{id}/approve

Aprueba una propuesta pendiente de decisión. NO la ejecuta, y ninguna operación de /v1 lo hace: la acción aprobada se ejecuta en la consola antes de approval_expires_at (15 minutos), como tras una aprobación hecha allí. Una aprobación es consentimiento para ejecutar ahora, no una autorización permanente. La decisión pasa por el propio servicio de la consola, así que sus reglas son las de la consola: el rol que exigen la clase de acción y la política del inquilino, el módulo que necesita la clase, el doble control (el usuario para quien se hizo la propuesta no puede aprobarla cuando aplica), la caducidad, una sola decisión por propuesta y los interruptores de pausa. Toda denegación lleva un error.details.code estable y, junto a él, el motivo ACT (error.details.reason). Quien decide es el usuario del token, con su rol leído en cada petición. Una decisión exige un inicio de sesión confirmado en los últimos 15 minutos (403 STEP_UP_REQUIRED en otro caso: vuelve a iniciar sesión, lo que pide tu segundo factor o la contraseña). Como máximo 30 decisiones por minuto y persona (429, error.details.scope decision_user). Cada decisión y cada denegación escribe una entrada en la auditoría del inquilino con la persona, la aplicación y el motivo; el libro mayor ACT también registra la decisión. Un id de otro inquilino responde el mismo 404 que uno que no existe. Sólo puede llamarla un token de acceso de usuario de la CLI de HodeiShield con act:decide (un ámbito sólo OAuth, desactivado salvo que el servidor lo habilite): una clave de API de inquilino, una clave de cartera MSSP, un token emitido para el servidor MCP de HodeiShield y cualquier otra aplicación reciben 403 CREDENTIAL_NOT_ALLOWED.

Ámbito requerido: act:decide

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la propuesta, tal como lo devolvió listPendingActProposals.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Cuerpo de la petición: JSON. reason es obligatorio (de 1 a 1000 caracteres). Una clave desconocida es un 400.

Ejemplo (curl):

curl -X POST "https://api.hodeishield.com/v1/act/proposals/33333333-3333-4333-8333-333333333333/approve" \
  -H "Authorization: Bearer $HODEISHIELD_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Reviewed the payload; it matches the vendor notice"}'

El token de acceso es el de un usuario de la CLI de HodeiShield con act:decide; no sirve una clave de API.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "3c9d1e2f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "status": "approved",
    "approval_expires_at": "2026-11-19T09:45:00Z",
    "ledger_entry_id": "5d0e2f3a-5b6c-4d7e-9f80-1b2c3d4e5f60"
  }
}

Rechazar una propuesta

POST /v1/act/proposals/{id}/reject

Rechaza una propuesta pendiente de decisión, con el motivo; no se ejecuta nada. Como en la consola, cualquier rol que pueda escribir puede rechazar, incluido el usuario para quien se hizo la propuesta. La decisión pasa por el propio servicio de la consola, así que sus reglas son las de la consola: el rol que exigen la clase de acción y la política del inquilino, el módulo que necesita la clase, el doble control, la caducidad, una sola decisión por propuesta y los interruptores de pausa. Toda denegación lleva un error.details.code estable y, junto a él, el motivo ACT (error.details.reason). Quien decide es el usuario del token, con su rol leído en cada petición. Una decisión exige un inicio de sesión confirmado en los últimos 15 minutos (403 STEP_UP_REQUIRED en otro caso: vuelve a iniciar sesión, lo que pide tu segundo factor o la contraseña). Como máximo 30 decisiones por minuto y persona (429, error.details.scope decision_user). Cada decisión y cada denegación escribe una entrada en la auditoría del inquilino con la persona, la aplicación y el motivo; el libro mayor ACT también registra la decisión. Un id de otro inquilino responde el mismo 404 que uno que no existe. Sólo puede llamarla un token de acceso de usuario de la CLI de HodeiShield con act:decide (un ámbito sólo OAuth, desactivado salvo que el servidor lo habilite): una clave de API de inquilino, una clave de cartera MSSP, un token emitido para el servidor MCP de HodeiShield y cualquier otra aplicación reciben 403 CREDENTIAL_NOT_ALLOWED.

Ámbito requerido: act:decide

Parámetros:

Parámetro En Obligatorio Tipo Descripción
id path sí string Identificador de la propuesta, tal como lo devolvió listPendingActProposals.
X-HS-Tenant header no string El inquilino que se lee, por su id (un UUID, en mayúsculas o minúsculas). OBLIGATORIA con una clave de cartera (hsp_…); con una clave de API de inquilino o un token OAuth, opcional y aceptada sólo si coincide con el inquilino de la propia credencial. Nunca un slug.

Cuerpo de la petición: JSON. reason es obligatorio (de 1 a 1000 caracteres). Una clave desconocida es un 400.

Ejemplo (curl):

curl -X POST "https://api.hodeishield.com/v1/act/proposals/33333333-3333-4333-8333-333333333333/reject" \
  -H "Authorization: Bearer $HODEISHIELD_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"The payload does not match what the vendor announced"}'

El token de acceso es el de un usuario de la CLI de HodeiShield con act:decide; no sirve una clave de API.

Ejemplo de respuesta (200, valores ficticios):

{
  "data": {
    "id": "3c9d1e2f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "status": "rejected",
    "approval_expires_at": null,
    "ledger_entry_id": "5d0e2f3a-5b6c-4d7e-9f80-1b2c3d4e5f60"
  }
}