DarkRisk API · v1

API reference

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.

Base URLhttps://api.darkrisk.io

curl https://api.darkrisk.io/v1/api/vendors \
  -H "Authorization: Bearer dr_live_your_api_key"

Getting started

Your first request

Create a key

In the dashboard, open Dashboard → API and generate a key. The secret is shown once — store it securely.

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.

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.

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
`limit`optional	integer	Page size, 1–500. Default 200.
`offset`optional	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
`severity`optional	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
`severity`optional	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
            }
          ]
        }
      ]
    }
  ]
}

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.

Ready to build?

Generate a key and make your first call in under a minute.

Create an API key ↗