Internal API — The Source Intelligence Core API is used internally within CleanStart infrastructure. It is not a public-facing API. Externally, the system is referred to as CleanStart Verified Source.
API at a Glance
Base URL:
https://intelligence.cleanstart.com/api/v1Protocol: HTTP/1.1 and HTTP/2 Content-Type: application/json Response Format: JSON envelope with data, meta, and errors sections Access: Internal use only (not publicly accessible)
Authentication: Bearer token in Authorization header
Authorization: Bearer YOUR_API_TOKENRate Limits: Per-minute: 1,000 requests, Per-hour: 10,000 requests, Per-day: 100,000 requests, and Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
API Version: v1 Deprecation Policy: 12-month notice before removal of endpoint versions
The following diagram illustrates the Source Intelligence API endpoint tree and request flow:
graph TD A["Source Intelligence<br/>API v1<br/>Base URL"] -->|Root| B["https://intelligence<br/>.cleanstart.com<br/>/api/v1"] B -->|GET| C["/vulnerabilities<br/>Query CVE database"] B -->|GET| D["/advisories<br/>Retrieve advisories"] B -->|GET| E["/packages<br/>Package metadata"] B -->|GET| F["/epss<br/>EPSS scores"] C -->|Filter| C1["?cve=CVE-2024-"] C -->|Filter| C2["?severity=critical"] C -->|Result| C3["Vulnerability<br/>Details"] D -->|Filter| D1["?package=openssl"] D -->|Filter| D2["?date_from=2024-01"] D -->|Result| D3["Advisory<br/>Details"] E -->|Query| E1["?name=flask"] E -->|Query| E2["?version=3.0.0"] E -->|Result| E3["Package<br/>Info + CVEs"] F -->|Rank| F1["?limit=10"] F -->|Rank| F2["?sort=epss_score"] F -->|Result| F3["EPSS Scores<br/>Risk Ranking"] C3 -->|Response| G["JSON Envelope<br/>data<br/>meta<br/>errors"] D3 -->|Response| G E3 -->|Response| G F3 -->|Response| G G -->|Auth| H["Bearer Token<br/>Authorization"] H -->|Rate Limit| I["1000 req/min<br/>10000 req/hr"] I -->|Scope| J["read:vulnerabilities<br/>read:advisories<br/>read:packages"] J -->|Return| K["JSON Response<br/>request_id<br/>timestamp<br/>data/errors"] style A fill:#99ccff style B fill:#99ccff style C fill:#ccffcc style D fill:#ccffcc style E fill:#ccffcc style F fill:#ccffcc style K fill:#ffff99Authentication
Bearer Token
All requests require an Authorization header with a bearer token:
curl -H "Authorization: Bearer token_abc123xyz..." \ https://intelligence.cleanstart.com/api/v1/vulnerabilitiesToken format: alphanumeric strings issued by CleanStart administrative dashboard. Tokens do not expire but can be revoked.
Token Scopes
Tokens support the following scopes:
Scope | Resources |
|---|---|
| Vulnerability queries and details |
| Advisory queries and details |
| Package metadata and versioning |
| EPSS scores and rankings |
| All read operations (default) |
| Advisory creation and updates (admin only) |
Request a scoped token from your account administrator.
Token Validation
Invalid tokens return 401 Unauthorized:
{ "data": null, "meta": {}, "errors": [ { "code": "INVALID_TOKEN", "message": "Token not recognized or revoked" } ]}Common Response Format
All responses follow a consistent JSON envelope structure:
{ "data": { }, "meta": { "request_id": "req_7a8c4d2e", "timestamp": "2026-03-22T14:32:18Z", "version": "1.0" }, "errors": [ ]}Response Fields:
Field | Type | Description |
|---|---|---|
| object/array/null | Response payload. Array for list endpoints, object for detail endpoints, null for errors. |
| object | Request metadata including correlation ID, timestamp, API version. |
| array | Error objects with |
Error Responses
All errors include an error code and message:
{ "data": null, "meta": { "request_id": "req_xyz", "timestamp": "2026-03-22T14:35:00Z" }, "errors": [ { "code": "RESOURCE_NOT_FOUND", "message": "CVE-2024-1234 not found in database" } ]}Common Error Codes:
Code | HTTP Status | Meaning |
|---|---|---|
| 401 | Authentication token missing or invalid |
| 403 | Token lacks required scope for operation |
| 404 | Requested resource does not exist |
| 400 | Query parameter or request body format error |
| 429 | Request rate limit exceeded |
| 500 | Server-side error |
Pagination
List endpoints support cursor-based and offset-based pagination.
Cursor-Based Pagination (Recommended)
Request the first page:
GET /api/v1/vulnerabilities?limit=50Response includes next_cursor for fetching the next page:
{ "data": [ { "cve_id": "CVE-2024-0001" }, ... ], "meta": { "pagination": { "limit": 50, "count": 50, "has_next": true, "next_cursor": "cur_a7f9e2c1" } }, "errors": []}Fetch subsequent pages:
GET /api/v1/vulnerabilities?limit=50&cursor=cur_a7f9e2c1Offset-Based Pagination
Alternative approach using offset and limit:
GET /api/v1/vulnerabilities?limit=50&offset=100Query Parameters:
Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| integer | 20 | 500 | Results per page |
| integer | 0 | — | Starting record index |
| string | — | — | Pagination cursor from previous response |
Vulnerability Endpoints
List Vulnerabilities
Search and list vulnerabilities with filtering, sorting, and pagination.
Request:
GET /api/v1/vulnerabilitiesQuery Parameters:
Parameter | Type | Description | Example |
|---|---|---|---|
| string | Package ecosystem filter (npm, pip, maven, etc.) |
|
| string | Filter by severity: critical, high, medium, low, info |
|
| string | Exact CVE ID match |
|
| date | Published after date (ISO 8601) |
|
| date | Published before date (ISO 8601) |
|
| string | Filter by affected package name |
|
| string | Sort field: published_date, severity, cvss_score |
|
| string | asc or desc |
|
| integer | Results per page (max 500) |
|
| string | Pagination cursor | — |
Response Example:
{ "data": [ { "cve_id": "CVE-2024-0001", "severity": "critical", "cvss_score": 9.8, "published_date": "2024-01-15T08:30:00Z", "summary": "Remote code execution in package X" } ], "meta": { "pagination": { "limit": 50, "count": 50, "has_next": true, "next_cursor": "cur_a7f9e2c1" } }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid query parameters |
401 | Missing or invalid authentication |
429 | Rate limit exceeded |
Get Vulnerability Detail
Retrieve full details for a specific vulnerability.
Request:
GET /api/v1/vulnerabilities/{cve_id}Path Parameters:
Parameter | Type | Description |
|---|---|---|
| string | CVE identifier (e.g., CVE-2024-1234) |
Response Example:
{ "data": { "cve_id": "CVE-2024-1234", "severity": "critical", "cvss_score": 9.8, "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", "summary": "Remote code execution vulnerability", "description": "A critical vulnerability in library X allows remote attackers...", "published_date": "2024-01-15T08:30:00Z", "affected_packages": [ { "ecosystem": "npm", "name": "package-x", "affected_versions": "< 2.5.0" } ], "references": [ "https://nvd.nist.gov/vuln/detail/CVE-2024-1234" ] }, "meta": { "request_id": "req_xyz" }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Vulnerability not found |
401 | Authentication required |
Get Affected Packages
Retrieve packages affected by a vulnerability.
Request:
GET /api/v1/vulnerabilities/{cve_id}/packagesPath Parameters:
Parameter | Type | Description |
|---|---|---|
| string | CVE identifier |
Query Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Filter by ecosystem (npm, pip, maven, etc.) |
| integer | Results per page (max 500) |
Response Example:
{ "data": [ { "ecosystem": "npm", "name": "package-x", "affected_versions": "< 2.5.0", "patched_versions": ">= 2.5.0", "first_patched_version": "2.5.0" } ], "meta": { "pagination": { "count": 3 } }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Vulnerability not found |
Get Vulnerability Timeline
Retrieve fix and patch timeline for a vulnerability.
Request:
GET /api/v1/vulnerabilities/{cve_id}/timelinePath Parameters:
Parameter | Type | Description |
|---|---|---|
| string | CVE identifier |
Response Example:
{ "data": { "cve_id": "CVE-2024-1234", "discovered": "2024-01-10T12:00:00Z", "published": "2024-01-15T08:30:00Z", "patches": [ { "version": "2.5.0", "released": "2024-01-20T14:00:00Z", "ecosystem": "npm", "status": "available" } ] }, "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Vulnerability not found |
Advisory Endpoints
List Advisories
Query CleanStart Security Advisories in OSV format.
Request:
GET /api/v1/advisoriesQuery Parameters:
Parameter | Type | Description | Example |
|---|---|---|---|
| string | Package ecosystem filter |
|
| string | critical, high, medium, low, info |
|
| string | Package name filter |
|
| date | Published after date (ISO 8601) |
|
| string | published_date, severity |
|
| integer | Results per page (max 500) |
|
| string | Pagination cursor | — |
Response Example:
{ "data": [ { "id": "GHSA-xxxx-yyyy-zzzz", "severity": "high", "affected": [ { "package": { "ecosystem": "npm", "name": "express" }, "ranges": [ { "type": "SEMVER", "events": [ { "introduced": "0", "fixed": "4.19.0" } ] } ] } ], "published": "2024-02-10T09:15:00Z", "summary": "Security advisory summary" } ], "meta": { "pagination": { "count": 25 } }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid query parameters |
401 | Authentication required |
Get Advisory Detail
Retrieve full details for a specific advisory.
Request:
GET /api/v1/advisories/{id}Path Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Advisory ID (GHSA or CleanStart ID) |
Response Example:
{ "data": { "id": "GHSA-xxxx-yyyy-zzzz", "severity": "high", "summary": "Express session vulnerability", "description": "Detailed description of the vulnerability", "affected": [ { "package": { "ecosystem": "npm", "name": "express" }, "ranges": [ ] } ], "references": [ "https://github.com/advisories/GHSA-xxxx-yyyy-zzzz" ], "published": "2024-02-10T09:15:00Z", "modified": "2024-02-15T10:30:00Z" }, "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Advisory not found |
Check Affected Packages
Determine if provided packages are affected by any known advisories.
Request:
POST /api/v1/advisories/affectedRequest Body:
{ "packages": [ { "ecosystem": "npm", "name": "express", "version": "4.18.0" }, { "ecosystem": "npm", "name": "lodash", "version": "4.17.20" } ]}Response Example:
{ "data": [ { "package": { "ecosystem": "npm", "name": "express", "version": "4.18.0" }, "affected_advisories": [ { "id": "GHSA-xxxx-yyyy-zzzz", "severity": "high", "fixed_version": "4.19.0" } ] }, { "package": { "ecosystem": "npm", "name": "lodash", "version": "4.17.20" }, "affected_advisories": [] } ], "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid request body |
401 | Authentication required |
Package Endpoints
Get Package Security Posture
Retrieve security posture and risk summary for a package.
Request:
GET /api/v1/packages/{ecosystem}/{name}Path Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Package ecosystem (npm, pip, maven, nuget, etc.) |
| string | Package name (URL-encoded) |
Response Example:
{ "data": { "ecosystem": "npm", "name": "express", "latest_version": "4.18.2", "total_releases": 187, "vulnerabilities": { "critical": 0, "high": 2, "medium": 5, "low": 8 }, "advisories": 7, "last_updated": "2024-03-20T15:45:00Z" }, "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Package not found |
Get Package Version History
Retrieve version history with fix and vulnerability status.
Request:
GET /api/v1/packages/{ecosystem}/{name}/versionsPath Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Package ecosystem |
| string | Package name (URL-encoded) |
Query Parameters:
Parameter | Type | Description |
|---|---|---|
| integer | Results per page (max 500) |
| string | Pagination cursor |
Response Example:
{ "data": [ { "version": "4.18.2", "released": "2024-03-15T10:00:00Z", "vulnerabilities": 0, "advisories": 0 }, { "version": "4.18.1", "released": "2024-02-28T08:30:00Z", "vulnerabilities": 2, "advisories": 2 } ], "meta": { "pagination": { "count": 50 } }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Package not found |
Get Package Dependencies
Retrieve dependency graph for a package version.
Request:
GET /api/v1/packages/{ecosystem}/{name}/dependenciesPath Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Package ecosystem |
| string | Package name (URL-encoded) |
Query Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Package version (defaults to latest) |
| integer | Dependency graph depth (1-5, default 1) |
Response Example:
{ "data": { "ecosystem": "npm", "name": "express", "version": "4.18.2", "direct_dependencies": [ { "name": "body-parser", "ecosystem": "npm", "version": "1.20.2" } ], "transitive_dependencies": 45 }, "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Package or version not found |
Correlation Endpoints
List Correlations
Query cross-source correlations between vulnerabilities, packages, and repositories.
Request:
GET /api/v1/correlationsQuery Parameters:
Parameter | Type | Description |
|---|---|---|
| string | First source type: vulnerability, package, repository |
| string | First source identifier |
| string | Second source type |
| string | Second source identifier |
| float | Minimum confidence threshold (0.0-1.0) |
| integer | Results per page (max 500) |
Response Example:
{ "data": [ { "id": "cor_abc123", "source1": { "type": "vulnerability", "id": "CVE-2024-1234" }, "source2": { "type": "package", "id": "npm:express" }, "confidence": 0.95, "correlation_type": "affects" } ], "meta": { "pagination": { "count": 5 } }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid query parameters |
Get Correlation Detail
Retrieve full details for a specific correlation.
Request:
GET /api/v1/correlations/{id}Path Parameters:
Parameter | Type | Description |
|---|---|---|
| string | Correlation identifier |
Response Example:
{ "data": { "id": "cor_abc123", "source1": { "type": "vulnerability", "id": "CVE-2024-1234", "data": { } }, "source2": { "type": "package", "id": "npm:express", "data": { } }, "confidence": 0.95, "correlation_type": "affects", "created_at": "2024-02-01T12:00:00Z" }, "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | Correlation not found |
Search Endpoints
Universal Search
Perform unified search across vulnerabilities, advisories, packages, and repositories.
Request:
GET /api/v1/search/universalQuery Parameters:
Parameter | Type | Description | Example |
|---|---|---|---|
| string | Search term (CVE ID, package name, etc.) |
|
| string | Comma-separated filter: vulnerabilities, advisories, packages |
|
| integer | Results per page (max 500) |
|
Response Example:
{ "data": { "vulnerabilities": [ { "cve_id": "CVE-2024-1234", "severity": "critical", "summary": "..." } ], "packages": [ { "ecosystem": "npm", "name": "cve-2024", "latest_version": "1.0.0" } ] }, "meta": { "query": "CVE-2024" }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid search query |
Batch Vulnerability Check
Check multiple packages against all known vulnerabilities and advisories.
Request:
POST /api/v1/search/batchRequest Body:
{ "packages": [ { "ecosystem": "npm", "name": "express", "version": "4.18.0" }, { "ecosystem": "pip", "name": "django", "version": "3.2.0" } ]}Response Example:
{ "data": [ { "package": { "ecosystem": "npm", "name": "express", "version": "4.18.0" }, "vulnerabilities": [ { "cve_id": "CVE-2024-1234", "severity": "high" } ], "advisories": [ { "id": "GHSA-xxxx-yyyy-zzzz", "severity": "high" } ] }, { "package": { "ecosystem": "pip", "name": "django", "version": "3.2.0" }, "vulnerabilities": [], "advisories": [] } ], "meta": { "checked_packages": 2 }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid request body |
413 | Payload too large (max 1000 packages) |
EPSS Endpoints
Get EPSS Score
Retrieve Exploit Prediction Scoring System (EPSS) score for a vulnerability.
Request:
GET /api/v1/epss/{cve_id}Path Parameters:
Parameter | Type | Description |
|---|---|---|
| string | CVE identifier |
Response Example:
{ "data": { "cve_id": "CVE-2024-1234", "epss_score": 0.87, "percentile": 0.94, "published": "2024-02-10T08:00:00Z" }, "meta": {}, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
404 | EPSS score not available |
Get Top Exploited Vulnerabilities
Retrieve vulnerabilities with highest EPSS scores (active exploitation).
Request:
GET /api/v1/epss/topQuery Parameters:
Parameter | Type | Description |
|---|---|---|
| integer | Results per page (max 500, default 50) |
| float | Minimum EPSS score (0.0-1.0) |
Response Example:
{ "data": [ { "cve_id": "CVE-2024-0001", "epss_score": 0.98, "percentile": 0.99, "severity": "critical" }, { "cve_id": "CVE-2024-0002", "epss_score": 0.95, "percentile": 0.98, "severity": "critical" } ], "meta": { "pagination": { "count": 50 } }, "errors": []}HTTP Status Codes:
Code | Meaning |
|---|---|
200 | Success |
400 | Invalid query parameters |
HTTP Status Codes
Standard HTTP Response Codes:
Code | Name | Meaning |
|---|---|---|
200 | OK | Successful request |
201 | Created | Resource created successfully |
400 | Bad Request | Invalid parameters or request body |
401 | Unauthorized | Missing or invalid authentication token |
403 | Forbidden | Token lacks required scope |
404 | Not Found | Requested resource does not exist |
429 | Too Many Requests | Rate limit exceeded; retry after delay |
500 | Internal Server Error | Server-side error; contact support |
503 | Service Unavailable | Temporary service outage |
Rate Limiting
Requests are rate-limited per API token. Rate limit status is included in response headers.
Rate Limit Headers:
Header | Example | Meaning |
|---|---|---|
| 1000 | Requests allowed per minute |
| 987 | Requests remaining in current window |
| 1711185600 | Unix timestamp when limit resets |
When rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header:
Retry-After: 60Wait the specified number of seconds before retrying the request.
Filtering and Sorting
Filtering
Apply filters to list endpoints using query parameters. Multiple filters use AND logic:
GET /api/v1/vulnerabilities?ecosystem=npm&severity=critical&published_after=2024-01-01Returns vulnerabilities in npm ecosystem with critical severity published after January 1, 2024.
Sorting
Sort results by specified field and order:
GET /api/v1/vulnerabilities?sort_by=published_date&sort_order=descAvailable sort fields vary by endpoint. Check individual endpoint documentation for supported sort fields.
Date/Time Formats
All dates and timestamps use ISO 8601 format with UTC timezone:
Format | Example |
|---|---|
Date |
|
Timestamp |
|
Duration |
|
Data Types
Severity Levels
Vulnerability severity ratings follow CVSS definitions:
Level | CVSS Score Range |
|---|---|
critical | 9.0–10.0 |
high | 7.0–8.9 |
medium | 4.0–6.9 |
low | 0.1–3.9 |
info | 0.0 |
Ecosystems
Supported package ecosystems:
Ecosystem | Registry | Examples |
|---|---|---|
npm | Node Package Manager | express, lodash, react |
pip | Python Package Index | django, requests, numpy |
maven | Maven Central Repository | org.apache.struts, com.google.guava |
nuget | NuGet Gallery | Newtonsoft.Json, NUnit |
gem | RubyGems | rails, devise, bundler |
composer | Packagist | laravel/framework, symfony/console |
crates | Crates.io | tokio, serde, actix-web |
go | Go Modules | github.com/golang/protobuf |
Error Handling
Handle errors programmatically by checking response status codes and error codes:
# Example: Check for authentication errorcurl -i https://intelligence.cleanstart.com/api/v1/vulnerabilities # Response: 401 Unauthorized# {# "data": null,# "meta": {},# "errors": [# { "code": "INVALID_TOKEN", "message": "Token not recognized" }# ]# }Implement exponential backoff for transient errors (5xx responses):
Attempt 1: immediateAttempt 2: wait 1 secondAttempt 3: wait 2 secondsAttempt 4: wait 4 secondsAttempt 5: wait 8 secondsVersioning and Deprecation
The API follows semantic versioning. Breaking changes increment the major version. Non-breaking changes (new endpoints, fields, parameters) increment the minor version. Bug fixes increment the patch version.
Deprecated endpoints and parameters receive a 12-month notice before removal. Deprecation notices appear in response headers:
Deprecation: trueSunset: Mon, 20 Mar 2027 00:00:00 GMTUpdate client code to use replacement endpoints before the sunset date.
Examples
Example: Check Package for Vulnerabilities
curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "packages": [ { "ecosystem": "npm", "name": "express", "version": "4.18.0" } ] }' \ https://intelligence.cleanstart.com/api/v1/search/batchExample: Retrieve Top Exploited Vulnerabilities
curl -X GET \ -H "Authorization: Bearer YOUR_API_TOKEN" \ 'https://intelligence.cleanstart.com/api/v1/epss/top?limit=10&min_score=0.90'Example: Get Package Security Posture
curl -X GET \ -H "Authorization: Bearer YOUR_API_TOKEN" \ https://intelligence.cleanstart.com/api/v1/packages/npm/expressClient Libraries
CleanStart provides official client libraries for common programming languages:
Language | Repository | Package |
|---|---|---|
Python | github.com/cleanstart/python-intelligence-api |
|
JavaScript | github.com/cleanstart/js-intelligence-api |
|
Go | github.com/cleanstart/go-intelligence-api |
|
Java | github.com/cleanstart/java-intelligence-api | Maven Central |
.NET | github.com/cleanstart/dotnet-intelligence-api | NuGet |
Support and Feedback
Documentation: https://docs.cleanstart.com/intelligence Status Page: https://status.cleanstart.com Support Email: support@cleanstart.com GitHub Issues: github.com/cleanstart/intelligence-api/issues
Report bugs, request features, and ask questions through official support channels.