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:
See the full vocabulary in Errors.
Next step¶
- Authentication and API keys
- Full reference of the operations
- Raw OpenAPI specification
- Versioning and deprecation
- Deprecation policy
- Rate limits
- Troubleshooting
Downloads¶
- Postman collection (v2.1):
one request per operation. Import it into Postman and set the collection variable
api_keyto your credential;base_urlpoints athttps://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).