Skip to content

API overview

OpenAPI 3.1 specification of the public API: https://api.hodeishield.com/v1/openapi.json (no authentication). Browsable reference: Complete reference.

Your first call

Create an API key in the console (Settings › Integrations and development › Integrations › API Key) and keep it in an environment variable. A tenant key starts with hsk_. GET /v1/me needs no scope and tells you which credential you came in with.

export HODEISHIELD_API_KEY="hsk_..."   # your key; never in code

curl -sS https://api.hodeishield.com/v1/me \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY"

Then a paginated list of vendors (scope supply_risk:read):

curl -sS "https://api.hodeishield.com/v1/vendors?per_page=10" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY"

The response carries data and pagination (page, per_page, total, total_pages). Every authenticated response includes the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. A 401 means the key is missing, revoked, expired or unknown; a 403 means the scope is missing. More in Authentication and Errors.

Filters match exactly. If the value of severity (alerts), domain or status (risks) or status (compliance controls) is not a published one, the response is still 200 with whatever matches, and adds meta.warnings[] (param, value, known) and the X-HS-Unknown-Filter header, so a typo does not look like "no results". Vendor category is free text and is not checked. Details in Versioning.

Availability

The public /v1 API is served at api.hodeishield.com. Its contract is frozen and versioned: the current contract version is 2026-11-21 (the info.version field of the OpenAPI document). To use it you need a credential with the scopes each operation requires and a licence in force on your tenant; without a licence in force the API answers 403 (see Errors). See the versioning policy, the deprecation policy and the rate limits.

Plan

/v1 read access is part of your HodeiShield license. Requests are subject to usage limits that apply per key and per tenant.

What /v1 is

/v1 is HodeiShield's public and versioned contract (version 1 of the contract): a set of read operations over your tenant's data (vendors, alerts, risks, compliance, evidence, and endpoints), plus two writes on alerts (acknowledge and resolve), designed so external systems — a SIEM, a data warehouse, your own dashboard — can consume your data without depending on the console's user session.

It is not a mirror of everything the console does: it is the surface that commits to not breaking without opening a new version (/v2).

Operations

Operation Method and path Required scope
Vendors GET /v1/vendors, GET /v1/vendors/{id} supply_risk:read
Alerts GET /v1/alerts, GET /v1/alerts/{id} supply_risk:read
Acknowledge an alert POST /v1/alerts/{id}/acknowledge alerts:write
Resolve an alert POST /v1/alerts/{id}/resolve alerts:write
Risks GET /v1/risks, GET /v1/risks/{id} supply_risk:read
Compliance controls GET /v1/compliance/controls?framework=… compliance.<framework>:read
Framework posture GET /v1/compliance/frameworks/{framework} compliance.<framework>:read
Evidence GET /v1/evidence, GET /v1/evidence/{id} evidence:read
Endpoints GET /v1/endpoints endpoints:read
Reports GET /v1/reports, GET /v1/reports/{id}, GET /v1/reports/{id}/download (PDF or XLSX file) reports:read
Changes GET /v1/changes (change-management register; served once at least one compliance framework is activated for the tenant) changes:read
Incidents GET /v1/incidents, GET /v1/incidents/{id} (incident register with its regulatory notification deadlines) incidents:read
AI systems GET /v1/ai-systems, GET /v1/ai-systems/{id} (register of AI systems) ai_systems:read
Who am I GET /v1/me none (any valid credential)
Portfolio tenants GET /v1/portfolio/tenants (MSSP portfolio key only) portfolio:read
OpenAPI document GET /v1/openapi.json none

Every other operation is a GET. Any method a path does not serve returns 405 Method Not Allowed, with Allow naming the one it does. The only writes in /v1 are the two alert operations above, under the separate alerts:write scope (see Acknowledge and resolve alerts), and POST /v1/act/proposals, available only to OAuth tokens of the MCP server with the act:propose scope, which records a proposal that a person in your organisation approves in the console.

Common response shape

Pagination — every collection accepts page (starting at 1) and per_page (1–200, default 50), and returns:

{
  "data": [ /* … */ ],
  "pagination": { "page": 1, "per_page": 50, "total": 213, "total_pages": 5 }
}

Errors — always the same envelope:

{ "error": { "code": "not_found", "message": "…", "request_id": "…", "details": {} } }

See the full vocabulary in Errors.

Next step

Downloads

  • Postman collection (v2.1): one request per operation. Import it into Postman and set the collection variable api_key to your credential; base_url points at https://api.hodeishield.com. It contains no key.
  • Raw OpenAPI 3.1 document: GET https://api.hodeishield.com/v1/openapi.json (no authentication; see OpenAPI specification).