Create a key
In the dashboard, open Dashboard → API and generate a key. The secret is shown once — store it securely.
API documentation · v1
Risk intelligence.
In your workflow.
Read your vendor scores, pull in-depth per-vendor reports, and surface every vendor carrying critical or high-severity findings — programmatically, over a simple, key-authenticated REST API.
01 / Getting started
Your first request
Send the key
Pass it on every request as a bearer token or an X-API-Key header.
Read your data
Every response is JSON, scoped to the organisation that owns the key.
02 / Authentication
API keys
All API requests are authenticated with an organisation API key that starts with dr_live_. Keys are secret — never expose them in browser code or public repositories. A leaked key can be revoked instantly from the dashboard.
Authorization header (recommended)
curl https://api.darkrisk.io/v1/api/vendors \
-H "Authorization: Bearer dr_live_your_api_key"X-API-Key header
curl https://api.darkrisk.io/v1/api/vendors \
-H "X-API-Key: dr_live_your_api_key"Usage is metered. Every authenticated call increments your key’s request counter, visible in Dashboard → API.
03 / Endpoints
Reference
Three read endpoints cover the full surface: list scores, drill into one vendor, and pull every vendor with critical or high findings. Click a row to expand it.
GET/v1/api/vendorsList all vendor scores
Returns every active vendor in your organisation with headline scores and critical/high finding counts, newest first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
limitoptional | integer | Page size, 1–500. Default 200. |
offsetoptional | integer | Rows to skip. Default 0. |
Request
curl "https://api.darkrisk.io/v1/api/vendors?limit=50" \
-H "Authorization: Bearer dr_live_your_api_key"Response 200
{
"vendors": [
{
"id": "vnd_9f2c",
"name": "Acme Corp",
"category": "Cloud",
"status": "Active",
"risk": "High",
"score": 62,
"averageScore": 68,
"worstScore": 41,
"domainCount": 4,
"redFlagCount": 3,
"criticalCount": 1,
"highCount": 2,
"lastScannedAt": "2026-08-21T09:14:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}GET/v1/api/vendors/{vendorId}Get one vendor in depth
Returns a single vendor with every tracked domain, its latest scan score/grade, and the findings for that scan. Filter which severities come back with severity.
Query parameters
| Parameter | Type | Description |
|---|---|---|
severityoptional | string | Comma-separated severities to include (critical, high, medium, low, info). Default: all. |
Request
curl "https://api.darkrisk.io/v1/api/vendors/vnd_9f2c?severity=critical,high" \
-H "Authorization: Bearer dr_live_your_api_key"Response 200
{
"vendor": {
"id": "vnd_9f2c",
"name": "Acme Corp",
"category": "Cloud",
"status": "Active",
"risk": "High",
"score": 62,
"averageScore": 68,
"worstScore": 41,
"domainCount": 4,
"redFlagCount": 3,
"website": "acme.com"
},
"domains": [
{
"id": "dom_1a2b",
"fqdn": "acme.com",
"score": 41,
"grade": "D",
"riskBand": "High",
"redFlagCount": 2,
"lastScannedAt": "2026-08-21T09:14:00.000Z",
"findings": [
{
"severity": "critical",
"message": "Expired TLS certificate on mail host",
"recommendation": "Renew and automate certificate rotation.",
"module": "tls_security",
"domain": "mail.acme.com",
"isRedFlag": true
}
]
}
]
}GET/v1/api/reports/criticalAll vendors with critical / high issues
A cross-portfolio report: every vendor carrying findings at the requested severities, grouped by vendor and domain. Defaults to critical,high.
Query parameters
| Parameter | Type | Description |
|---|---|---|
severityoptional | string | Comma-separated severities to include. Default: critical,high. |
Request
curl "https://api.darkrisk.io/v1/api/reports/critical" \
-H "Authorization: Bearer dr_live_your_api_key"Response 200
{
"severities": ["critical", "high"],
"vendorCount": 1,
"vendors": [
{
"vendorId": "vnd_9f2c",
"vendorName": "Acme Corp",
"category": "Cloud",
"criticalCount": 1,
"highCount": 2,
"domains": [
{
"fqdn": "acme.com",
"score": 41,
"grade": "D",
"riskBand": "High",
"lastScannedAt": "2026-08-21T09:14:00.000Z",
"findings": [
{
"severity": "critical",
"message": "Expired TLS certificate on mail host",
"recommendation": "Renew and automate certificate rotation.",
"module": "tls_security",
"isRedFlag": true
}
]
}
]
}
]
}04 / Errors & limits
Status codes
| Code | Meaning |
|---|---|
200 | Success — the response body contains your data. |
400 | Invalid query parameters (e.g. a bad limit or severity). |
401 | Missing, malformed, revoked, or expired API key. |
404 | The requested vendor does not exist in your organisation. |
429 | Rate limit exceeded — slow down and retry after a short pause. |
Error shape
{
"error": "Unauthorized",
"message": "Invalid or revoked API key."
}Rate limits
Requests are rate limited per source. On a 429, the JSON body includes a retryAfterSec hint. Build exponential backoff into automated clients and cache responses where you can.