Skip to content

Complete /v1 reference

This reference is generated from the API's OpenAPI 3.1 specification, so it describes exactly the operations the service publishes. If you want the raw specification (to import into a client or to generate code), it is at GET /v1/openapi.json: see OpenAPI specification.

Every operation is read-only (GET) except the two alert writes (POST, scope alerts:write), the risk transition (POST, scope risks:write), POST /v1/act/proposals, which only records a proposal that a person approves in the console, and the two proposal decisions (approve and reject, scope act:decide; approving executes nothing). They return 404 if the resource does not exist, 403 if a scope is missing, and shares the pagination and error vocabulary described in Overview and Errors. Example values on this page are fictitious.

Operations

List third parties

GET /v1/vendors

The tenant's third-party inventory, newest first by default. Soft-deleted vendors are never returned.

Required scope: supply_risk:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(created_at, updated_at, name) Field to order by. One of: created_at, updated_at, name.
order query no enum(asc, desc) Sort direction. Defaults to desc.
q query no string Case-insensitive substring of the name or the domain.
category query no string Exact category match, as the tenant wrote it (case-sensitive). Category is free text with NO closed vocabulary, so there is no list of values to publish: read category from GET /v1/vendors. To filter by the kind of third party, read vendor_type (x-hs-known-values).
active query no string Filter by the operational flag.
business_criticality query no enum(low, medium, high, critical) Exact criticality match.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one third party

GET /v1/vendors/{id}

The same object as the collection, for a single vendor by id.

Required scope: supply_risk:read

Parameters:

Parameter In Required Type Description
id path yes string Vendor identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
  }
}

List supply-chain alerts

GET /v1/alerts

The tenant's supply-chain alerts: score degradations, critical CVEs, breaches.

Required scope: supply_risk:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1. Cannot be combined with cursor.
per_page query no integer Items per page, 1..200. Defaults to 50.
cursor query no string Opaque keyset cursor: pass the next_cursor of the previous page, with the same sort, order and filters. Cannot be combined with page.
sort query no enum(created_at, updated_at) Field to order by. One of: created_at, updated_at.
order query no enum(asc, desc) Sort direction. Defaults to desc.
status query no enum(open, acknowledged, resolved) Filter by the derived status.
severity query no string Exact severity match, in the vocabulary the response uses (critical
vendor_id query no string Only alerts about this vendor.
since query no string Only alerts created at or after this RFC 3339 instant.
updated_since query no string Only alerts last changed at or after this RFC 3339 instant (updated_at), including ones created long before it. Poll changes with sort=updated_at&order=asc.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one alert

GET /v1/alerts/{id}

The same object as the collection, for a single alert by id.

Required scope: supply_risk:read

Parameters:

Parameter In Required Type Description
id path yes string Alert identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
  }
}

List risk-register entries

GET /v1/risks

The tenant's risk register.

Required scope: supply_risk:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(created_at, updated_at, inherent_score, residual_score) Field to order by. One of: created_at, updated_at, inherent_score, residual_score.
order query no enum(asc, desc) Sort direction. Defaults to desc.
status query no string Exact status match. Known values: identified, assessed, treatment_planned, treatment_implemented, closed. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
domain query no string Exact domain match. Known values: vendor, cyber, data, operational, compliance, concentration, strategic, legal, financial, reputational. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
vendor_id query no string Only risks linked to this vendor.
min_inherent_score query no integer Only risks whose inherent score is at least this.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one risk-register entry

GET /v1/risks/{id}

The same object as the collection, for a single entry by id.

Required scope: supply_risk:read

Parameters:

Parameter In Required Type Description
id path yes string Risk identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
  }
}

List control status for a framework

GET /v1/compliance/controls

Requires the framework query parameter (e.g. ens, nis2, iso27001) and that specific framework's compliance.<framework>:read scope.

Required scope: compliance.<framework>:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(control_code, last_evaluated_at) Field to order by. One of: control_code, last_evaluated_at.
order query no enum(asc, desc) Sort direction. Defaults to desc.
framework query yes string Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.
status query no string Exact status match. Known values: covered, partial, missing. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Framework posture summary

GET /v1/compliance/frameworks/{framework}

Percentage of controls covered, with expired evidence, and with none, for the framework named in the path.

Required scope: compliance.<framework>:read

Parameters:

Parameter In Required Type Description
framework path yes string Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

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

List security evidence

GET /v1/evidence

The tenant's evidence items: owner, validity date, status.

