Response Format

Every BreachSpider API response follows a consistent envelope structure. No endpoint returns a raw object or array directly.

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": 354520,
    "page": 1,
    "per_page": 20,
    "pages": 17726,
    "has_next": true,
    "has_prev": false,
    "count": 20
  },
  "filters_applied": {
    "severity": "CRITICAL"
  },
  "meta": {
    "corpus_size": 354520,
    "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=17726&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

All timestamps are ISO 8601 UTC format: 2026-06-07T13:34:43.930705Z