{"openapi":"3.1.0","info":{"title":"Hodei-Shield API","version":"2026-11-21","summary":"Third-party risk and compliance posture, for your own systems.","description":"## Versioning\n\n`/v1` is frozen. These changes are **compatible** and will happen inside it\nwithout notice:\n\n- a new operation;\n- a new **optional** query parameter;\n- a new field in a response object;\n- a new value in a field documented as an open vocabulary (`status`,\n  `severity`, `evidence_type`, the keys of `by_status`);\n- a new `error.code`, always with the HTTP status its siblings already use;\n- anything under `error.details`, which is diagnostic and not part of the\n  contract — except `error.details.code` and the keys the error table of\n  the operation names (`missing`, `licence`, `parameter`, `scope`,\n  `limit`, `window_seconds`, `retry_after_seconds`, `status`,\n  `formats`, `limit_bytes`): those are contract.\n  `error.details.code` is an OPEN vocabulary: a value, once published, keeps\n  its meaning and the HTTP status it is sent with; new values may be added.\n\nWrite your client so those do not break it: ignore unknown fields, do not\nswitch exhaustively on a documented-open vocabulary, and treat an unknown\n`error.code` as \"an error of this HTTP status\".\n\nThese changes are **incompatible** and will NOT happen inside `/v1`. They go\nto `/v2`, and `/v1` keeps serving:\n\n- removing or renaming an operation, a parameter or a field;\n- changing the type, the unit or the meaning of a field;\n- making an optional parameter required, or narrowing what one accepts;\n- changing which scope an operation requires;\n- changing the HTTP status an existing `error.code` is sent with.\n\n## Reads and writes\n\nEvery operation that reads is a `GET`. Three kinds of operation change state,\neach a `POST`: the key writes, `POST /v1/alerts/{id}/acknowledge` and\n`POST /v1/alerts/{id}/resolve` under the write scope `alerts:write`, and\n`POST /v1/risks/{id}/transition` under `risks:write`;\n`POST /v1/act/proposals` (`createActProposal`), which only RECORDS a proposal\nthat a person of the tenant approves before anything changes,\nreachable only with a user's OAuth access token issued for the HodeiShield MCP\nserver that carries `act:propose`; and a person's decision on such a proposal,\n`POST /v1/act/proposals/{id}/approve` and `…/reject`, reachable only with a\nuser's OAuth access token of the HodeiShield CLI that carries `act:decide` and\nwhose sign-in was confirmed within the last 15 minutes (**403**\n`STEP_UP_REQUIRED` otherwise; the same window applies to the list of proposals\nwaiting for the caller, `GET /v1/act/inbox`). An approval does not execute the action: it is\nexecuted in the console within the approval window. Any other method on a path that exists\nanswers **405** with `Allow` naming the one method it serves, and on a path that\ndoes not exist answers **404**: neither changes any state. A new write is offered\nonly as a new operation, which is a compatible change.\n\nThe alert writes are authorised by an API key and its scope alone, with no interactive\nconfirmation, because the caller is an automation (a SOAR): a **tenant API key**\nin its own tenant, or an MSSP **portfolio key** in the client tenant it names\nwith `X-HS-Tenant`, exactly as on the reads (a tenant outside its client set\nanswers **404** `TENANT_NOT_FOUND`). The tenant's IP allowlist (`IP_NOT_ALLOWED`;\nfor a portfolio key, that same 404) and the module of the scope (`supply_risk`\nfor `alerts:write` and `risks:write`, else `MODULE_NOT_ENTITLED`) apply to a\nwrite exactly as to a read. An OAuth access token cannot make them. No read\nscope implies a write scope, a write scope implies no read scope, existing\nkeys do not hold one, and only a user whose role may make the same change in the\nconsole can grant it: `alerts:write` a role that may close alerts,\n`risks:write` an administrator role of the tenant (on a portfolio key, an\norganisation administrator of the provider, for both). The key acts with the role of the **user\nwho created it**, read on every request: a creator who was demoted, suspended,\ndeleted or removed from the tenant (for a portfolio key: from the provider, or\nno longer reaching that client) takes the power away from the key (**403**,\n`WRITE_ACTOR_UNRESOLVED` or `ROLE_NOT_PERMITTED`). The console's\nrole-by-severity rule applies: an MSSP analyst's key closes medium and low\nalerts only; and a risk moves only along the lifecycle the console allows\n(**409** `TRANSITION_NOT_ALLOWED` otherwise). A write takes a JSON object body (an unknown key is a **400**), is\nrefused while the licence is in its grace period (**403** `LICENCE_INACTIVE`),\nand is idempotent: repeating a change already made answers the current state with\n`changed: false`, while a concurrent change between its read and its write\nanswers **409** (`ALERT_STATE_CHANGED`). Every change writes one entry in the\ntenant's audit trail with the key id, the acting user, the old and new status and\nthe reason.\n\n## Downloads\n\nAn operation whose success is a FILE (`GET /v1/reports/{id}/download`) answers\n**200** with the bytes, the `Content-Type` of the format asked for and\n`Content-Disposition: attachment; filename=\"…\"`; it never answers a URL to fetch\nthem from. Its errors are the same JSON envelope as everywhere else. A file that\ncannot be served as asked is a **409** with `error.details.code`: the report is\nnot ready yet (`REPORT_NOT_READY`), its content has no renderer for that format\n(`FORMAT_UNSUPPORTED`) or the file exceeds the size the operation serves\n(`FILE_TOO_LARGE`, with `limit_bytes`). Every file delivered is recorded in the\ntenant's audit trail with the credential that received it.\n\n## Authentication\n\nEvery operation takes `Authorization: Bearer <credential>`. Three credentials\nexist:\n\n- a **tenant API key** (`hsk_…`): belongs to ONE tenant and carries an\n  explicit list of scopes; it can read nothing outside that tenant, whatever it\n  asks for. It can hold the write scopes `alerts:write` and `risks:write`;\n- a user's **OAuth access token** (`hs_at_…`): one user, ONE tenant chosen\n  at consent, read scopes only — plus, for a token issued for the HodeiShield\n  MCP server, the OAuth-only `act:propose`, which lets it record proposals\n  (`createActProposal`) and read their status (`getActProposal`); and, for a\n  token of the HodeiShield CLI, the OAuth-only `act:decide`, which lets the\n  person list the proposals waiting for a decision and approve or reject them;\n- an MSSP **portfolio key** (`hsp_…`): held by a managed security service\n  provider, it reads ANY of its client tenants, ONE per request, selected with\n  the request header `X-HS-Tenant: <tenant id>` (a UUID, never a slug).\n  `GET /v1/portfolio/tenants` lists the tenants it may select. Read scopes,\n  plus at most the write scopes `alerts:write` and `risks:write`, with a mandatory expiry. A\n  tenant outside the key's portfolio answers **404**\n  (`error.details.code: \"TENANT_NOT_FOUND\"`), exactly as one that does not\n  exist.\n\nEvery successful (2xx) answer of a data operation carries `X-HS-Tenant` with\nthe id of the tenant whose data the body holds, for every credential; no error\ncarries it. A tenant API key or OAuth token may send `X-HS-Tenant` only with\nits own tenant's id; any other value is a **400**\n(`TENANT_SELECTOR_NOT_SUPPORTED`).\n\nEach operation below declares the scope it requires. A credential that\nauthenticates but lacks the scope is answered **403**\n(`error.details.code: \"INSUFFICIENT_SCOPE\"`), never 404: you are told what you\nare missing, not that the resource does not exist.\n\nA scope is not enough on its own: the module it names (`supply_risk`,\n`compliance.nis2`, `endpoints`, …) must also be active for the tenant read\n— the credential's own, or the one a portfolio key selected — at the time of the\nrequest; a compliance framework (`compliance.<framework>`) must also be\nactivated for the tenant, as in the console. When it is not (the plan changed,\nthe module was turned off, or the framework was never activated) the\nanswer is **403** with `error.details.code: \"MODULE_NOT_ENTITLED\"`,\n`error.details.scopes` naming the scopes concerned and `error.details.modules`\nthe modules the tenant lacks, for every credential; when the module is in the\nplan but a compliance framework is not activated, `error.details.frameworks`\nnames those frameworks (`nis2`, …). A new key does not help; the module has to\nbe active again.\n\n## Errors\n\nEvery error has the same body:\n\n```json\n{ \"error\": { \"code\": \"forbidden\", \"message\": \"…\", \"request_id\": \"…\" } }\n```\n\nBranch on `code`, log `request_id`, show `message` to nobody but yourself.\n`request_id` is also the `X-Request-Id` response header, and it is what\nsupport will ask you for.\n\n## Rate limits\n\nEvery response that got past authentication carries the limit that is closest\nto being exhausted:\n\n- `RateLimit-Limit` — requests allowed in the window;\n- `RateLimit-Remaining` — requests left in the current window;\n- `RateLimit-Reset` — **seconds** until the window renews;\n- `RateLimit-Policy` — `<limit>;w=<window seconds>`.\n\nThree limits apply, each per one-minute window: per API key, per organisation\n(all of its keys together) and per service. The first two come from the licence\nof the organisation the key belongs to: a higher licence tier has more room, and\nan MSSP partner has more than a direct customer of the same tier. Read the\ncurrent limit from `RateLimit-Limit` and `RateLimit-Policy` rather than\nhard-coding it. When one is exhausted the answer is\n**429** with `error.code: \"rate_limited\"`, `Retry-After` (seconds) and\n`error.details.scope` (`key`, `tenant` or `service`) saying which. A\nwrite is not counted in those: it has its own budget per key (`write_key`),\nplus the service ceiling, so reads and writes never spend each other's room. A\nportfolio key is limited per key (`portfolio_key`), per provider across all\nits portfolio keys (`portfolio_org`) and per service; once the selected tenant\nis known to be in its portfolio, the client tenant's own limit (`tenant`) and\nthe provider's share of it (`portfolio_tenant`) apply too. Your\norganisation's usage never counts against another's. Windows are fixed, so a\nclient can burst up to twice the limit across a window boundary: back off on\n`Retry-After` rather than pacing to the second. The limits are part of the\nservice, not of the frozen contract: they may be raised without notice.\n\n## Pagination, filtering and ordering\n\nEvery collection takes `page` and `per_page` (max 200) and answers with a\n`pagination` object carrying `total` and `total_pages`. Every collection\ntakes `sort` (an enum of the fields THAT collection can order by) and\n`order` (`asc`/`desc`, default `desc`). Filters are exact matches unless\nthe parameter says otherwise. A parameter or field with a known vocabulary lists\nit in `x-hs-known-values` (an OpenAPI extension, not a JSON Schema `enum`: the\nserver still accepts what it accepted before; a value outside the list is served as sent and flagged by `meta.warnings` and the `X-HS-Unknown-Filter` header). Values retired from a parameter\nare listed in `x-hs-deprecated-values`, with the date until which the server is\ndocumented to accept them in `x-hs-deprecated-values-sunset`. A 2xx answer to a\nrequest that uses one carries `Deprecation: @<unix seconds>` (RFC 9745, the day it was\nannounced), `Sunset: <HTTP-date>` (RFC 8594) and `Link: <…>; rel=\"deprecation\"`, the\ndeprecation policy; an answer to a request that uses none carries none of them.\n\n## Contract changes\n\nCorrections and additions to the published contract, newest first. They ship\nwith the contract version (`info.version`) named in each entry. Detect a\ncapability by the operation, not by this string: the portfolio contract is\npresent when `GET /v1` lists `listPortfolioTenants`.\n\n- **2026-11-21 — addition: the host binding state of an endpoint.** `listEndpoints`\n  (`GET /v1/endpoints`, scope `endpoints:read`) gains two keys on every endpoint:\n  `host_binding_state` (`unbound` | `bound` | `unavailable` | `mismatch`), whether the\n  enrolment is bound to the machine it was made on, and `host_binding_changed_at` (RFC 3339 or\n  null), the first transition into `mismatch`. `mismatch` means a signed report presented\n  another machine's binding: a possible cloned host, answered by revoking and re-enrolling.\n  The binding itself is never served. A compatible addition: two new keys in a response object.\n\n- **2026-11-19 — addition: incidents, AI systems, risk transitions and decisions.**\n  This version carries both sets of additions listed below under 2026-11-18 and\n  2026-11-17, which were drafted on separate lanes and are published together under\n  this one version: the incident and AI-system register reads, the risk transition,\n  and a person's decisions on ACT proposals. Nothing else changed.\n- **2026-11-18 — addition: move a risk, and decide proposals as a person.**\n  `POST /v1/risks/{id}/transition` (`transitionRisk`) moves a risk-register entry\n  along the lifecycle the console allows, under the new key write scope\n  `risks:write` (a tenant API key, or an MSSP portfolio key naming the client with\n  `X-HS-Tenant`), acting with the live role of the key's creator, who must be an\n  administrator of the tenant; it answers `{ data, changed }` with the entry's\n  state, never its content. `GET /v1/act/inbox` (`listPendingActProposals`) lists\n  the proposals waiting for a decision, and `POST /v1/act/proposals/{id}/approve`\n  (`approveActProposal`) and `POST /v1/act/proposals/{id}/reject`\n  (`rejectActProposal`) decide one, with a required reason, under the console's\n  rules (role per action class, module, four-eyes, expiry, pause). They take only a\n  user access token of the HodeiShield CLI carrying the new OAuth-only scope\n  `act:decide` (every other credential: 403 `CREDENTIAL_NOT_ALLOWED`), and a\n  decision needs a sign-in confirmed within the last 15 minutes. New detail codes:\n  `STEP_UP_REQUIRED`, `OWN_PROPOSAL` (403), `TRANSITION_NOT_ALLOWED`,\n  `PROPOSAL_EXPIRED`, `ALREADY_DECIDED`, `NOT_DECIDABLE` (409); the existing\n  `ROLE_NOT_PERMITTED` and `ACTIONS_PAUSED` are reused with their meaning; new 429\n  `details.scope` value `decision_user`. The 409 description of the key writes now\n  says \"resource\" instead of \"alert\". Nothing existing was removed, renamed or\n  re-statused.\n- **2026-11-17 — addition: incidents and AI systems.** Four read operations.\n  `GET /v1/incidents` (`listIncidents`) and `GET /v1/incidents/{id}`\n  (`getIncident`) return the tenant's incident register: type, severity, status, the\n  key dates and, per incident, `notifications`, its regulatory notification deadlines\n  (DORA, NIS2, GDPR, AI Act) with their stage, live status, due date and the date the\n  report that met each one was submitted. `GET /v1/ai-systems` (`listAiSystems`) and\n  `GET /v1/ai-systems/{id}` (`getAiSystem`) return the tenant's register of AI systems:\n  risk class, lifecycle status, kind, owning unit, provider and data categories (no AI Act\n  role and no review date per system: the register does not record them). Exact\n  filters (`status`, `severity`, `type`; `risk_class`, `lifecycle_status`,\n  `vendor_id`) with `x-hs-known-values`, `sort`, `order`, `page` and `per_page`\n  (at most 200). Two new read scopes, `incidents:read` (served while the tenant has the\n  `supply_risk` module) and `ai_systems:read` (served while it has `ai_governance`);\n  otherwise **403** `MODULE_NOT_ENTITLED` naming that module. No existing key or token\n  holds them: a credential must be created, or a sign-in made, that asks for them. Free\n  text other than the title and the people involved are not published. Nothing existing\n  was removed, renamed or re-statused.\n\n- **2026-11-15 — correction: API access is a plan feature.** API and CLI access\n  belong to the plans from Comply up (Comply, Assure, Scale, Essentials, Automate,\n  Operate, Enterprise) and to the trial; Respond, Free, Supplier and AI Governance\n  have none. A tenant API key (`hsk_…`) or an OAuth access token not issued for\n  the HodeiShield MCP server, whose tenant is on a plan without API access, was\n  served; it is now refused on every request, reads and the alert writes\n  (`acknowledgeAlert`, `resolveAlert`) alike, with status **403**, `error.code`\n  `forbidden`, `error.details.code` `PLAN_WITHOUT_API` and\n  `error.details.deniedReason` `plan_without_api`. A key that already exists is\n  refused the same way, from the first request after its tenant moves to such a\n  plan. A portfolio key is judged on the plan of the client tenant it selects, with\n  the same answer. The plan is the effective one: a running beta counts. Re-authenticating\n  does not change this; the plan can be changed in the console. The owner of each refused\n  key is told once by email. Nothing existing was removed, renamed or re-statused.\n\n- **2026-11-15 — addition: proposals a person approves (`act:propose`).** A write of\n  another kind: `POST /v1/act/proposals` (`createActProposal`) records a proposal of one\n  action class (`create_task`, `schedule_vendor_scan`, `request_vendor_evidence`)\n  that a person of the tenant approves in the console, which executes it with the\n  approver's role; `GET /v1/act/proposals/{id}` (`getActProposal`) reports its\n  status to the grant that made it, never its payload or approver. Both are reachable\n  only with a user's OAuth access token issued for the HodeiShield MCP server that\n  carries the new OAuth-only scope `act:propose` (never a tenant or portfolio key:\n  403 `CREDENTIAL_NOT_ALLOWED`). New detail codes: `CREDENTIAL_NOT_ALLOWED` (403),\n  `BODY_NOT_JSON`, `BODY_TOO_LARGE`, `VALIDATION_FAILED` (400), `DUPLICATE`,\n  `OPEN_PROPOSAL_CAP`, `ACTIONS_PAUSED` (409); two new 429 `details.scope` values,\n  `proposal_grant` (10 proposals per minute per grant) and `proposal_user` (10 per\n  minute per user across all their applications). Every other path still\n  answers 405 to a write. Also in this version: a 2xx answer to a request that uses a\n  deprecated parameter value now carries the response headers `Deprecation` (RFC 9745),\n  `Sunset` (RFC 8594) and `Link` with `rel=\"deprecation\"`; today only the Spanish\n  `severity` values of `GET /v1/alerts` (announced 2026-10-16, sunset 2027-01-14), which\n  are still accepted. A request that uses none gets none. Nothing existing was removed,\n  renamed or re-statused.\n\n- **2026-11-15 — addition: `credential.expires_at` on `GET /v1/me`.** The\n  credential block gains `expires_at`, an RFC 3339 UTC instant or null: when a tenant\n  API key stops working, so an integration can warn before the key does. It is null for a\n  key with no expiry, for an OAuth access token (renewed by its refresh token) and, for\n  now, for a portfolio key (not reported). The key itself answers 401 from that instant.\n  A compatible addition: a new key in a response object. Nothing existing was removed, renamed or re-statused.\n\n- **2026-11-15 — correction: an unknown query parameter name is refused.** A query\n  parameter whose NAME the operation does not declare (`GET /v1/alerts?stauts=open`)\n  was ignored and the request was served unfiltered, so a connector with a typo\n  ingested the whole table believing it had filtered. It is now refused with status\n  **400**, `error.code` `invalid_request` and `error.details.code`\n  `UNKNOWN_QUERY_PARAMETER`; `error.details.unknown` lists the names that are not\n  declared (at most 10, each cut to 64 characters; `error.details.unknown_omitted`\n  counts the rest) and `error.details.allowed` the names the operation accepts. An operation\n  without query parameters accepts none. A misspelt VALUE is unchanged (served as sent\n  and flagged). Nothing was removed, renamed or re-statused: a request that only\n  uses the declared names is unaffected.\n\n- **2026-11-15 — correction: a key dies with its creator's role, and keys\n  expire.** A tenant API key (`hsk_…`) and a portfolio key (`hsp_…`) kept\n  working after the administrator who created it was removed, deactivated or\n  demoted. Such a key is now refused with status **401**, the answer a revoked or\n  expired key already got, unless another administrator of the tenant took the\n  tenant API key over before the change. Every tenant API key now has an expiry of\n  at most 365 days (`never` is no longer offered; a key that had none was given\n  one and its creator was told), and a portfolio key lives at most 90 days. The\n  descriptions of both security schemes say so. Re-authenticating does not help:\n  an administrator of the tenant creates a new key. Nothing existing was removed,\n  renamed or re-statused.\n- **2026-11-14 — addition: acknowledge and resolve an alert (the first writes).**\n  `POST /v1/alerts/{id}/acknowledge` (`acknowledgeAlert`) and\n  `POST /v1/alerts/{id}/resolve` (`resolveAlert`, a `reason` is required),\n  under the new write scope `alerts:write`, for a tenant API key or an MSSP\n  portfolio key (the client named with `X-HS-Tenant`). Both answer\n  `{ data, changed }`: the alert's state after the request (`status`, the\n  timestamps, `resolution_reason`; never its content) and whether this request\n  changed it. New `error.details.code` values: `ROLE_NOT_PERMITTED` and\n  `WRITE_ACTOR_UNRESOLVED` (403), `ALERT_RESOLVED` and\n  `ALERT_STATE_CHANGED` (409); new 429 `error.details.scope` value\n  `write_key`. See \"Reads and writes\". Nothing existing changed: every read\n  operation is still a `GET` and needs no new scope.\n- **2026-11-14 — addition: MITRE ATT&CK techniques on alerts.**\n  `GET /v1/alerts` and `GET /v1/alerts/{id}` gain two keys on the alert\n  object. `mitre_techniques` lists the techniques the CTID KEV mappings assign\n  to the alert's CVE (`id`, `name`, `tactic_id`, `tactic_name`,\n  `subtechnique_id`; one entry per technique and tactic). `mitre_mapping`\n  says why the list holds what it holds: `status` is `mapped`, `unmapped`\n  (an empty list and the note «sin mapeo»: a CVE outside the CISA KEV set, or an\n  alert that is not a CVE), `not_in_plan` or `unavailable`, and `source`\n  names the mapping dataset, its version, the ATT&CK release and the upstream\n  commit. The mapping is a feature of the tenant's plan\n  (`supply_chain.mitre_mapping`): without it `mitre_techniques` is `null` and\n  `status` is `not_in_plan`, and the alert is otherwise served in full (no 403).\n  Treat `null` as \"not served\", never as \"no mapping\". Nothing existing was\n  removed, renamed or re-statused.\n\n- **2026-11-12 — correction: the tenant's IP allowlist applies to API keys.** A\n  tenant that configured an IP allowlist in the console had it enforced on console\n  sessions and OAuth access tokens, but a tenant API key (`hsk_…`) was served from\n  any address. A key is now refused from an address outside its tenant's\n  allowlist with status **403**, `error.code` `forbidden` and\n  `error.details.code` `IP_NOT_ALLOWED`, the answer an OAuth access token already\n  got for the same reason. A portfolio key acting in a client tenant that has an\n  allowlist is refused from an address outside it with the same **404**\n  `TENANT_NOT_FOUND` as a tenant outside its portfolio, so the allowlist reveals\n  nothing about which tenants belong to the portfolio. The address is the one the\n  client connects from. A tenant without an allowlist is unaffected.\n  Re-authenticating does not help: the tenant's administrator adds the address to\n  the allowlist. Nothing existing was removed, renamed or re-statused.\n\n- **2026-11-12 — correction: the portfolio listing and `/v1/me` respect each client's IP\n  allowlist.** `GET /v1/portfolio/tenants` listed every client of the portfolio, and\n  `GET /v1/me` counted them, from any address. A client tenant that has an IP allowlist\n  excluding the address of the request is now left out of the listing and out of the count,\n  with no sign that it exists; a client without an allowlist is unaffected. If a client's allowlist cannot be read, both answer **503** `service_unavailable` instead of a shorter list. Nothing existing\n  was removed, renamed or re-statused.\n\n- **2026-11-12 — correction: `MFA_ENROLLMENT_REQUIRED` is published.** An OAuth\n  access token (the CLI, an MCP client) of an account without a second factor,\n  used against a tenant that requires one, has always been refused with status\n  **403**, `error.code` `forbidden` and `error.details.code`\n  `MFA_ENROLLMENT_REQUIRED`, but the contract did not list that code among the\n  detail codes every operation shares. It is listed now. Re-authenticating does\n  not help: the account enrols a second factor in the console. Nothing existing\n  was removed, renamed or re-statused.\n\n- **2026-10-29 — addition: a warning when a filter value is not a published one.**\n  `GET /v1/alerts` `severity`, `GET /v1/risks` `domain` and `status` and\n  `GET /v1/compliance/controls` `status` match exactly, so a mistyped value\n  (`severity=critcal`) used to return an empty list that looked like \"no results\".\n  The request is still served as sent, with status **200** and the same items: no\n  parameter is narrowed. When the value is outside the parameter's\n  `x-hs-known-values`, the answer now also carries the optional body key\n  `meta.warnings[]` (`param`, `value`, `known`) and the response header\n  `X-HS-Unknown-Filter`, which names the parameter(s). Both are absent when\n  every filter value is a published one, and the retired Spanish `severity`\n  values inside their notice window raise no warning. `GET /v1/vendors`\n  `category` is free text with no vocabulary and is not checked. Nothing\n  existing was removed, renamed or re-statused.\n\n- **2026-10-27 — correction: a scope needs its module active.** A tenant API key\n  or a portfolio key was served on its scope alone, even when the tenant read no\n  longer had that scope's module active; an OAuth access token already was not.\n  Every credential now gets **403** with `error.details.code`\n  `MODULE_NOT_ENTITLED`, `error.details.scopes` and `error.details.modules`\n  (the module ids the tenant lacks) in that case (a new `error.details.code`\n  value), plus `error.details.frameworks` when a compliance framework is\n  entitled but not activated. A `compliance.<framework>` scope also needs\n  the framework ACTIVATED for the tenant, not only included in its plan; an OAuth\n  token no longer carries a compliance scope whose framework is not activated. **This changes what such a request receives:**\n  it was a 200. `GET /v1/me` needs no scope and is unaffected. The same version\n  adds the operation `listChanges` (`GET /v1/changes`, scope `changes:read`,\n  read-only), the change-management register, served once at least one compliance\n  framework is ACTIVATED for the tenant. Nothing else was removed, renamed or\n  re-statused.\n\n- **2026-10-26 — change: `user.email` on `GET /v1/me` needs the `email` scope.**\n  The OAuth scope `email` is new. `user.email` is returned only to an access\n  token that carries it, and is omitted otherwise: `user` still names the\n  signed-in user by `id` and `name`. A client that shows the email asks for\n  `email` at authorization; the consent screen lists it. The call is never refused\n  for a missing `email` scope. A client that decoded `user.email` as required\n  must treat it as optional.\n\n- **2026-10-24 — correction: `beta` on `GET /v1/me` is the tenant's own.** For\n  a client tenant of an MSSP whose own organisation is not in a running beta, `beta`\n  is `active`, `running: true` and `ends_at: null` while the MSSP's beta runs\n  (it is what lifts the client's access), and `null` otherwise: the MSSP's end date\n  and whether its beta ended or converted are not the client's to read. The tenant's\n  own organisation's beta is described as before. No field was added or removed.\n\n- **2026-10-21 — addition: `user` on `GET /v1/me`.** The `whoAmI` answer gains\n  a nullable `user` object (`id`, `name`, `email`): the signed-in user of an\n  OAuth access token (`hs_at_…`), so a client can show who is logged in. It is the\n  caller's own data only, never another user's. It is `null` for a tenant API key\n  and for a portfolio key. Nothing existing was removed, renamed or re-statused.\n\n- **2026-10-20 — addition: `beta` on `GET /v1/me`.** The `whoAmI` answer gains\n  a nullable `beta` object (`status`, `running`, `ends_at`): the beta of the\n  tenant's own organisation, so a client can show when it ends. It is `null` for an\n  organisation that never joined the beta and for a portfolio key; a beta inherited\n  from a parent MSSP is not described. Nothing existing was removed, renamed or\n  re-statused.\n\n- **2026-10-19 — addition: reports.** `GET /v1/reports` (`listReports`),\n  `GET /v1/reports/{id}` (`getReport`) and\n  `GET /v1/reports/{id}/download` (`downloadReport`), all under the scope\n  `reports:read`. The download is the contract's first non-JSON success: a\n  PDF or XLSX file as an attachment (see Downloads). A new `error.code`,\n  `conflict` (**409**), answered only by the download, with three new\n  `error.details.code` values (`REPORT_NOT_READY`, `FORMAT_UNSUPPORTED`,\n  `FILE_TOO_LARGE`). Nothing existing was removed, renamed or re-statused.\n\n- **2026-10-18 — addition: known values for four filters.** `GET /v1/risks`\n  `domain` and `status`, `GET /v1/compliance/controls` `status` and the\n  `vendor_type` field of `GET /v1/vendors` now list their vocabulary in\n  `x-hs-known-values`, taken from the lists the platform validates against.\n  They stay open: a value outside the list is still accepted and matches exactly,\n  as before. `GET /v1/vendors` `category` is free text with no closed\n  vocabulary, and its description now says so. Nothing existing was removed,\n  renamed or re-statused.\n\n- **2026-10-17 — addition: `GET /v1/me`.** The operation `whoAmI` describes the\n  calling credential: its type and scopes, the tenant (id, name) and organisation it\n  reads, or, for a portfolio key, the MSSP organisation and how many tenants it can\n  reach. Any valid credential may call it and it requires no scope; it uses the same\n  authentication and rate limits as every other operation, and refuses\n  `X-HS-Tenant`. Nothing existing was removed, renamed or re-statused.\n\n- **2026-10-16 — addition: MSSP portfolio keys.** A third credential, the\n  portfolio key (`hsp_…`); the operation `GET /v1/portfolio/tenants`\n  (`listPortfolioTenants`, scope `portfolio:read`); the optional request\n  header `X-HS-Tenant` on every data operation, echoed on every 2xx answer of\n  them for every credential, with `Vary: X-HS-Tenant`;\n  `error.details.code` becomes contract (`TENANT_HEADER_INVALID`,\n  `TENANT_REQUIRED`, `TENANT_SELECTOR_NOT_SUPPORTED`, `TENANT_NOT_FOUND`,\n  `INSUFFICIENT_SCOPE`, `LICENCE_INACTIVE`), and every scope 403 now carries\n  `INSUFFICIENT_SCOPE`; three new 429 `details.scope` values\n  (`portfolio_key`, `portfolio_org`, `portfolio_tenant`). Nothing existing\n  was removed, renamed or re-statused.\n\n- **2026-10-16 — correction: alert `severity` is English.** `GET /v1/alerts`\n  and `GET /v1/alerts/{id}` returned `severity` as stored, in Spanish\n  (`critico`, `alto`, `medio`, `bajo`, `info`), while this document\n  promised `critical | high | medium | low`. They now return `critical`,\n  `high`, `medium`, `low` and `info` (`info` is added to the documented\n  values). **This changes what an integrator who adapted to the Spanish values\n  receives.** The `severity` filter accepts both the English values and the\n  Spanish ones; the Spanish ones are documented as accepted until\n  **2027-01-14** (90 days after this version), so switch to the English ones\n  before then. A value outside both lists is still matched exactly and matches\n  nothing. `GET /v1/risks`: the descriptions of `domain` and `status` named\n  values that do not exist; they now list the real ones (no value changed).","contact":{"name":"Hodeitek S.L.","url":"https://hodeishield.com"}},"servers":[{"url":"https://api.hodeishield.com"}],"tags":[{"name":"vendors"},{"name":"alerts"},{"name":"risks"},{"name":"compliance"},{"name":"evidence"},{"name":"endpoints"},{"name":"Portfolio"},{"name":"Identity"},{"name":"reports"},{"name":"changes"},{"name":"incidents"},{"name":"ai-systems"},{"name":"proposals"}],"paths":{"/v1/vendors":{"get":{"operationId":"listVendors","summary":"List third parties","description":"The tenant third-party inventory, newest first by default. Soft-deleted vendors are never returned.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, name.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","name"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring of the name or the domain.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"category","in":"query","required":false,"description":"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`).","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"active","in":"query","required":false,"description":"Filter by the operational flag.","schema":{"type":"string"}},{"name":"business_criticality","in":"query","required":false,"description":"Exact criticality match.","schema":{"type":"string","enum":["low","medium","high","critical"]}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant. NOT a closed vocabulary: the console form stores the label of the tenant’s language, and the API accepts any text. List the vendors to see the values a tenant uses.","type":["string","null"]},"vendor_type":{"description":"Kind of third party: software | cloud | hardware | service_provider. Open vocabulary: a new kind is a compatible change.","x-hs-known-values":["software","cloud","hardware","service_provider"],"type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/vendors/{id}":{"get":{"operationId":"getVendor","summary":"Fetch one third party","description":"The same object `listVendors` returns, for a single vendor.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant. NOT a closed vocabulary: the console form stores the label of the tenant’s language, and the API accepts any text. List the vendors to see the values a tenant uses.","type":["string","null"]},"vendor_type":{"description":"Kind of third party: software | cloud | hardware | service_provider. Open vocabulary: a new kind is a compatible change.","x-hs-known-values":["software","cloud","hardware","service_provider"],"type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts":{"get":{"operationId":"listAlerts","summary":"List supply-chain alerts","description":"Alerts raised against the tenant vendors. Poll new alerts with `since` plus `order=asc`, changed ones with `updated_since` plus `sort=updated_at&order=asc`.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1. Cannot be combined with `cursor`.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque keyset cursor: pass the `next_cursor` of the previous page, with the same `sort`, `order` and filters. Cannot be combined with `page`.","schema":{"type":"string","minLength":1,"maxLength":512}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Filter by the derived status.","schema":{"type":"string","enum":["open","acknowledged","resolved"]}},{"name":"severity","in":"query","required":false,"description":"Exact severity match, in the vocabulary the response uses (critical | high | medium | low | info). The legacy Spanish values (critico, alto, medio, bajo, info) are still accepted and mean the same; they are documented as accepted until 2027-01-14, so move to the English ones; a request that uses one also gets the `Deprecation`, `Sunset` and `Link` (`rel=\"deprecation\"`) response headers. 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.","schema":{"x-hs-known-values":["critical","high","medium","low","info"],"x-hs-deprecated-values":["critico","alto","medio","bajo"],"x-hs-deprecated-values-sunset":"2027-01-14","type":"string","minLength":1,"maxLength":40}},{"name":"vendor_id","in":"query","required":false,"description":"Only alerts about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"since","in":"query","required":false,"description":"Only alerts created at or after this RFC 3339 instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"updated_since","in":"query","required":false,"description":"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`.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}},"X-HS-Unknown-Filter":{"description":"Present only when a filter value is outside the parameter’s published `x-hs-known-values`: the name(s) of the parameter(s), comma-separated (for example `severity, status`). The request was served as sent, so the list is usually empty; the same entries are in `meta.warnings`. Absent when every filter value is a published one.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. Present only when the request used a deprecated value: `severity` (`critico`, `alto`, `medio`, `bajo`). `@` and the Unix time, in seconds, of the day the deprecation was announced (for example `@1792108800`). Absent otherwise.","schema":{"type":"string","pattern":"^@[0-9]+$"}},"Sunset":{"description":"RFC 8594. Present with `Deprecation`: the HTTP-date after which the deprecated value is no longer documented as accepted (for example `Thu, 14 Jan 2027 00:00:00 GMT`). The server keeps accepting it until a later contract version announces its removal.","schema":{"type":"string"}},"Link":{"description":"Present with `Deprecation`: `<https://docs.hodeishield.com/api/deprecation-policy/>; rel=\"deprecation\"`, the deprecation policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.","x-hs-known-values":["critical","high","medium","low","info"],"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC. Last change of severity, acknowledgement, resolution or CISA KEV status; equals the instant the service started tracking it for alerts older than that."},"mitre_techniques":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ATT&CK technique id, e.g. `T1059`; the parent of a sub-technique."},"name":{"type":"string"},"tactic_id":{"type":"string","description":"e.g. `TA0002`."},"tactic_name":{"type":"string"},"subtechnique_id":{"description":"e.g. `T1059.001` when the technique is a sub-technique, otherwise null.","type":["string","null"]}},"required":["id","name","tactic_id","tactic_name","subtechnique_id"],"additionalProperties":false}},{"type":"null"}],"description":"MITRE ATT&CK techniques mapped to the alert CVE (CTID KEV mappings; one entry per technique and tactic). Empty array: the alert has no mapping (`mitre_mapping.status` is `unmapped`, «sin mapeo»). null: the mapping is not served (`not_in_plan` or `unavailable`)."},"mitre_mapping":{"type":"object","properties":{"status":{"type":"string","enum":["mapped","unmapped","not_in_plan","unavailable"],"description":"`mapped`: techniques found. `unmapped`: no mapping (a non-CVE alert, or a CVE outside the CISA KEV set). `not_in_plan`: the tenant plan does not include `supply_chain.mitre_mapping`. `unavailable`: the reference data is not loaded in this environment."},"note":{"description":"Human-readable reason; «sin mapeo» when `unmapped`.","type":["string","null"]},"source":{"anyOf":[{"type":"object","properties":{"framework":{"type":"string","description":"CTID Mappings Explorer dataset, e.g. `kev`."},"framework_version":{"type":"string"},"attack_version":{"type":"string","description":"MITRE ATT&CK release the techniques come from."},"upstream_commit":{"type":"string","description":"Commit of the CTID mappings that were imported."}},"required":["framework","framework_version","attack_version","upstream_commit"],"additionalProperties":false},{"type":"null"}],"description":"Source and version of the mapping; null unless the mapping was served."}},"required":["status","note","source"],"additionalProperties":false,"description":"Why `mitre_techniques` holds what it holds, and where the mapping comes from."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at","updated_at","mitre_techniques","mitre_mapping"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."},"next_cursor":{"description":"Pass as `cursor` for the next page; null on the last page.","type":["string","null"]}},"required":["per_page","next_cursor"],"additionalProperties":false},"meta":{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","description":"The query parameter whose value is not in the published list."},"value":{"type":"string","description":"The value as sent."},"known":{"type":"array","items":{"type":"string"},"description":"The published values of the parameter (its `x-hs-known-values`)."}},"required":["param","value","known"],"additionalProperties":false,"description":"A filter value outside the published vocabulary. The request was served as sent."},"description":"One entry per filter whose value is not a published value. The list is still filtered by the value as sent (so it is usually empty); the same parameters are named in the `X-HS-Unknown-Filter` response header."}},"required":["warnings"],"additionalProperties":false,"description":"Present only when at least one filter value is outside its published list; omitted otherwise."}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts/{id}":{"get":{"operationId":"getAlert","summary":"Fetch one alert","description":"The same object `listAlerts` returns, for a single alert.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.","x-hs-known-values":["critical","high","medium","low","info"],"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC. Last change of severity, acknowledgement, resolution or CISA KEV status; equals the instant the service started tracking it for alerts older than that."},"mitre_techniques":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ATT&CK technique id, e.g. `T1059`; the parent of a sub-technique."},"name":{"type":"string"},"tactic_id":{"type":"string","description":"e.g. `TA0002`."},"tactic_name":{"type":"string"},"subtechnique_id":{"description":"e.g. `T1059.001` when the technique is a sub-technique, otherwise null.","type":["string","null"]}},"required":["id","name","tactic_id","tactic_name","subtechnique_id"],"additionalProperties":false}},{"type":"null"}],"description":"MITRE ATT&CK techniques mapped to the alert CVE (CTID KEV mappings; one entry per technique and tactic). Empty array: the alert has no mapping (`mitre_mapping.status` is `unmapped`, «sin mapeo»). null: the mapping is not served (`not_in_plan` or `unavailable`)."},"mitre_mapping":{"type":"object","properties":{"status":{"type":"string","enum":["mapped","unmapped","not_in_plan","unavailable"],"description":"`mapped`: techniques found. `unmapped`: no mapping (a non-CVE alert, or a CVE outside the CISA KEV set). `not_in_plan`: the tenant plan does not include `supply_chain.mitre_mapping`. `unavailable`: the reference data is not loaded in this environment."},"note":{"description":"Human-readable reason; «sin mapeo» when `unmapped`.","type":["string","null"]},"source":{"anyOf":[{"type":"object","properties":{"framework":{"type":"string","description":"CTID Mappings Explorer dataset, e.g. `kev`."},"framework_version":{"type":"string"},"attack_version":{"type":"string","description":"MITRE ATT&CK release the techniques come from."},"upstream_commit":{"type":"string","description":"Commit of the CTID mappings that were imported."}},"required":["framework","framework_version","attack_version","upstream_commit"],"additionalProperties":false},{"type":"null"}],"description":"Source and version of the mapping; null unless the mapping was served."}},"required":["status","note","source"],"additionalProperties":false,"description":"Why `mitre_techniques` holds what it holds, and where the mapping comes from."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at","updated_at","mitre_techniques","mitre_mapping"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks":{"get":{"operationId":"listRisks","summary":"List risk-register entries","description":"The tenant risk register, with inherent and residual figures.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, inherent_score, residual_score.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","inherent_score","residual_score"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["identified","assessed","treatment_planned","treatment_implemented","closed"],"type":"string","minLength":1,"maxLength":24}},{"name":"domain","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["vendor","cyber","data","operational","compliance","concentration","strategic","legal","financial","reputational"],"type":"string","minLength":1,"maxLength":20}},{"name":"vendor_id","in":"query","required":false,"description":"Only risks linked to this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"min_inherent_score","in":"query","required":false,"description":"Only risks whose inherent score is at least this.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}},"X-HS-Unknown-Filter":{"description":"Present only when a filter value is outside the parameter’s published `x-hs-known-values`: the name(s) of the parameter(s), comma-separated (for example `severity, status`). The request was served as sent, so the list is usually empty; the same entries are in `meta.warnings`. Absent when every filter value is a published one.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational.","x-hs-known-values":["vendor","cyber","data","operational","compliance","concentration","strategic","legal","financial","reputational"]},"status":{"type":"string","description":"Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed.","x-hs-known-values":["identified","assessed","treatment_planned","treatment_implemented","closed"]},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false},"meta":{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","description":"The query parameter whose value is not in the published list."},"value":{"type":"string","description":"The value as sent."},"known":{"type":"array","items":{"type":"string"},"description":"The published values of the parameter (its `x-hs-known-values`)."}},"required":["param","value","known"],"additionalProperties":false,"description":"A filter value outside the published vocabulary. The request was served as sent."},"description":"One entry per filter whose value is not a published value. The list is still filtered by the value as sent (so it is usually empty); the same parameters are named in the `X-HS-Unknown-Filter` response header."}},"required":["warnings"],"additionalProperties":false,"description":"Present only when at least one filter value is outside its published list; omitted otherwise."}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks/{id}":{"get":{"operationId":"getRisk","summary":"Fetch one risk-register entry","description":"The same object `listRisks` returns, for a single entry.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Risk identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational.","x-hs-known-values":["vendor","cyber","data","operational","compliance","concentration","strategic","legal","financial","reputational"]},"status":{"type":"string","description":"Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed.","x-hs-known-values":["identified","assessed","treatment_planned","treatment_implemented","closed"]},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/compliance/controls":{"get":{"operationId":"listComplianceControls","summary":"List control status for a framework","description":"Per-control status of one framework. Requires the read scope OF THAT FRAMEWORK: `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: control_code, last_evaluated_at.","schema":{"default":"control_code","type":"string","enum":["control_code","last_evaluated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"framework","in":"query","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["covered","partial","missing"],"type":"string","minLength":1,"maxLength":20}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}},"X-HS-Unknown-Filter":{"description":"Present only when a filter value is outside the parameter’s published `x-hs-known-values`: the name(s) of the parameter(s), comma-separated (for example `severity, status`). The request was served as sent, so the list is usually empty; the same entries are in `meta.warnings`. Absent when every filter value is a published one.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework slug the control belongs to."},"control_code":{"type":"string","description":"Control identifier inside the framework."},"status":{"type":"string","description":"covered | partial | missing, as evaluated by the platform.","x-hs-known-values":["covered","partial","missing"]},"evidence_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Evidence items currently linked to the control."},"last_evaluated_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["framework","control_code","status","evidence_count","last_evaluated_at"],"additionalProperties":false,"description":"The tenant status of one framework control."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false},"meta":{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","description":"The query parameter whose value is not in the published list."},"value":{"type":"string","description":"The value as sent."},"known":{"type":"array","items":{"type":"string"},"description":"The published values of the parameter (its `x-hs-known-values`)."}},"required":["param","value","known"],"additionalProperties":false,"description":"A filter value outside the published vocabulary. The request was served as sent."},"description":"One entry per filter whose value is not a published value. The list is still filtered by the value as sent (so it is usually empty); the same parameters are named in the `X-HS-Unknown-Filter` response header."}},"required":["warnings"],"additionalProperties":false,"description":"Present only when at least one filter value is outside its published list; omitted otherwise."}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/compliance/frameworks/{framework}":{"get":{"operationId":"getFrameworkPosture","summary":"Framework posture summary","description":"Counts of evaluated controls by status for one framework, for a dashboard tile. Requires `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"framework":{"type":"string"},"controls_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Controls the platform has evaluated."},"by_status":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Control count per status. Keys are whatever statuses exist; may grow."},"evidence_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of the evidence linked across the evaluated controls."},"last_evaluated_at":{"description":"Most recent control evaluation, RFC 3339 UTC. Null if never evaluated.","type":["string","null"]}},"required":["framework","controls_total","by_status","evidence_total","last_evaluated_at"],"additionalProperties":false,"description":"Posture summary for one framework."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/evidence":{"get":{"operationId":"listEvidence","summary":"List security evidence","description":"Evidence held for the tenant. Use `expiring_before` plus `sort=valid_until&order=asc` for a renewal queue.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, valid_until.","schema":{"default":"created_at","type":"string","enum":["created_at","valid_until"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"evidence_type","in":"query","required":false,"description":"Exact type match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"source_type","in":"query","required":false,"description":"Exact producer match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"vendor_id","in":"query","required":false,"description":"Only evidence about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"expiring_before","in":"query","required":false,"description":"Only evidence with a `valid_until` strictly before this `YYYY-MM-DD`.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Fetch one evidence item","description":"The same object `listEvidence` returns, for a single item.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"id","in":"path","required":true,"description":"Evidence identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/endpoints":{"get":{"operationId":"listEndpoints","summary":"List enrolled endpoint agents","description":"The endpoint agents enrolled in this tenant. `silent_since` selects the ones that have gone quiet, including those that never reported.\n\nRequired scope: `endpoints:read`. Published in `/v1` since 2026-09-20.","tags":["endpoints"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: enrolled_at, last_seen_at, producer.","schema":{"default":"enrolled_at","type":"string","enum":["enrolled_at","last_seen_at","producer"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","enum":["active","revoked"]}},{"name":"silent_since","in":"query","required":false,"description":"Agents last seen before this RFC 3339 instant, or never seen at all.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"producer":{"type":"string","description":"The agent name, unique among the active ones of the tenant."},"producer_kind":{"type":"string","description":"What kind of producer it is."},"status":{"type":"string","description":"active | revoked."},"signature_alg":{"type":"string","description":"Algorithm this enrollment signs with."},"agent_version":{"type":["string","null"]},"hostname":{"description":"Last hostname the agent reported.","type":["string","null"]},"enrolled_at":{"type":"string","description":"RFC 3339, UTC."},"last_seen_at":{"description":"RFC 3339, UTC. Null until the first envelope.","type":["string","null"]},"revoked_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"host_binding_state":{"type":"string","enum":["unbound","bound","unavailable","mismatch"],"description":"Whether this enrolment is bound to the machine it was made on. unbound: enrolled by an agent that does not bind, or reinstated. bound / unavailable: bound, or the machine has no usable identifier. mismatch: a signed report presented another machine’s binding, a possible cloned host; revoke and re-enrol."},"host_binding_changed_at":{"description":"RFC 3339, UTC. The first transition into mismatch; null otherwise.","type":["string","null"]}},"required":["id","producer","producer_kind","status","signature_alg","agent_version","hostname","enrolled_at","last_seen_at","revoked_at","host_binding_state","host_binding_changed_at"],"additionalProperties":false,"description":"An endpoint agent enrolled in this tenant."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["endpoints:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["endpoints:read"]}}},"/v1/portfolio/tenants":{"get":{"operationId":"listPortfolioTenants","summary":"List the client tenants of an MSSP portfolio","description":"Every tenant the presented PORTFOLIO key may select with `X-HS-Tenant`: the MSSP’s own tenants (its internal one included) and every tenant of its active client organisations, active or not, licensed or not, narrowed to the key’s client subset when it has one, and to the tenants whose IP allowlist admits the address of this request (a tenant with an allowlist that excludes it is not listed and is not counted; if a client’s allowlist cannot be read the answer is 503, not a shorter list). Membership is evaluated live on every request. Only a portfolio key (`hsp_…`) can call this operation; this operation never takes `X-HS-Tenant`.\n\nRequired scope: `portfolio:read`. Published in `/v1` since 2026-10-16.","tags":["Portfolio"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: name, slug.","schema":{"default":"name","type":"string","enum":["name","slug"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier (lowercase). The ONLY value `X-HS-Tenant` accepts."},"name":{"type":"string","description":"Display name. Untrusted text."},"slug":{"type":"string","description":"Short name, unique across the platform. A client may resolve a slug to an `id` from this list; the server never accepts a slug as a selector."},"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"description":"The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation."},"internal":{"type":"boolean","description":"True only for the MSSP’s own internal tenant."},"active":{"type":"boolean","description":"Whether the tenant is enabled. A deactivated tenant is listed but cannot be read."},"licence_status":{"type":"string","description":"Open vocabulary: `in_force` (licence in force), `grace` (grace period: reads are served), `inactive` (none, suspended, revoked or expired: data operations answer 403 `LICENCE_INACTIVE`). Treat an unknown value as \"may not be readable\". A tenant is readable when `active` is true and `licence_status` is not `inactive`.","x-hs-known-values":["in_force","grace","inactive"]}},"required":["id","name","slug","organization","internal","active","licence_status"],"additionalProperties":false,"description":"A client tenant an MSSP portfolio key may select."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"portfolioKey":[]}],"x-hs-scope":{"scopes":["portfolio:read"]}}},"/v1/me":{"get":{"operationId":"whoAmI","summary":"Describe the calling credential","description":"Who the presented credential is: its type and scopes, and the tenant and organisation it reads (a tenant API key or an OAuth token), for an OAuth token also the signed-in user (`user`: its own id and name, and its email only when the token carries the `email` scope; never another user’s; null for any key), or the MSSP organisation it belongs to and how many tenants it can reach from this address (a portfolio key; tenants whose IP allowlist excludes the address are not counted; 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`.\n\nRequired scope: `none (any valid credential)`. Published in `/v1` since 2026-10-17.","tags":["Identity"],"parameters":[],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"credential":{"type":"object","properties":{"type":{"type":"string","description":"Open vocabulary: `tenant` (a tenant API key, `hsk_…`), `oauth` (a user access token, `hs_at_…`) or `portfolio` (an MSSP portfolio key, `hsp_…`).","x-hs-known-values":["tenant","oauth","portfolio"]},"prefix":{"description":"The clear key prefix (`hsp_…`) of a portfolio key. Null for a tenant key or an OAuth token. Never the full key and never a hash.","type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes the credential carries."},"expires_at":{"description":"When a tenant API key (`hsk_…`) stops working, RFC 3339 UTC; null for a key with no expiry. Always null for an OAuth access token, which a client renews with its refresh token, and, for now, for a portfolio key (not reported).","type":["string","null"]}},"required":["type","prefix","scopes","expires_at"],"additionalProperties":false,"description":"The credential that made this call."},"tenant":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The tenant this credential reads (lowercase)."},"name":{"type":"string","description":"Display name. Untrusted text."},"type":{"type":"string","description":"The type of the organisation that owns the tenant. Open vocabulary: `direct` (a customer organisation), `mssp` (a managed security service provider) or `root` (the platform operator). Treat an unknown value as opaque.","x-hs-known-values":["direct","mssp","root"]}},"required":["id","name","type"],"additionalProperties":false},{"type":"null"}],"description":"The credential’s own tenant. Null for a portfolio key, which has no tenant."},"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"description":"Display name. Null for a portfolio key whose client subset holds none of the provider’s own tenants, the only place a portfolio key sees the name. Untrusted text.","type":["string","null"]},"type":{"type":"string","description":"`direct`, `mssp` or `root`; `mssp` for a portfolio key."}},"required":["id","name","type"],"additionalProperties":false,"description":"The organisation of the tenant (tenant key, OAuth token) or the MSSP the key belongs to (portfolio key)."},"beta":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","description":"The beta status of the tenant’s own organisation, or `active` while the beta of its parent MSSP runs and lifts its access. Open vocabulary: `active`, `ended` or `converted`.","x-hs-known-values":["active","ended","converted"]},"running":{"type":"boolean","description":"True while the beta runs: status `active` and `ends_at` in the future. While it runs the organisation has Enterprise access."},"ends_at":{"description":"When the own organisation’s beta ends or ended, ISO 8601 UTC. Null when no end is recorded, and always null for a beta inherited from the parent MSSP.","type":["string","null"]}},"required":["status","running","ends_at"],"additionalProperties":false},{"type":"null"}],"description":"The beta of the tenant’s own organisation; while it does not run and the parent MSSP’s beta does, `active` and running with no date. Nothing else about the parent’s beta is described: not its end, nor whether it ended or converted. Null when the own organisation never joined the beta and no parent beta runs, and for a portfolio key."},"user":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The user the access token belongs to (lowercase)."},"name":{"description":"The user’s display name. Untrusted text.","type":["string","null"]},"email":{"description":"The user’s email address. Present only when the access token carries the `email` scope; omitted otherwise.","type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The signed-in user of an OAuth access token (`hs_at_…`): the CALLER’S OWN id, name and, with the `email` scope, email; never another user’s. Null for a tenant API key and for a portfolio key, which act for no user, and for a token whose user row is no longer visible in the token’s tenant."},"portfolio":{"anyOf":[{"type":"object","properties":{"tenant_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many tenants this key can select, right now."},"tenants_path":{"type":"string","description":"Where the tenants are listed: `GET /v1/portfolio/tenants`."}},"required":["tenant_count","tenants_path"],"additionalProperties":false},{"type":"null"}],"description":"Portfolio keys only. Null for a tenant key or an OAuth token."}},"required":["credential","tenant","organization","beta","user","portfolio"],"additionalProperties":false,"description":"The credential that made the call, and what it may see about itself."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"none":true}}},"/v1/reports":{"get":{"operationId":"listReports","summary":"List generated reports","description":"The reports generated for the tenant, newest first by default. Poll for new ones with `since` plus `order=asc`; download one with `downloadReport` once its `status` is `completed`.\n\nRequired scope: `reports:read`. Published in `/v1` since 2026-10-19.","tags":["reports"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, period_end.","schema":{"default":"created_at","type":"string","enum":["created_at","period_end"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"report_type","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["monthly","vendor_risk","nis2_compliance","ens","cyberbrief","compliance","security_posture","board_report"],"type":"string","minLength":1,"maxLength":50}},{"name":"status","in":"query","required":false,"description":"Exact status match. Known values: generating, completed, failed. Open vocabulary: any other value is matched exactly and matches nothing.","schema":{"x-hs-known-values":["generating","completed","failed"],"type":"string","minLength":1,"maxLength":20}},{"name":"since","in":"query","required":false,"description":"Only reports created at or after this RFC 3339 instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"report_type":{"type":"string","description":"What kind of report this is. Known values: monthly, vendor_risk, nis2_compliance, ens, cyberbrief, compliance, security_posture, board_report. Open vocabulary: a new kind may appear.","x-hs-known-values":["monthly","vendor_risk","nis2_compliance","ens","cyberbrief","compliance","security_posture","board_report"]},"title":{"type":"string"},"period_start":{"type":"string","description":"First day the report covers, `YYYY-MM-DD`."},"period_end":{"type":"string","description":"Last day the report covers, `YYYY-MM-DD`."},"status":{"type":"string","description":"Lifecycle: generating | completed | failed. Only a `completed` report can be downloaded.","x-hs-known-values":["generating","completed","failed"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","report_type","title","period_start","period_end","status","created_at"],"additionalProperties":false,"description":"A report the platform generated for the tenant (metadata only)."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["reports:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["reports:read"]}}},"/v1/reports/{id}":{"get":{"operationId":"getReport","summary":"Fetch one report","description":"The same object `listReports` returns, for a single report, plus the formats it can be downloaded in now (`download_formats`).\n\nRequired scope: `reports:read`. Published in `/v1` since 2026-10-19.","tags":["reports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Report identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"report_type":{"type":"string","description":"What kind of report this is. Known values: monthly, vendor_risk, nis2_compliance, ens, cyberbrief, compliance, security_posture, board_report. Open vocabulary: a new kind may appear.","x-hs-known-values":["monthly","vendor_risk","nis2_compliance","ens","cyberbrief","compliance","security_posture","board_report"]},"title":{"type":"string"},"period_start":{"type":"string","description":"First day the report covers, `YYYY-MM-DD`."},"period_end":{"type":"string","description":"Last day the report covers, `YYYY-MM-DD`."},"status":{"type":"string","description":"Lifecycle: generating | completed | failed. Only a `completed` report can be downloaded.","x-hs-known-values":["generating","completed","failed"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"download_formats":{"type":"array","items":{"type":"string","description":"A format `downloadReport` serves. Known values: pdf, xlsx. Open vocabulary: a format may be added.","x-hs-known-values":["pdf","xlsx"]},"description":"The formats `downloadReport` can serve for this report now. Empty while it is not `completed`, or when its content has no renderer (download it from the console as Markdown or JSON)."}},"required":["id","report_type","title","period_start","period_end","status","created_at","download_formats"],"additionalProperties":false,"description":"One report, with the formats it can be downloaded in."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["reports:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["reports:read"]}}},"/v1/reports/{id}/download":{"get":{"operationId":"downloadReport","summary":"Download a report file","description":"The report rendered as a file (PDF or XLSX), returned as 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. A report that is not `completed`, a format its content has no renderer for (see `download_formats` in `getReport`) and a file over the size cap are a 409.\n\nRequired scope: `reports:read`. Published in `/v1` since 2026-10-19.","tags":["reports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Report identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"format","in":"query","required":false,"description":"File format, one of: pdf, xlsx. Defaults to pdf. `getReport` lists the formats a report can be served in (`download_formats`).","schema":{"default":"pdf","type":"string","enum":["pdf","xlsx"]}},{"name":"locale","in":"query","required":false,"description":"Language of the file, one of: es, en, de, fr, it, eu. Defaults to en.","schema":{"default":"en","type":"string","enum":["es","en","de","fr","it","eu"]}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The file, as an attachment. At most 20971520 bytes; a larger one is a 409 `FILE_TOO_LARGE`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}},"Content-Disposition":{"description":"`attachment; filename=\"<name>.<extension>\"`. The name is `[A-Za-z0-9._-]`.","schema":{"type":"string"}},"Content-Length":{"description":"Size of the file in bytes.","schema":{"type":"integer","minimum":0}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The file cannot be served as asked. `error.details.code` says why: `REPORT_NOT_READY` (the report is still `generating`, or `failed`; `error.details.status` says which. Retry a `generating` one later); `FORMAT_UNSUPPORTED` (the report’s content has no renderer for that format; `error.details.formats` lists the ones it has, possibly none); `FILE_TOO_LARGE` (the file is larger than 20971520 bytes; `error.details.limit_bytes` says the cap, and no byte is sent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["reports:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["reports:read"]}}},"/v1/changes":{"get":{"operationId":"listChanges","summary":"List change requests","description":"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.\n\nRequired scope: `changes:read`. Published in `/v1` since 2026-10-27.","tags":["changes"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, planned_start_at, implemented_at.","schema":{"default":"created_at","type":"string","enum":["created_at","planned_start_at","implemented_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","enum":["draft","submitted","approved","rejected","scheduled","implementing","implemented","failed","rolled_back","in_review","closed","cancelled"]}},{"name":"change_type","in":"query","required":false,"description":"Exact type match.","schema":{"type":"string","enum":["normal","emergency"]}},{"name":"category","in":"query","required":false,"description":"Exact category match.","schema":{"type":"string","enum":["infrastructure","application","configuration","access","vendor","other"]}},{"name":"created_from","in":"query","required":false,"description":"Only changes created on or after this `YYYY-MM-DD` (UTC).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"created_to","in":"query","required":false,"description":"Only changes created on or before this `YYYY-MM-DD` (UTC).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ref":{"type":"string","description":"Human reference, `CHG-<year>-<number>`, unique per tenant."},"title":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","approved","rejected","scheduled","implementing","implemented","failed","rolled_back","in_review","closed","cancelled"]},"change_type":{"type":"string","enum":["normal","emergency"],"description":"`emergency` may be carried out before approval."},"category":{"type":"string","enum":["infrastructure","application","configuration","access","vendor","other"]},"risk_level":{"type":"string","enum":["low","medium","high"]},"planned_start_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"planned_end_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"implemented_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"closed_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"outcome":{"anyOf":[{"type":"string","enum":["successful","failed","rolled_back"]},{"type":"null"}],"description":"Set by the post-change review."},"approved_without_second_person":{"type":"boolean","description":"True when four-eyes approval was waived because the tenant has a single administrator."},"external_ref":{"description":"Reference in an external ITSM, when linked.","type":["string","null"]},"approvals":{"type":"object","properties":{"approved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["approved","rejected"],"additionalProperties":false,"description":"How many decisions the change holds."},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","ref","title","status","change_type","category","risk_level","planned_start_at","planned_end_at","implemented_at","closed_at","outcome","approved_without_second_person","external_ref","approvals","created_at"],"additionalProperties":false,"description":"One change request of the register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["changes:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["changes:read"]}}},"/v1/incidents":{"get":{"operationId":"listIncidents","summary":"List incidents","description":"The tenant's incident register: type, severity, status, the key dates and, per incident, its regulatory notification deadlines (DORA, NIS2, GDPR, AI Act) with their stage, status, due date and submission date. Read only; free text but the title and people are not published.\n\nRequired scope: `incidents:read`. Published in `/v1` since 2026-11-17.","tags":["incidents"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: detected_at, created_at, updated_at.","schema":{"default":"detected_at","type":"string","enum":["detected_at","created_at","updated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["open","investigating","contained","resolved","closed"],"type":"string","minLength":1,"maxLength":20}},{"name":"severity","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["critical","high","medium","low"],"type":"string","minLength":1,"maxLength":12}},{"name":"type","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["cybersecurity","service_disruption","data_breach","system_failure","third_party","fraud","physical","compliance"],"type":"string","minLength":1,"maxLength":24}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}},"X-HS-Unknown-Filter":{"description":"Present only when a filter value is outside the parameter’s published `x-hs-known-values`: the name(s) of the parameter(s), comma-separated (for example `severity, status`). The request was served as sent, so the list is usually empty; the same entries are in `meta.warnings`. Absent when every filter value is a published one.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reference":{"type":"string","description":"Human reference, unique per tenant."},"title":{"type":"string"},"type":{"type":"string","description":"Incident type: cybersecurity | service_disruption | data_breach | system_failure | third_party | fraud | physical | compliance.","x-hs-known-values":["cybersecurity","service_disruption","data_breach","system_failure","third_party","fraud","physical","compliance"]},"severity":{"type":"string","description":"Severity: critical | high | medium | low.","x-hs-known-values":["critical","high","medium","low"]},"status":{"type":"string","description":"Lifecycle status: open | investigating | contained | resolved | closed.","x-hs-known-values":["open","investigating","contained","resolved","closed"]},"phase":{"type":"string","description":"Response phase: detection | classification | response | resolution | post_incident.","x-hs-known-values":["detection","classification","response","resolution","post_incident"]},"occurred_at":{"type":"string","description":"RFC 3339, UTC."},"detected_at":{"type":"string","description":"RFC 3339, UTC: the moment of awareness."},"classified_major_at":{"description":"RFC 3339, UTC: when the incident was classified as major (DORA).","type":["string","null"]},"contained_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"recovered_at":{"description":"RFC 3339, UTC: when regular activities were recovered (DORA).","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"closed_at":{"description":"RFC 3339, UTC: when it last entered `closed`.","type":["string","null"]},"personal_data_breached":{"type":"boolean"},"cross_border":{"type":"boolean"},"ai_system_involved":{"type":"boolean"},"aiact_role":{"description":"The tenant's AI Act role towards the AI system involved: provider | deployer; null when not declared.","x-hs-known-values":["provider","deployer"],"type":["string","null"]},"gdpr_role":{"description":"The tenant's GDPR role for this incident: controller | processor; null when the tenant's general declaration applies.","x-hs-known-values":["controller","processor"],"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The third party the incident involves, when any."},"notifications":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Regulatory regime: dora | nis2 | gdpr | aiact.","x-hs-known-values":["dora","nis2","gdpr","aiact"]},"stage":{"type":"string","description":"The report this deadline is for, within its regime (for example `early_warning`, `notification` and `final` under NIS2; `initial`, `intermediate` and `final` under DORA): initial | intermediate | intermediate_recovery | final | client_notification | early_warning | notification | recipient_notification | dpa_notification | subject_notification | controller_notification | serious_incident.","x-hs-known-values":["initial","intermediate","intermediate_recovery","final","client_notification","early_warning","notification","recipient_notification","dpa_notification","subject_notification","controller_notification","serious_incident"]},"status":{"type":"string","description":"Live state, computed on every read as the console computes it: `pending` (due, not yet submitted), `overdue` (past due, not submitted), `met` / `met_late` (submitted on or before / after the due date), `awaiting` (the event its clock runs from is not recorded yet, so it has no date), `undue_delay` (the norm sets no figure, so it has no date). Known values: pending | met | met_late | overdue | na | awaiting | undue_delay.","x-hs-known-values":["pending","met","met_late","overdue","na","awaiting","undue_delay"]},"anchor":{"description":"The event the clock runs from: awareness | classified | previous_submission | resolved | recovered; null on a deadline stored before anchors were recorded.","x-hs-known-values":["awareness","classified","previous_submission","resolved","recovered"],"type":["string","null"]},"due_at":{"description":"RFC 3339, UTC. Null while `awaiting`, and for `undue_delay`: never an invented date.","type":["string","null"]},"submitted_at":{"description":"RFC 3339, UTC: when the report that met this deadline was submitted (the earliest recorded submission that satisfies it). Null while none has.","type":["string","null"]}},"required":["framework","stage","status","anchor","due_at","submitted_at"],"additionalProperties":false,"description":"One regulatory notification deadline of the incident."},"description":"The regulatory notification deadlines of the incident, by regime then due date. Empty when no regime applies."},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","reference","title","type","severity","status","phase","occurred_at","detected_at","classified_major_at","contained_at","recovered_at","resolved_at","closed_at","personal_data_breached","cross_border","ai_system_involved","aiact_role","gdpr_role","vendor_id","notifications","created_at","updated_at"],"additionalProperties":false,"description":"One incident of the tenant register, with its notification deadlines."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false},"meta":{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","description":"The query parameter whose value is not in the published list."},"value":{"type":"string","description":"The value as sent."},"known":{"type":"array","items":{"type":"string"},"description":"The published values of the parameter (its `x-hs-known-values`)."}},"required":["param","value","known"],"additionalProperties":false,"description":"A filter value outside the published vocabulary. The request was served as sent."},"description":"One entry per filter whose value is not a published value. The list is still filtered by the value as sent (so it is usually empty); the same parameters are named in the `X-HS-Unknown-Filter` response header."}},"required":["warnings"],"additionalProperties":false,"description":"Present only when at least one filter value is outside its published list; omitted otherwise."}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["incidents:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["incidents:read"]}}},"/v1/incidents/{id}":{"get":{"operationId":"getIncident","summary":"Fetch one incident","description":"The same object `listIncidents` returns, for a single incident.\n\nRequired scope: `incidents:read`. Published in `/v1` since 2026-11-17.","tags":["incidents"],"parameters":[{"name":"id","in":"path","required":true,"description":"Incident identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reference":{"type":"string","description":"Human reference, unique per tenant."},"title":{"type":"string"},"type":{"type":"string","description":"Incident type: cybersecurity | service_disruption | data_breach | system_failure | third_party | fraud | physical | compliance.","x-hs-known-values":["cybersecurity","service_disruption","data_breach","system_failure","third_party","fraud","physical","compliance"]},"severity":{"type":"string","description":"Severity: critical | high | medium | low.","x-hs-known-values":["critical","high","medium","low"]},"status":{"type":"string","description":"Lifecycle status: open | investigating | contained | resolved | closed.","x-hs-known-values":["open","investigating","contained","resolved","closed"]},"phase":{"type":"string","description":"Response phase: detection | classification | response | resolution | post_incident.","x-hs-known-values":["detection","classification","response","resolution","post_incident"]},"occurred_at":{"type":"string","description":"RFC 3339, UTC."},"detected_at":{"type":"string","description":"RFC 3339, UTC: the moment of awareness."},"classified_major_at":{"description":"RFC 3339, UTC: when the incident was classified as major (DORA).","type":["string","null"]},"contained_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"recovered_at":{"description":"RFC 3339, UTC: when regular activities were recovered (DORA).","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"closed_at":{"description":"RFC 3339, UTC: when it last entered `closed`.","type":["string","null"]},"personal_data_breached":{"type":"boolean"},"cross_border":{"type":"boolean"},"ai_system_involved":{"type":"boolean"},"aiact_role":{"description":"The tenant's AI Act role towards the AI system involved: provider | deployer; null when not declared.","x-hs-known-values":["provider","deployer"],"type":["string","null"]},"gdpr_role":{"description":"The tenant's GDPR role for this incident: controller | processor; null when the tenant's general declaration applies.","x-hs-known-values":["controller","processor"],"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The third party the incident involves, when any."},"notifications":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Regulatory regime: dora | nis2 | gdpr | aiact.","x-hs-known-values":["dora","nis2","gdpr","aiact"]},"stage":{"type":"string","description":"The report this deadline is for, within its regime (for example `early_warning`, `notification` and `final` under NIS2; `initial`, `intermediate` and `final` under DORA): initial | intermediate | intermediate_recovery | final | client_notification | early_warning | notification | recipient_notification | dpa_notification | subject_notification | controller_notification | serious_incident.","x-hs-known-values":["initial","intermediate","intermediate_recovery","final","client_notification","early_warning","notification","recipient_notification","dpa_notification","subject_notification","controller_notification","serious_incident"]},"status":{"type":"string","description":"Live state, computed on every read as the console computes it: `pending` (due, not yet submitted), `overdue` (past due, not submitted), `met` / `met_late` (submitted on or before / after the due date), `awaiting` (the event its clock runs from is not recorded yet, so it has no date), `undue_delay` (the norm sets no figure, so it has no date). Known values: pending | met | met_late | overdue | na | awaiting | undue_delay.","x-hs-known-values":["pending","met","met_late","overdue","na","awaiting","undue_delay"]},"anchor":{"description":"The event the clock runs from: awareness | classified | previous_submission | resolved | recovered; null on a deadline stored before anchors were recorded.","x-hs-known-values":["awareness","classified","previous_submission","resolved","recovered"],"type":["string","null"]},"due_at":{"description":"RFC 3339, UTC. Null while `awaiting`, and for `undue_delay`: never an invented date.","type":["string","null"]},"submitted_at":{"description":"RFC 3339, UTC: when the report that met this deadline was submitted (the earliest recorded submission that satisfies it). Null while none has.","type":["string","null"]}},"required":["framework","stage","status","anchor","due_at","submitted_at"],"additionalProperties":false,"description":"One regulatory notification deadline of the incident."},"description":"The regulatory notification deadlines of the incident, by regime then due date. Empty when no regime applies."},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","reference","title","type","severity","status","phase","occurred_at","detected_at","classified_major_at","contained_at","recovered_at","resolved_at","closed_at","personal_data_breached","cross_border","ai_system_involved","aiact_role","gdpr_role","vendor_id","notifications","created_at","updated_at"],"additionalProperties":false,"description":"One incident of the tenant register, with its notification deadlines."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["incidents:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["incidents:read"]}}},"/v1/ai-systems":{"get":{"operationId":"listAiSystems","summary":"List AI systems","description":"The tenant's register of AI systems: risk class, lifecycle status, kind, owning unit, provider and the categories of data each processes. Read only; free text 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; the role an incident declared is `aiact_role` on `/v1/incidents`.\n\nRequired scope: `ai_systems:read`. Published in `/v1` since 2026-11-17.","tags":["ai-systems"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, name.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","name"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"risk_class","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["prohibited","high_risk","transparency","minimal"],"type":"string","minLength":1,"maxLength":20}},{"name":"lifecycle_status","in":"query","required":false,"description":"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.","schema":{"x-hs-known-values":["planned","pilot","in_use","retired"],"type":"string","minLength":1,"maxLength":20}},{"name":"vendor_id","in":"query","required":false,"description":"Only systems provided by this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}},"X-HS-Unknown-Filter":{"description":"Present only when a filter value is outside the parameter’s published `x-hs-known-values`: the name(s) of the parameter(s), comma-separated (for example `severity, status`). The request was served as sent, so the list is usually empty; the same entries are in `meta.warnings`. Absent when every filter value is a published one.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Name of the system, unique per tenant."},"risk_class":{"type":"string","description":"EU AI Act risk class recorded for the system: prohibited | high_risk | transparency | minimal.","x-hs-known-values":["prohibited","high_risk","transparency","minimal"]},"lifecycle_status":{"type":"string","description":"Lifecycle status: planned | pilot | in_use | retired.","x-hs-known-values":["planned","pilot","in_use","retired"]},"system_type":{"description":"Kind of system: llm | agent | rag | predictive; null when not stated.","x-hs-known-values":["llm","agent","rag","predictive"],"type":["string","null"]},"department":{"description":"The organisational unit that owns the system, as the tenant labelled it.","type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The third party that provides the system, when any."},"data_categories":{"type":"array","items":{"type":"string","description":"Category of data the system processes: personal | special_category | employee | customer | confidential | source_code | public.","x-hs-known-values":["personal","special_category","employee","customer","confidential","source_code","public"]},"description":"Categories of data the system processes."},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC: the last change to the entry."}},"required":["id","name","risk_class","lifecycle_status","system_type","department","vendor_id","data_categories","created_at","updated_at"],"additionalProperties":false,"description":"One AI system of the tenant register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false},"meta":{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","description":"The query parameter whose value is not in the published list."},"value":{"type":"string","description":"The value as sent."},"known":{"type":"array","items":{"type":"string"},"description":"The published values of the parameter (its `x-hs-known-values`)."}},"required":["param","value","known"],"additionalProperties":false,"description":"A filter value outside the published vocabulary. The request was served as sent."},"description":"One entry per filter whose value is not a published value. The list is still filtered by the value as sent (so it is usually empty); the same parameters are named in the `X-HS-Unknown-Filter` response header."}},"required":["warnings"],"additionalProperties":false,"description":"Present only when at least one filter value is outside its published list; omitted otherwise."}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["ai_systems:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["ai_systems:read"]}}},"/v1/ai-systems/{id}":{"get":{"operationId":"getAiSystem","summary":"Fetch one AI system","description":"The same object `listAiSystems` returns, for a single system.\n\nRequired scope: `ai_systems:read`. Published in `/v1` since 2026-11-17.","tags":["ai-systems"],"parameters":[{"name":"id","in":"path","required":true,"description":"AI system identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Name of the system, unique per tenant."},"risk_class":{"type":"string","description":"EU AI Act risk class recorded for the system: prohibited | high_risk | transparency | minimal.","x-hs-known-values":["prohibited","high_risk","transparency","minimal"]},"lifecycle_status":{"type":"string","description":"Lifecycle status: planned | pilot | in_use | retired.","x-hs-known-values":["planned","pilot","in_use","retired"]},"system_type":{"description":"Kind of system: llm | agent | rag | predictive; null when not stated.","x-hs-known-values":["llm","agent","rag","predictive"],"type":["string","null"]},"department":{"description":"The organisational unit that owns the system, as the tenant labelled it.","type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The third party that provides the system, when any."},"data_categories":{"type":"array","items":{"type":"string","description":"Category of data the system processes: personal | special_category | employee | customer | confidential | source_code | public.","x-hs-known-values":["personal","special_category","employee","customer","confidential","source_code","public"]},"description":"Categories of data the system processes."},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC: the last change to the entry."}},"required":["id","name","risk_class","lifecycle_status","system_type","department","vendor_id","data_categories","created_at","updated_at"],"additionalProperties":false,"description":"One AI system of the tenant register."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["ai_systems:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["ai_systems:read"]}}},"/v1/alerts/{id}/acknowledge":{"post":{"operationId":"acknowledgeAlert","summary":"Acknowledge an alert","description":"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. Authorised by the API key and its scope alone, with no interactive confirmation: the key acts with the role of the user who CREATED it, read on every request (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 the key’s client set is a 404 (`TENANT_NOT_FOUND`), and inside it the key acts with the role of the MSSP user who created it, who must still reach that client in the console (403 `WRITE_ACTOR_UNRESOLVED` otherwise); only an MSSP organisation administrator can grant `alerts:write` on a portfolio key. Writes have their own rate-limit 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 audit row in the tenant’s 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.\n\nRequired scope: `alerts:write`. Published in `/v1` since 2026-11-14.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"A JSON object (`Content-Type: application/json`, at most 8 KiB). An unknown key is a 400.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Free text, at most 500 characters. Kept in the audit trail."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"updated_at":{"type":"string","description":"RFC 3339, UTC. Moves on every change of status."}},"required":["id","status","acknowledged_at","resolved_at","resolution_reason","updated_at"],"additionalProperties":false,"description":"The state of the alert after the request. Its content (title, description, vendor) is `GET /v1/alerts/{id}`, under `supply_risk:read`."},"changed":{"type":"boolean","description":"`true` when THIS request changed the alert (and wrote its audit row); `false` when the alert was already in the state asked for and nothing was written."}},"required":["data","changed"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. For this write also: `ROLE_NOT_PERMITTED` (the role the key acts with may not triage alerts (only a role that may write, or an MSSP analyst, may)); `WRITE_ACTOR_UNRESOLVED` (the user who created the key no longer exists, is not active or no longer reaches the tenant; nothing was written).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource is not in a state this request can change, and nothing was written. `error.details.code` says why: `ALERT_RESOLVED` (the alert is already resolved; `error.details.status` is `resolved`); `ALERT_STATE_CHANGED` (the alert changed between the read and the write of this request; read it again).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["alerts:write"]}}},"/v1/alerts/{id}/resolve":{"post":{"operationId":"resolveAlert","summary":"Resolve an alert","description":"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 may close it in the console: an MSSP analyst's key closes medium and low alerts only (403 `ROLE_NOT_PERMITTED`). Authorised by the API key and its scope alone, with no interactive confirmation: the key acts with the role of the user who CREATED it, read on every request (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 the key’s client set is a 404 (`TENANT_NOT_FOUND`), and inside it the key acts with the role of the MSSP user who created it, who must still reach that client in the console (403 `WRITE_ACTOR_UNRESOLVED` otherwise); only an MSSP organisation administrator can grant `alerts:write` on a portfolio key. Writes have their own rate-limit 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 audit row in the tenant’s 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.\n\nRequired scope: `alerts:write`. Published in `/v1` since 2026-11-14.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"A JSON object (`Content-Type: application/json`, at most 8 KiB). An unknown key is a 400.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Why the alert is closed: required, at least two non-blank characters, at most 500. It becomes the alert's `resolution_reason` and is kept in the audit trail."}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"updated_at":{"type":"string","description":"RFC 3339, UTC. Moves on every change of status."}},"required":["id","status","acknowledged_at","resolved_at","resolution_reason","updated_at"],"additionalProperties":false,"description":"The state of the alert after the request. Its content (title, description, vendor) is `GET /v1/alerts/{id}`, under `supply_risk:read`."},"changed":{"type":"boolean","description":"`true` when THIS request changed the alert (and wrote its audit row); `false` when the alert was already in the state asked for and nothing was written."}},"required":["data","changed"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. For this write also: `ROLE_NOT_PERMITTED` (the role the key acts with may not close this alert: it may not triage alerts at all, or it is an MSSP analyst and the alert is critical or high); `WRITE_ACTOR_UNRESOLVED` (the user who created the key no longer exists, is not active or no longer reaches the tenant; nothing was written).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource is not in a state this request can change, and nothing was written. `error.details.code` says why: `ALERT_STATE_CHANGED` (the alert changed between the read and the write of this request; read it again).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["alerts:write"]}}},"/v1/act/proposals":{"post":{"operationId":"createActProposal","summary":"Propose an action a person approves in the console","description":"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.\n\nRequired 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)`. Published in `/v1` since 2026-11-15.","tags":["proposals"],"parameters":[{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"class":{"type":"string","enum":["create_task","schedule_vendor_scan","request_vendor_evidence"],"description":"The action class to propose."},"fields":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":64},"additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"description":"The class's fields (for example `title`, `priority`, `dueDate` for `create_task`; `vendorId` for `schedule_vendor_scan`). Validated by the class's own schema; an unknown field is ignored."},"rationale":{"type":"string","minLength":1,"maxLength":2000,"description":"Why this is proposed. Shown to the person who decides."}},"required":["class","fields","rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"The same content was already proposed by this grant: that proposal, unchanged.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The proposal id, for `GET /v1/act/proposals/{id}`."},"status":{"type":"string","enum":["proposed","approved","rejected","executed","expired","refused"],"description":"`proposed` (waiting for a person), `approved`, `executed`, `rejected` (a person said no), `refused` (the system did; `refusal_reason` says why) or `expired` (nobody decided within 7 days; reported as soon as `expires_at` passes)."},"expires_at":{"type":"string","description":"RFC 3339, UTC. After this instant nobody can approve it and it reads `expired`."}},"required":["id","status","expires_at"],"additionalProperties":false}}}},"201":{"description":"Recorded: a new proposal waits for a person to decide it.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The proposal id, for `GET /v1/act/proposals/{id}`."},"status":{"type":"string","enum":["proposed","approved","rejected","executed","expired","refused"],"description":"`proposed` (waiting for a person), `approved`, `executed`, `rejected` (a person said no), `refused` (the system did; `refusal_reason` says why) or `expired` (nobody decided within 7 days; reported as soon as `expires_at` passes)."},"expires_at":{"type":"string","description":"RFC 3339, UTC. After this instant nobody can approve it and it reads `expired`."}},"required":["id","status","expires_at"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored). On this operation also: `BODY_NOT_JSON` (the body is not `application/json` or not valid JSON); `BODY_TOO_LARGE` (the body exceeds 16384 bytes (`limit_bytes`)); `VALIDATION_FAILED` (the fields do not satisfy the class's schema (`issues` names them)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. On this operation also: `CREDENTIAL_NOT_ALLOWED` (the credential is not a user access token issued for the HodeiShield MCP server).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource exists but cannot be served in that form right now, or (on `createActProposal`) the proposal cannot be recorded, or (on `approveActProposal` and `rejectActProposal`) the proposal cannot be decided: `error.details.code` says why. On this operation also: `DUPLICATE` (the same content was already proposed in this tenant by another grant); `OPEN_PROPOSAL_CAP` (too many open proposals: 20 for this grant, 20 for this user across all their applications, or 100 for the tenant (`scope` is `grant`, `user` or `tenant`, `limit` the cap)); `ACTIONS_PAUSED` (proposing actions is paused for this tenant or platform-wide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"oauth2":["act:propose"]}],"x-hs-scope":{"template":"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)"}}},"/v1/act/proposals/{id}":{"get":{"operationId":"getActProposal","summary":"Status of a proposal this application made","description":"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.\n\nRequired scope: `act:propose`. Published in `/v1` since 2026-11-15.","tags":["proposals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Proposal identifier, as `createActProposal` returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["proposed","approved","rejected","executed","expired","refused"],"description":"`proposed` (waiting for a person), `approved`, `executed`, `rejected` (a person said no), `refused` (the system did; `refusal_reason` says why) or `expired` (nobody decided within 7 days; reported as soon as `expires_at` passes)."},"refusal_reason":{"description":"Why the system refused it (`refused` only), from an open vocabulary: for example `grant_revoked` (this access was revoked before it ran), `mcp_not_open` (the plan no longer includes the MCP) or `approval_expired`. Null otherwise.","type":["string","null"]},"executed_at":{"description":"RFC 3339, UTC, when it was executed; else null.","type":["string","null"]}},"required":["status","refusal_reason","executed_at"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. On this operation also: `CREDENTIAL_NOT_ALLOWED` (the credential is not a user access token issued for the HodeiShield MCP server).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"oauth2":["act:propose"]}],"x-hs-scope":{"scopes":["act:propose"]}}},"/v1/risks/{id}/transition":{"post":{"operationId":"transitionRisk","summary":"Move a risk along its lifecycle","description":"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 the key’s 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 rate-limit 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 audit row in the tenant’s 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.\n\nRequired scope: `risks:write`. Published in `/v1` since 2026-11-18.","tags":["risks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Risk identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"A JSON object (`Content-Type: application/json`, at most 8 KiB). An unknown key is a 400.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"to_status":{"type":"string","enum":["identified","assessed","treatment_planned","treatment_implemented","closed"],"description":"The lifecycle status to move the entry to."},"note":{"description":"Why, free text, at most 2000 characters. Kept in the register's history and the audit trail.","type":"string","maxLength":2000}},"required":["to_status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["identified","assessed","treatment_planned","treatment_implemented","closed"],"description":"The lifecycle status after the request."},"updated_at":{"type":"string","description":"RFC 3339, UTC. Moves on every change of status."}},"required":["id","status","updated_at"],"additionalProperties":false,"description":"The state of the entry after the request. Its content (title, scores, owner) is `GET /v1/risks/{id}`, under `supply_risk:read`."},"changed":{"type":"boolean","description":"`true` when THIS request moved the entry (and wrote its history and audit rows); `false` when the entry already had the status asked for and nothing was written."}},"required":["data","changed"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. For this write also: `ROLE_NOT_PERMITTED` (the role the key acts with may not move risks (only an administrator role of the tenant may)); `WRITE_ACTOR_UNRESOLVED` (the user who created the key no longer exists, is not active or no longer reaches the tenant; nothing was written).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource is not in a state this request can change, and nothing was written. `error.details.code` says why: `TRANSITION_NOT_ALLOWED` (the lifecycle does not allow that move from the current status; `error.details.status` is the current status and `error.details.allowed` where it may go).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["risks:write"]}}},"/v1/act/inbox":{"get":{"operationId":"listPendingActProposals","summary":"Proposals waiting for a decision","description":"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`.\n\nRequired scope: `act:decide`. Published in `/v1` since 2026-11-18.","tags":["proposals"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: expires_at, created_at.","schema":{"default":"expires_at","type":"string","enum":["expires_at","created_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to asc (the proposal that expires soonest first).","schema":{"default":"asc","type":"string","enum":["asc","desc"]}},{"name":"class","in":"query","required":false,"description":"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.","schema":{"type":"string","enum":["create_risk_entry","create_task","request_vendor_evidence","schedule_vendor_scan","set_vendor_criticality","open_vendor_review","add_roadmap_item"]}},{"name":"module","in":"query","required":false,"description":"Only proposals whose action class needs this module (`supply_risk`, …). A module no class needs matches nothing.","schema":{"type":"string","minLength":1,"maxLength":48}},{"name":"expires_before","in":"query","required":false,"description":"RFC 3339. Only proposals that stop being decidable before this instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The proposal id, for the approve and reject operations."},"class":{"description":"The action class (`create_task`, …); null for a kind no class declares.","type":["string","null"]},"module":{"description":"The module the class needs, re-checked at the decision; null when none.","type":["string","null"]},"payload_kind":{"type":"string"},"payload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"EXACTLY what would be written if approved and executed. Read it before deciding."},"rationale":{"type":"string","description":"Why it was proposed, as the proposer wrote it."},"confidence":{"description":"The proposing agent's self-reported confidence, 0..1; not calibrated. Null for a proposal made through the MCP.","type":["number","null"]},"proposed_via":{"type":"string","description":"Who recorded the proposal (`mcp.v1`, an agent name, …)."},"proposed_by_you":{"type":"boolean","description":"True when the caller is the user the proposal was made for. Such a proposal is listed only when its class and the tenant policy do not require four-eyes (otherwise the caller could not approve it)."},"created_at":{"type":"string","description":"RFC 3339, UTC."},"expires_at":{"type":"string","description":"RFC 3339, UTC. After this instant nobody can decide it."}},"required":["id","class","module","payload_kind","payload","rationale","confidence","proposed_via","proposed_by_you","created_at","expires_at"],"additionalProperties":false,"description":"A proposal waiting for a decision."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. On this operation also: `CREDENTIAL_NOT_ALLOWED` (the credential is not a user access token of the HodeiShield CLI); `STEP_UP_REQUIRED` (the token's sign-in was confirmed more than 15 minutes ago (`max_grant_age_seconds`); sign in again and repeat).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"oauth2":["act:decide"]}],"x-hs-scope":{"scopes":["act:decide"]}}},"/v1/act/proposals/{id}/approve":{"post":{"operationId":"approveActProposal","summary":"Approve a proposal","description":"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`.\n\nRequired scope: `act:decide`. Published in `/v1` since 2026-11-18.","tags":["proposals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Proposal identifier, as `listPendingActProposals` returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","maxLength":1000,"description":"Why, free text, 1..1000 characters, required. Kept in the tenant's audit trail with the decision."}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["approved","rejected"],"description":"The proposal status after the decision."},"approval_expires_at":{"description":"Approve only, RFC 3339 UTC: the approved action must be executed in the console before this instant, or the approval lapses. Null for a rejection.","type":["string","null"]},"ledger_entry_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The ACT ledger entry that records the decision."}},"required":["id","status","approval_expires_at","ledger_entry_id"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored). On this operation also: `BODY_NOT_JSON` (the body is not `application/json` or not valid JSON); `BODY_TOO_LARGE` (the body exceeds 16384 bytes (`limit_bytes`)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. On this operation also: `CREDENTIAL_NOT_ALLOWED` (the credential is not a user access token of the HodeiShield CLI); `STEP_UP_REQUIRED` (the token's sign-in was confirmed more than 15 minutes ago (`max_grant_age_seconds`); sign in again and repeat); `ROLE_NOT_PERMITTED` (the caller's role may not decide this proposal (the console's rule for its class and the tenant's policy)); `OWN_PROPOSAL` (four-eyes applies and the caller is the user the proposal was made for).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource exists but cannot be served in that form right now, or (on `createActProposal`) the proposal cannot be recorded, or (on `approveActProposal` and `rejectActProposal`) the proposal cannot be decided: `error.details.code` says why. On this operation also: `PROPOSAL_EXPIRED` (the proposal expired); `ALREADY_DECIDED` (the proposal is no longer waiting: already approved, rejected, executed or ended); `ACTIONS_PAUSED` (actions are paused for this tenant or platform-wide); `NOT_DECIDABLE` (the proposal cannot be decided (`reason` says why, from the ACT vocabulary)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"oauth2":["act:decide"]}],"x-hs-scope":{"scopes":["act:decide"]}}},"/v1/act/proposals/{id}/reject":{"post":{"operationId":"rejectActProposal","summary":"Reject a proposal","description":"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 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`.\n\nRequired scope: `act:decide`. Published in `/v1` since 2026-11-18.","tags":["proposals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Proposal identifier, as `listPendingActProposals` returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"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.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","maxLength":1000,"description":"Why, free text, 1..1000 characters, required. Kept in the tenant's audit trail with the decision."}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["approved","rejected"],"description":"The proposal status after the decision."},"approval_expires_at":{"description":"Approve only, RFC 3339 UTC: the approved action must be executed in the console before this instant, or the approval lapses. Null for a rejection.","type":["string","null"]},"ledger_entry_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The ACT ledger entry that records the decision."}},"required":["id","status","approval_expires_at","ledger_entry_id"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`. Or a query parameter name the operation does not declare: `error.details.code` is `UNKNOWN_QUERY_PARAMETER`, `error.details.unknown` lists the names (at most 10, each cut to 64 characters; `error.details.unknown_omitted` counts the rest) and `error.details.allowed` the names the operation accepts (a misspelt name is refused, never ignored). On this operation also: `BODY_NOT_JSON` (the body is not `application/json` or not valid JSON); `BODY_TOO_LARGE` (the body exceeds 16384 bytes (`limit_bytes`)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) does not have active the module of a scope the credential does carry (`error.details.code` is `MODULE_NOT_ENTITLED`, `error.details.scopes` lists those scopes, `error.details.modules` the modules the tenant lacks and, when a compliance framework is entitled but not activated, `error.details.frameworks` those frameworks), or that tenant is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which), or that tenant has an IP allowlist and the request comes from an address outside it (`error.details.code` is `IP_NOT_ALLOWED`), or the credential is an OAuth access token of an account without the second factor that tenant requires (`error.details.code` is `MFA_ENROLLMENT_REQUIRED`), or that tenant’s plan does not include API access, which is included from Comply, except in AI Governance (`error.details.code` is `PLAN_WITHOUT_API` and `error.details.deniedReason` is `plan_without_api`). Re-authenticating alone does not help with the last five: the licence is renewed, the module activated, the address allowed, a second factor enrolled or the plan changed in the console. On this operation also: `CREDENTIAL_NOT_ALLOWED` (the credential is not a user access token of the HodeiShield CLI); `STEP_UP_REQUIRED` (the token's sign-in was confirmed more than 15 minutes ago (`max_grant_age_seconds`); sign in again and repeat); `ROLE_NOT_PERMITTED` (the caller's role may not decide this proposal (the console's rule for its class and the tenant's policy)); `OWN_PROPOSAL` (four-eyes applies and the caller is the user the proposal was made for).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist, is not in this key’s portfolio, or has an IP allowlist that excludes the address of the request (`error.details.code` is `TENANT_NOT_FOUND`; the cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource exists but cannot be served in that form right now, or (on `createActProposal`) the proposal cannot be recorded, or (on `approveActProposal` and `rejectActProposal`) the proposal cannot be decided: `error.details.code` says why. On this operation also: `PROPOSAL_EXPIRED` (the proposal expired); `ALREADY_DECIDED` (the proposal is no longer waiting: already approved, rejected, executed or ended); `ACTIONS_PAUSED` (actions are paused for this tenant or platform-wide); `NOT_DECIDABLE` (the proposal cannot be decided (`reason` says why, from the ACT vocabulary)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`; on a write, `write_key` (the key’s write budget) or `service`; on `createActProposal` also `proposal_grant` (proposals per minute per application and user) or `proposal_user` (proposals per minute per user, across all their applications); on `approveActProposal` and `rejectActProposal` also `decision_user` (decisions per minute per person).","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"oauth2":["act:decide"]}],"x-hs-scope":{"scopes":["act:decide"]}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","method_not_allowed","conflict","rate_limited","internal_error","service_unavailable"],"description":"Closed vocabulary; new members may be added (see Versioning)."},"message":{"type":"string","description":"For a human reading a log. Not stable; do not parse it."},"request_id":{"type":"string","description":"Also the `X-Request-Id` response header."},"details":{"type":"object","additionalProperties":true,"description":"Diagnostic, except `code` and the keys the operation’s error descriptions name, which are contract.","properties":{"code":{"type":"string","description":"OPEN vocabulary (a value keeps its meaning and its HTTP status; new values may be added): `TENANT_HEADER_INVALID`, `TENANT_REQUIRED`, `TENANT_SELECTOR_NOT_SUPPORTED`, `UNKNOWN_QUERY_PARAMETER`, `BODY_NOT_JSON`, `BODY_TOO_LARGE`, `VALIDATION_FAILED` (400), `INSUFFICIENT_SCOPE`, `MODULE_NOT_ENTITLED`, `LICENCE_INACTIVE`, `IP_NOT_ALLOWED`, `MFA_ENROLLMENT_REQUIRED`, `PLAN_WITHOUT_API`, `ROLE_NOT_PERMITTED`, `WRITE_ACTOR_UNRESOLVED`, `CREDENTIAL_NOT_ALLOWED`, `STEP_UP_REQUIRED`, `OWN_PROPOSAL` (403), `TENANT_NOT_FOUND` (404), `REPORT_NOT_READY`, `FORMAT_UNSUPPORTED`, `FILE_TOO_LARGE`, `ALERT_RESOLVED`, `ALERT_STATE_CHANGED`, `DUPLICATE`, `OPEN_PROPOSAL_CAP`, `ACTIONS_PAUSED`, `TRANSITION_NOT_ALLOWED`, `PROPOSAL_EXPIRED`, `ALREADY_DECIDED`, `NOT_DECIDABLE` (409).","x-hs-known-values":["TENANT_HEADER_INVALID","TENANT_REQUIRED","TENANT_SELECTOR_NOT_SUPPORTED","UNKNOWN_QUERY_PARAMETER","INSUFFICIENT_SCOPE","MODULE_NOT_ENTITLED","LICENCE_INACTIVE","IP_NOT_ALLOWED","MFA_ENROLLMENT_REQUIRED","PLAN_WITHOUT_API","TENANT_NOT_FOUND","REPORT_NOT_READY","FORMAT_UNSUPPORTED","FILE_TOO_LARGE","ROLE_NOT_PERMITTED","WRITE_ACTOR_UNRESOLVED","ALERT_RESOLVED","ALERT_STATE_CHANGED","CREDENTIAL_NOT_ALLOWED","BODY_NOT_JSON","BODY_TOO_LARGE","VALIDATION_FAILED","DUPLICATE","OPEN_PROPOSAL_CAP","ACTIONS_PAUSED","TRANSITION_NOT_ALLOWED","STEP_UP_REQUIRED","OWN_PROPOSAL","PROPOSAL_EXPIRED","ALREADY_DECIDED","NOT_DECIDABLE"]},"scopes":{"type":"array","items":{"type":"string"},"description":"With `MODULE_NOT_ENTITLED`: the scopes the credential carries whose module is not active for the tenant read."},"modules":{"type":"array","items":{"type":"string"},"description":"With `MODULE_NOT_ENTITLED`: the module ids the tenant read lacks, one per module, in the order of `scopes` (`supply_risk`, `compliance.nis2`, …; `compliance` for `changes:read`, which needs any activated compliance framework)."},"frameworks":{"type":"array","items":{"type":"string"},"description":"With `MODULE_NOT_ENTITLED`, present only when it applies: the compliance framework ids (`nis2`, …) the tenant read is entitled to but has not activated."},"deniedReason":{"type":"string","description":"With `PLAN_WITHOUT_API`: why the plan of the tenant read offers no API access. Today always `plan_without_api`.","x-hs-known-values":["plan_without_api"]}}}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A tenant API key, created in the console under Settings → API keys with the minimum scopes it needs. Mandatory expiry (at most 365 days); it stops working as soon as the administrator who created it is removed from the tenant or loses the role, unless another administrator of the tenant takes it over."},"portfolioKey":{"type":"http","scheme":"bearer","description":"An MSSP portfolio key (`hsp_…`), created by an organisation administrator of an active managed security service provider in the console’s MSSP area (API keys). It lists the provider’s client tenants (`portfolio:read`) and reads ONE of them per request, selected with `X-HS-Tenant`, with the same data scopes a tenant API key uses. Read scopes, plus at most the two write scopes `alerts:write` (acknowledge and resolve an alert in the selected client) and `risks:write` (move a risk along its lifecycle there), each acting with the role, read on every request, of the provider user who created the key; mandatory expiry (at most 90 days); it stops working as soon as the administrator who created it is removed or loses the role; optional client subset and source IP ranges. Refused with 401 everywhere but `/v1`."},"oauth2":{"type":"oauth2","description":"A USER access token (`hs_at_…`) issued by the HodeiShield console, the OAuth 2.1 authorization server at `https://app.hodeishield.com/api/auth` (metadata: `/.well-known/oauth-authorization-server` on its origin). Authorization code with PKCE (S256, mandatory) for applications with a browser; the RFC 8628 device authorization grant (`https://app.hodeishield.com/api/auth/device/code`) for those without one. Every token is bound to ONE user and ONE tenant, chosen by the user on the consent screen, and carries read scopes only (and, for a token issued for the HodeiShield MCP server, `act:propose`; for a token of the HodeiShield CLI, `act:decide`, which decides proposals as the signed-in person); the tenant is re-checked against what the user can see on every request. Public clients register themselves (RFC 7591) at `/oauth2/register`; the HodeiShield CLI is pre-registered as `hodeishield-cli`. Revocation: RFC 7009 at `/oauth2/revoke`, or by the user in the console under Account → Application access.","flows":{"authorizationCode":{"authorizationUrl":"https://app.hodeishield.com/api/auth/oauth2/authorize","tokenUrl":"https://app.hodeishield.com/api/auth/oauth2/token","refreshUrl":"https://app.hodeishield.com/api/auth/oauth2/token","scopes":{"supply_risk:read":"Read supply_risk data of the tenant the token is bound to.","compliance.nis2:read":"Read compliance.nis2 data of the tenant the token is bound to.","compliance.ens:read":"Read compliance.ens data of the tenant the token is bound to.","compliance.iso27001:read":"Read compliance.iso27001 data of the tenant the token is bound to.","compliance.dora:read":"Read compliance.dora data of the tenant the token is bound to.","compliance.gdpr:read":"Read compliance.gdpr data of the tenant the token is bound to.","compliance.soc2:read":"Read compliance.soc2 data of the tenant the token is bound to.","compliance.iso42001:read":"Read compliance.iso42001 data of the tenant the token is bound to.","compliance.nistcsf:read":"Read compliance.nistcsf data of the tenant the token is bound to.","compliance.pcidss:read":"Read compliance.pcidss data of the tenant the token is bound to.","compliance.euaiact:read":"Read compliance.euaiact data of the tenant the token is bound to.","compliance.hipaa:read":"Read compliance.hipaa data of the tenant the token is bound to.","compliance.cmmc:read":"Read compliance.cmmc data of the tenant the token is bound to.","compliance.cyberessentials:read":"Read compliance.cyberessentials data of the tenant the token is bound to.","compliance.uaeia:read":"Read compliance.uaeia data of the tenant the token is bound to.","compliance.sama:read":"Read compliance.sama data of the tenant the token is bound to.","compliance.saudiecc:read":"Read compliance.saudiecc data of the tenant the token is bound to.","compliance.ndpa:read":"Read compliance.ndpa data of the tenant the token is bound to.","radar:read":"Read radar data of the tenant the token is bound to.","connectors:read":"Read connectors data of the tenant the token is bound to.","endpoints:read":"Read endpoints data of the tenant the token is bound to.","hodeiai:read":"Read hodeiai data of the tenant the token is bound to.","virtual_ciso:read":"Read virtual_ciso data of the tenant the token is bound to.","simulator:read":"Read simulator data of the tenant the token is bound to.","evidence:read":"Read evidence data of the tenant the token is bound to.","reports:read":"Read reports data of the tenant the token is bound to.","ai_governance:read":"Read ai_governance data of the tenant the token is bound to.","management:read":"Read management data of the tenant the token is bound to.","changes:read":"Read changes data of the tenant the token is bound to.","incidents:read":"Read incidents data of the tenant the token is bound to.","ai_systems:read":"Read ai_systems data of the tenant the token is bound to.","email":"Read the email address of the signed-in user (`user.email` on `GET /v1/me`).","offline_access":"Issue a refresh token (30 days, rotated on every use).","act:propose":"Propose actions that a person of the tenant approves in the console (`createActProposal`, `getActProposal`). Only on a token issued for the HodeiShield MCP server; never on a tenant or portfolio key.","act:decide":"Decide, as the signed-in person, the proposals waiting for a decision (`listPendingActProposals`, `approveActProposal`, `rejectActProposal`). Only on a token of the HodeiShield CLI, never on one issued for the HodeiShield MCP server, a tenant key or a portfolio key; a decision also needs a sign-in confirmed within the last 15 minutes. Off unless the server enables it."}}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}]}