Required scope: evidence:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(created_at, valid_until) Field to order by. One of: created_at, valid_until.
order query no enum(asc, desc) Sort direction. Defaults to desc.
evidence_type query no string Exact type match.
source_type query no string Exact producer match.
vendor_id query no string Only evidence about this vendor.
expiring_before query no string Only evidence with a valid_until strictly before this YYYY-MM-DD.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one evidence item

GET /v1/evidence/{id}

The same object as the collection, for a single item by id.

Required scope: evidence:read

Parameters:

Parameter In Required Type Description
id path yes string Evidence identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
  }
}

List enrolled endpoint agents

GET /v1/endpoints

The fleet of endpoints with the agent installed, with their aggregate security posture.

Required scope: endpoints:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(enrolled_at, last_seen_at, producer) Field to order by. One of: enrolled_at, last_seen_at, producer.
order query no enum(asc, desc) Sort direction. Defaults to desc.
status query no enum(active, revoked) Exact status match.
silent_since query no string Agents last seen before this RFC 3339 instant, or never seen at all.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

List the client tenants of an MSSP portfolio

GET /v1/portfolio/tenants

The client tenants the presented portfolio key (hsp_…) may select with the X-HS-Tenant header: the MSSP’s own tenants (its internal one included) and those of its active client organisations, active or not, licensed or not, narrowed to the key’s client subset when it has one. Membership is evaluated on every request. Only a portfolio key can call this operation, which never takes X-HS-Tenant. A tenant is readable when active is true and licence_status is not inactive.

Required scope: portfolio:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(name, slug) Field to order by. One of: name, slug.
order query no enum(asc, desc) Sort direction. Defaults to desc.

Example response (200, fictitious values):

{
  "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
  }
}

Describe the calling credential

GET /v1/me

Who the presented credential is: its type and scopes, and the tenant and organisation it reads (a tenant API key or an OAuth token), or the MSSP organisation it belongs to and how many tenants it can reach (a portfolio key; the tenants themselves are on GET /v1/portfolio/tenants). It describes the caller only: no other tenant, no secret, never the key or its hash. Any valid credential may call it: it requires NO scope, and it uses the same authentication and the same rate limits as every other operation. It never takes X-HS-Tenant.

Required scope: none

Parameters:

No parameters.

Example response (200, fictitious values):

{
  "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
  }
}

List generated reports

GET /v1/reports

The reports generated for the tenant, newest first by default. Metadata only: the report itself is fetched as a file with downloadReport once its status is completed. To pick up new ones, use since with order=asc.

Required scope: reports:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(created_at, period_end) Field to order by. One of: created_at, period_end.
order query no enum(asc, desc) Sort direction. Defaults to desc.
report_type query no string Exact type match. Known values: monthly, vendor_risk, nis2_compliance, ens, cyberbrief, compliance, security_posture, board_report. Open vocabulary: any other value is matched exactly and matches nothing.
status query no string Exact status match. Known values: generating, completed, failed. Open vocabulary: any other value is matched exactly and matches nothing.
since query no string Only reports created at or after this RFC 3339 instant.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one report

GET /v1/reports/{id}

The same object as the collection, for a single report by id, plus the formats it can be downloaded in now (download_formats): empty while it is not completed, or when its content has no renderer (then download it from the console as Markdown or JSON).

Required scope: reports:read

Parameters:

Parameter In Required Type Description
id path yes string Report identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
    ]
  }
}

Download a report file

GET /v1/reports/{id}/download

The report as a file (PDF or XLSX), in the response body with Content-Disposition: attachment; never a link. Each delivery is recorded in the tenant’s audit trail with the credential that received it. It answers 409 with error.details.code: REPORT_NOT_READY when the report is still generating or failed (error.details.status), FORMAT_UNSUPPORTED when its content has no renderer for that format (error.details.formats lists the ones it has) and FILE_TOO_LARGE when the file exceeds the size the operation serves (error.details.limit_bytes, 20 MiB); none of the three sends the file.

Required scope: reports:read

Parameters:

Parameter In Required Type Description
id path yes string Report identifier.
format query no enum(pdf, xlsx) File format, one of: pdf, xlsx. Defaults to pdf. getReport lists the formats a report can be served in (download_formats).
locale query no enum(es, en, de, fr, it, eu) Language of the file, one of: es, en, de, fr, it, eu. Defaults to en.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Response (200, fictitious values): The body is the binary file, not JSON. Example headers:

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

List change requests

GET /v1/changes

The tenant's change-management register: status, type, risk, planned and carried-out dates, the review outcome and how many approval decisions each change holds. Read only; free text and people are not published. Served once at least one compliance framework is activated for the tenant.

