Response Format

Most BreachSpider API responses follow the consistent envelope structure below (an api block, data, and optional meta, pagination, and _links).

A few endpoints currently return a simpler, non-enveloped shape: the vendor and protocol CVE listings (/cves/vendor/{slug}, /cves/protocol/{name}), the stats endpoints (/cves/stats/summary, /cves/stats/dashboard), the catalog endpoints, and the API key create response. Enveloping these is planned. Treat the envelope as the norm and check the specific endpoint page for exceptions.

Success Response (Single Resource)

{
  "api": {
    "version": "1.0.0",
    "request_id": "bs-req-75d2ecafebce",
    "timestamp": "2026-06-07T13:34:43.930705Z",
    "processing_ms": 21
  },
  "data": {
    "cve_id": "CVE-2025-32433",
    "bsid": "BS-2025-254014-C"
  },
  "meta": {
    "enrichment_version": "2.1",
    "sage_model": "SAGE-v1",
    "source": "breachspider-enriched"
  },
  "_links": {
    "self": "/api/v1/cves/CVE-2025-32433",
    "pdf": "/api/v1/ics-cve/CVE-2025-32433/pdf",
    "html": "https://breachspider.com/ics-cve/CVE-2025-32433"
  }
}

Success Response (Collection)

{
  "api": {
    "version": "1.0.0",
    "request_id": "bs-req-1902da167d3f",
    "timestamp": "2026-06-07T13:34:44.470706Z",
    "processing_ms": 491
  },
  "data": [],
  "pagination": {
    "total": 47000,
    "page": 1,
    "per_page": 20,
    "pages": 2350,
    "has_next": true,
    "has_prev": false,
    "count": 20
  },
  "filters_applied": {
    "severity": "CRITICAL"
  },
  "meta": {
    "corpus_size": 360581,
    "data_freshness": "live"
  },
  "_links": {
    "self": "/api/v1/cves?page=1&limit=20",
    "next": "/api/v1/cves?page=2&limit=20",
    "prev": null,
    "first": "/api/v1/cves?page=1&limit=20",
    "last": "/api/v1/cves?page=2350&limit=20"
  }
}

Error Response

{
  "api": {
    "version": "1.0.0",
    "request_id": "bs-req-1d166b132017",
    "timestamp": "2026-06-07T13:34:44.528718Z"
  },
  "error": {
    "code": "NOT_FOUND",
    "message": "CVE not found.",
    "detail": {
      "resource": "CVE",
      "identifier": "CVE-9999-99999"
    }
  }
}

Response Headers

Every response includes:

Timestamps

Envelope timestamps (api.timestamp) are ISO 8601 UTC with a Z suffix, for example 2026-06-07T13:34:43.930705Z. Timestamps inside data objects (published_at, modified_at, and so on) are ISO 8601 with an explicit UTC offset, for example 2025-04-16T22:15:14+00:00.