Knowledge Hub

Source Intelligence Core API Reference

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/v1

Protocol: 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_TOKEN

Rate 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:#ffff99

Authentication

Bearer Token

All requests require an Authorization header with a bearer token:

curl -H "Authorization: Bearer token_abc123xyz..." \  https://intelligence.cleanstart.com/api/v1/vulnerabilities

Token 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
`read:vulnerabilities`	Vulnerability queries and details
`read:advisories`	Advisory queries and details
`read:packages`	Package metadata and versioning
`read:epss`	EPSS scores and rankings
`read:all`	All read operations (default)
`write:advisories`	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
`data`	object/array/null	Response payload. Array for list endpoints, object for detail endpoints, null for errors.
`meta`	object	Request metadata including correlation ID, timestamp, API version.
`errors`	array	Error objects with `code` and `message` fields. Empty array on success.

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
`INVALID_TOKEN`	401	Authentication token missing or invalid
`FORBIDDEN`	403	Token lacks required scope for operation
`RESOURCE_NOT_FOUND`	404	Requested resource does not exist
`INVALID_PARAMETER`	400	Query parameter or request body format error
`RATE_LIMIT_EXCEEDED`	429	Request rate limit exceeded
`INTERNAL_ERROR`	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=50

Response 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_a7f9e2c1

Offset-Based Pagination

Alternative approach using offset and limit:

GET /api/v1/vulnerabilities?limit=50&offset=100

Query Parameters:

Parameter	Type	Default	Max	Description
`limit`	integer	20	500	Results per page
`offset`	integer	0	—	Starting record index
`cursor`	string	—	—	Pagination cursor from previous response

Vulnerability Endpoints

List Vulnerabilities

Search and list vulnerabilities with filtering, sorting, and pagination.

Request:

GET /api/v1/vulnerabilities

Query Parameters:

Parameter	Type	Description	Example
`ecosystem`	string	Package ecosystem filter (npm, pip, maven, etc.)	`npm`
`severity`	string	Filter by severity: critical, high, medium, low, info	`critical`
`cve_id`	string	Exact CVE ID match	`CVE-2024-1234`
`published_after`	date	Published after date (ISO 8601)	`2024-01-01`
`published_before`	date	Published before date (ISO 8601)	`2024-12-31`
`affected_package`	string	Filter by affected package name	`lodash`
`sort_by`	string	Sort field: published_date, severity, cvss_score	`published_date`
`sort_order`	string	asc or desc	`desc`
`limit`	integer	Results per page (max 500)	`50`
`cursor`	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
`cve_id`	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}/packages

Path Parameters:

Parameter	Type	Description
`cve_id`	string	CVE identifier

Query Parameters:

Parameter	Type	Description
`ecosystem`	string	Filter by ecosystem (npm, pip, maven, etc.)
`limit`	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}/timeline

Path Parameters:

Parameter	Type	Description
`cve_id`	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/advisories

Query Parameters:

Parameter	Type	Description	Example
`ecosystem`	string	Package ecosystem filter	`npm`
`severity`	string	critical, high, medium, low, info	`high`
`affected_package`	string	Package name filter	`express`
`published_after`	date	Published after date (ISO 8601)	`2024-01-01`
`sort_by`	string	published_date, severity	`published_date`
`limit`	integer	Results per page (max 500)	`50`
`cursor`	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
`id`	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/affected

Request 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
`ecosystem`	string	Package ecosystem (npm, pip, maven, nuget, etc.)
`name`	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}/versions

Path Parameters:

Parameter	Type	Description
`ecosystem`	string	Package ecosystem
`name`	string	Package name (URL-encoded)

Query Parameters:

Parameter	Type	Description
`limit`	integer	Results per page (max 500)
`cursor`	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}/dependencies

Path Parameters:

Parameter	Type	Description
`ecosystem`	string	Package ecosystem
`name`	string	Package name (URL-encoded)

Query Parameters:

Parameter	Type	Description
`version`	string	Package version (defaults to latest)
`depth`	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/correlations

Query Parameters:

Parameter	Type	Description
`source1_type`	string	First source type: vulnerability, package, repository
`source1_id`	string	First source identifier
`source2_type`	string	Second source type
`source2_id`	string	Second source identifier
`min_confidence`	float	Minimum confidence threshold (0.0-1.0)
`limit`	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
`id`	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/universal

Query Parameters:

Parameter	Type	Description	Example
`query`	string	Search term (CVE ID, package name, etc.)	`CVE-2024-1234`
`resource_types`	string	Comma-separated filter: vulnerabilities, advisories, packages	`vulnerabilities,packages`
`limit`	integer	Results per page (max 500)	`50`

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/batch

Request 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
`cve_id`	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/top

Query Parameters:

Parameter	Type	Description
`limit`	integer	Results per page (max 500, default 50)
`min_score`	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
`X-RateLimit-Limit`	1000	Requests allowed per minute
`X-RateLimit-Remaining`	987	Requests remaining in current window
`X-RateLimit-Reset`	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: 60

Wait 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-01

Returns 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=desc

Available 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	`2026-03-22`
Timestamp	`2026-03-22T14:32:18Z`
Duration	`P30D` (30 days)

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 seconds

Versioning 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 GMT

Update 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/batch

Example: 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/express

Client Libraries

CleanStart provides official client libraries for common programming languages:

Language	Repository	Package
Python	github.com/cleanstart/python-intelligence-api	`pip install cleanstart-intelligence`
JavaScript	github.com/cleanstart/js-intelligence-api	`npm install @cleanstart/intelligence`
Go	github.com/cleanstart/go-intelligence-api	`go get 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.