Required scope: changes:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(created_at, planned_start_at, implemented_at) Field to order by. One of: created_at, planned_start_at, implemented_at.
order query no enum(asc, desc) Sort direction. Defaults to desc.
status query no enum(draft, submitted, approved, rejected, scheduled, implementing, implemented, failed, rolled_back, in_review, closed, cancelled) Exact status match.
change_type query no enum(normal, emergency) Exact type match.
category query no enum(infrastructure, application, configuration, access, vendor, other) Exact category match.
created_from query no string Only changes created on or after this YYYY-MM-DD (UTC).
created_to query no string Only changes created on or before this YYYY-MM-DD (UTC).
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

List incidents

GET /v1/incidents

The tenant's incident register: type, severity, status, the key dates and, per incident, its regulatory notification deadlines (DORA, NIS2, GDPR, AI Act) in notifications, each with its stage, its status (computed on every read, as the console does), its due date and the date the report that met it was submitted. Read only; free text other than the title, and people, are not published. Served while the tenant has the supply_risk module.

Required scope: incidents:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(detected_at, created_at, updated_at) Field to order by. One of: detected_at, created_at, updated_at.
order query no enum(asc, desc) Sort direction. Defaults to desc.
status query no string Exact status match. Known values: open, investigating, contained, resolved, closed. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
severity query no string Exact severity match. Known values: critical, high, medium, low. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
type query no string Exact type match. Known values: cybersecurity, service_disruption, data_breach, system_failure, third_party, fraud, physical, compliance. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one incident

GET /v1/incidents/{id}

The same object as the collection, for a single incident by id. Another tenant's id answers 404, like one that does not exist.

Required scope: incidents:read

Parameters:

Parameter In Required Type Description
id path yes string Incident identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
  }
}

List AI systems

GET /v1/ai-systems

The tenant's register of AI systems: AI Act risk class, lifecycle status, kind, owning unit, provider and the categories of data each one processes. Read only; free text (purpose, rationale) and people are not published. The register records no AI Act role (provider or deployer) and no review date per system, so neither is published. Served while the tenant has the ai_governance module.

Required scope: ai_systems:read

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(created_at, updated_at, name) Field to order by. One of: created_at, updated_at, name.
order query no enum(asc, desc) Sort direction. Defaults to desc.
risk_class query no string Exact risk class match. Known values: prohibited, high_risk, transparency, minimal. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
lifecycle_status query no string Exact lifecycle status match. Known values: planned, pilot, in_use, retired. Open vocabulary: any other value is matched exactly and matches nothing, and the answer then carries a meta.warnings entry and the X-HS-Unknown-Filter header.
vendor_id query no string Only systems provided by this vendor.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Fetch one AI system

GET /v1/ai-systems/{id}

The same object as the collection, for a single system by id. Another tenant's id answers 404, like one that does not exist.

Required scope: ai_systems:read

Parameters:

Parameter In Required Type Description
id path yes string AI system identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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"
  }
}

Acknowledge an alert

POST /v1/alerts/{id}/acknowledge

Marks an open alert as taken ("someone is on it"). It stays unresolved. Repeating it on an alert that is already acknowledged answers its current state with changed: false and writes nothing; if the alert is already resolved the answer is 409 ALERT_RESOLVED. The key acts with the role of the user who created it, read on every request, and no interactive confirmation is needed. An MSSP portfolio key (hsp_…) names the client tenant with X-HS-Tenant; a tenant outside its client set answers 404 (TENANT_NOT_FOUND). Writes have their own request budget per key (error.details.scope: "write_key"), separate from reads, and are refused while the licence is in its grace period. Every change writes one entry in the tenant’s audit trail with the key id (never the secret), the acting user, the old and new status and the reason. The body is a JSON object; an unknown key is a 400.

Required scope: alerts:write

Parameters:

Parameter In Required Type Description
id path yes string Alert identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Request body: JSON. reason is optional (at most 500 characters). An unknown key is a 400.

