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