Example (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"}'

With a portfolio key hsp_…, add -H "X-HS-Tenant: <tenant id>".

Example response (200, fictitious values):

{
  "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
}

Resolve an alert

POST /v1/alerts/{id}/resolve

Closes an open or acknowledged alert, with the reason why. Repeating it on an alert that is already resolved answers its current state with changed: false and writes nothing (the first reason stays). A critical or high alert is closed only by a key whose creator could close it in the console: an MSSP analyst’s key closes medium and low alerts only (403 ROLE_NOT_PERMITTED). The key acts with the role of the user who created it, read on every request, and no interactive confirmation is needed. An MSSP portfolio key (hsp_…) names the client tenant with X-HS-Tenant; a tenant outside its client set answers 404 (TENANT_NOT_FOUND). Writes have their own request budget per key (error.details.scope: "write_key"), separate from reads, and are refused while the licence is in its grace period. Every change writes one entry in the tenant’s audit trail with the key id (never the secret), the acting user, the old and new status and the reason. A concurrent change between its read and its write answers 409 ALERT_STATE_CHANGED.

Required scope: alerts:write

Parameters:

Parameter In Required Type Description
id path yes string Alert identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Request body: JSON. reason is required (at least two non-blank characters, at most 500).

Example (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"}'

With a portfolio key hsp_…, add -H "X-HS-Tenant: <tenant id>".

Example response (200, fictitious values):

{
  "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
}

Propose an action a person approves in the console

POST /v1/act/proposals

Records a PROPOSAL of one action class. Nothing changes until a person of the tenant approves it in the console, which executes it with the approver's own role; a proposal nobody decides expires after 7 days. Only an OAuth access token issued for the HodeiShield MCP server, carrying act:propose, may call it: every other credential is answered 403 CREDENTIAL_NOT_ALLOWED. The proposer is the token's user and the proposal is bound to the token's grant (application, user and tenant); a request cannot name another. A person in your organisation approves it in the console. The same content proposed again by the same grant answers 200 with the existing proposal.

Required scope: 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)

Parameters:

Parameter In Required Type Description
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

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

Status of a proposal this application made

GET /v1/act/proposals/{id}

The status of a proposal made by THIS grant (the same application, user and tenant). Never the payload and never who decided it. An id this grant did not propose answers 404, exactly as one that does not exist. Only an OAuth access token issued for the HodeiShield MCP server, carrying act:propose, may call it.

Required scope: act:propose

Parameters:

Parameter In Required Type Description
id path yes string Proposal identifier, as createActProposal returned it.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

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

Move a risk along its lifecycle

POST /v1/risks/{id}/transition

Changes the lifecycle status of one risk-register entry, exactly as the console does: only the transitions the lifecycle allows (identified → assessed; assessed → treatment_planned; treatment_planned → treatment_implemented; treatment_implemented → closed; closed → assessed); anything else is a 409 TRANSITION_NOT_ALLOWED that names the current status and where it may go. Asking for the status the entry already has answers its current state with changed: false and writes nothing. The key acts with the role of the user who created it, read on every request: only an administrator role of the tenant may move a risk (403 ROLE_NOT_PERMITTED otherwise), and a creator who was demoted, suspended, deleted or removed from the tenant takes the power away from the key (403 WRITE_ACTOR_UNRESOLVED or ROLE_NOT_PERMITTED). A tenant API key (hsk_…) writes in its own tenant. An MSSP portfolio key (hsp_…) names the client tenant with X-HS-Tenant, exactly as on the reads: a tenant outside its client set is a 404 (TENANT_NOT_FOUND); only an MSSP organisation administrator can grant risks:write on a portfolio key. Writes have their own request budget per key (error.details.scope: "write_key"), separate from reads, and are refused while the licence is in its grace period. Every change writes the register’s history row (from, to, note, the acting user) and one entry in the tenant’s audit trail with the key id (never the secret). An id of another tenant answers the same 404 as one that does not exist. The body is a JSON object; an unknown key is a 400.

Required scope: risks:write

Parameters:

Parameter In Required Type Description
id path yes string Risk identifier.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Request body: JSON. to_status is required; note is optional (at most 2000 characters). An unknown key is a 400.

Example (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"}'

With a portfolio key hsp_…, add -H "X-HS-Tenant: <tenant id>".

Example response (200, fictitious values):

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

Proposals waiting for a decision

GET /v1/act/inbox

The ACT proposals of the tenant that THE CALLER may approve: still waiting for a decision (status proposed, not expired) and admitted by the console’s own approve rules for this person (the role the action class and the tenant’s policy require, the module the class needs, four-eyes, and not a proposal made through the MCP, which the console cannot approve yet). A proposal the caller could not approve is not listed, and pagination.total counts only what is listed. While actions are paused a listed proposal is still refused at approval (ACTIONS_PAUSED), as in the console. Soonest to expire first by default, each with EXACTLY what it would write (payload) and why it was proposed. Approving does not execute it: execution stays a separate step in the console. Like a decision, the inbox needs a sign-in confirmed within the last 15 minutes (403 STEP_UP_REQUIRED otherwise). Only a user access token of the HodeiShield CLI carrying act:decide may call it (an OAuth-only scope, off unless the server enables it): a tenant API key, an MSSP portfolio key, a token issued for the HodeiShield MCP server and any other application are answered 403 CREDENTIAL_NOT_ALLOWED.

Required scope: act:decide

Parameters:

Parameter In Required Type Description
page query no integer 1-based page number. Defaults to 1.
per_page query no integer Items per page, 1..200. Defaults to 50.
sort query no enum(expires_at, created_at) Field to order by. One of: expires_at, created_at.
order query no enum(asc, desc) Sort direction. Defaults to asc (the proposal that expires soonest first).
class query no enum(create_risk_entry, create_task, request_vendor_evidence, schedule_vendor_scan, set_vendor_criticality, open_vendor_review, add_roadmap_item) Only proposals of this action class. One of: create_risk_entry, create_task, request_vendor_evidence, schedule_vendor_scan, set_vendor_criticality, open_vendor_review, add_roadmap_item.
module query no string Only proposals whose action class needs this module (supply_risk, …). A module no class needs matches nothing.
expires_before query no string RFC 3339. Only proposals that stop being decidable before this instant.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Example response (200, fictitious values):

{
  "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
  }
}

Approve a proposal

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

Approves one proposal waiting for a decision. It does NOT execute it, and no /v1 operation does: the approved action is executed in the console before approval_expires_at (15 minutes), as after an approval made there. An approval is consent to execute now, not a standing authorisation. The decision runs through the console’s own service, so its rules are the console’s: the role the action class and the tenant’s policy require, the module the class needs, four-eyes (the user a proposal was made for cannot approve it when it applies), the expiry, a single decision per proposal and the pause switches. Every refusal carries a stable error.details.code and the ACT reason beside it (error.details.reason). The decider is the token’s user, with their role read on every request. A decision needs a sign-in confirmed within the last 15 minutes (403 STEP_UP_REQUIRED otherwise: sign in again, which asks for your second factor or password). At most 30 decisions per minute per person (429, error.details.scope decision_user). Every decision and every refusal writes one entry in the tenant’s audit trail naming the person, the application and the reason; the ACT ledger records the decision too. An id of another tenant answers the same 404 as one that does not exist. Only a user access token of the HodeiShield CLI carrying act:decide may call it (an OAuth-only scope, off unless the server enables it): a tenant API key, an MSSP portfolio key, a token issued for the HodeiShield MCP server and any other application are answered 403 CREDENTIAL_NOT_ALLOWED.

Required scope: act:decide

Parameters:

Parameter In Required Type Description
id path yes string Proposal identifier, as listPendingActProposals returned it.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Request body: JSON. reason is required (1 to 1000 characters). An unknown key is a 400.

Example (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"}'

The access token is that of a HodeiShield CLI user carrying act:decide; an API key is not accepted.

Example response (200, fictitious values):

{
  "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"
  }
}

Reject a proposal

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

Rejects one proposal waiting for a decision, with the reason why; nothing is executed. As in the console, any role that may write may reject, the user a proposal was made for included. The decision runs through the console’s own service, so its rules are the console’s: the role the action class and the tenant’s policy require, the module the class needs, four-eyes, the expiry, a single decision per proposal and the pause switches. Every refusal carries a stable error.details.code and the ACT reason beside it (error.details.reason). The decider is the token’s user, with their role read on every request. A decision needs a sign-in confirmed within the last 15 minutes (403 STEP_UP_REQUIRED otherwise: sign in again, which asks for your second factor or password). At most 30 decisions per minute per person (429, error.details.scope decision_user). Every decision and every refusal writes one entry in the tenant’s audit trail naming the person, the application and the reason; the ACT ledger records the decision too. An id of another tenant answers the same 404 as one that does not exist. Only a user access token of the HodeiShield CLI carrying act:decide may call it (an OAuth-only scope, off unless the server enables it): a tenant API key, an MSSP portfolio key, a token issued for the HodeiShield MCP server and any other application are answered 403 CREDENTIAL_NOT_ALLOWED.

Required scope: act:decide

Parameters:

Parameter In Required Type Description
id path yes string Proposal identifier, as listPendingActProposals returned it.
X-HS-Tenant header no string The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (hsp_…); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.

Request body: JSON. reason is required (1 to 1000 characters). An unknown key is a 400.

Example (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"}'

The access token is that of a HodeiShield CLI user carrying act:decide; an API key is not accepted.

Example response (200, fictitious values):

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