Skip to main content

Your First API Call

This guide walks you through making your first API call to CyberSecFeed v1.5, understanding the response structure, and tracking your credit usage.

Before You Begin​

Make sure you have:

  • Your API key (see Authentication Guide)
  • A tool to make HTTP requests (curl, Postman, or any programming language)
  • Understanding of the credit system (endpoints cost 0-35 credits)

Understanding Credits (v1.5)​

CyberSecFeed uses a transparent credit system where different endpoints consume credits based on computational cost:

  • Health checks: 0 credits (free)
  • Basic searches: 1 credit
  • Single CVE details: 5 credits
  • Enterprise batch: 35 credits (up to 50 CVEs, 86% savings)

Check Your Credit Usage​

Before making API calls, you can check your current credit usage:

curl -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/usage

Response:

{
	"data": {
		"usage": {
			"plan": "CyberSecFeed Pro",
			"credits_used": 1234,
			"credits_limit": 200000,
			"credits_remaining": 198766,
			"reset_at": "2024-02-01T00:00:00Z",
			"percentage_used": 0.62
		}
	}
}

Making Your First Request​

Let's start with a simple CVE lookup. This example retrieves details for a specific CVE.

Using cURL​

curl -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001

Using Python​

import requests

api_key = "your-api-key-here"
cve_id = "CVE-2024-0001"

response = requests.get(
    f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
    headers={"X-API-Key": api_key}
)

print(response.json())

Using JavaScript​

const apiKey = 'your-api-key-here';
const cveId = 'CVE-2024-0001';

fetch(`https://api.cybersecfeed.com/api/v1/cve/${cveId}`, {
	headers: {
		'X-API-Key': apiKey,
	},
})
	.then((response) => response.json())
	.then((data) => console.log(data));

Understanding the Response​

A successful response will look like this:

{
	"data": {
		"cve": {
			"id": "CVE-2024-0001",
			"sourceIdentifier": "[email protected]",
			"published": "2024-01-15T10:00:00Z",
			"lastModified": "2024-01-16T14:30:00Z",
			"description": "A vulnerability in Example Software allows remote attackers...",
			"cvss": {
				"version": "3.1",
				"vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N",
				"baseScore": 9.1,
				"baseSeverity": "CRITICAL"
			},
			"cpe": [
				{
					"criteria": "cpe:2.3:a:example:software:1.0:*:*:*:*:*:*:*",
					"vulnerable": true
				}
			],
			"references": [
				{
					"url": "https://example.com/security/advisory-001",
					"source": "[email protected]"
				}
			],
			"kev": {
				"dateAdded": "2024-01-20",
				"vendorProject": "Example Corp",
				"product": "Example Software",
				"vulnerabilityName": "Example Software Remote Code Execution",
				"requiredAction": "Apply patch version 1.1 immediately",
				"knownRansomware": false
			},
			"epss": {
				"score": 0.97234,
				"percentile": 0.99,
				"date": "2024-01-25"
			}
		}
	},
	"meta": {
		"timestamp": "2024-01-25T12:00:00Z",
		"version": "v1.5",
		"correlationId": "req-12345"
	}
}

Response Structure Explained​

The data Object​

Contains the actual CVE information:

  • id: The CVE identifier
  • published: When the CVE was first published
  • lastModified: Most recent update timestamp
  • description: Detailed vulnerability description
  • cvss: CVSS scoring information
    • baseScore: Numeric score (0.0-10.0)
    • baseSeverity: LOW, MEDIUM, HIGH, or CRITICAL
  • cpe: Affected products/versions
  • references: Links to advisories and patches
  • kev: Known Exploited Vulnerability data (if applicable)
  • epss: Exploit Prediction score (if available)

The meta Object​

Contains request metadata:

  • timestamp: When the response was generated
  • version: API version
  • correlationId: Unique request ID for troubleshooting

Interpreting Enrichment Data​

KEV (Known Exploited Vulnerabilities)​

If the kev field is present, this CVE is actively being exploited in the wild. Pay special attention to:

  • dateAdded: When CISA confirmed exploitation
  • requiredAction: What you should do
  • knownRansomware: Associated with ransomware attacks

EPSS (Exploit Prediction Scoring System)​

The epss field provides predictive intelligence:

  • score: Probability of exploitation (0.0-1.0)
  • percentile: How this CVE ranks against all others
  • A score of 0.97 means 97% chance of exploitation in the next 30 days

Common Response Scenarios​

CVE Not Found​

{
	"error": {
		"code": "CVE_NOT_FOUND",
		"message": "CVE not found",
		"details": {
			"cveId": "CVE-9999-99999"
		}
	},
	"meta": {
		"timestamp": "2024-01-25T12:00:00Z",
		"version": "v1.5",
		"correlationId": "req-12345"
	}
}

Invalid API Key​

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Invalid or missing API key"
	},
	"meta": {
		"timestamp": "2024-01-25T12:00:00Z",
		"version": "v1.5",
		"correlationId": "req-12345"
	}
}

Try These v1.5 Examples​

1. Check the API Health (0 credits)​

curl -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/ping

2. Search for Critical CVEs with v1.5 Named Severity (1 credit)​

# v1.5 optimized - faster than legacy severity_min
curl -H "X-API-Key: your-api-key-here" \
     "https://api.cybersecfeed.com/api/v1/cves?severity=critical&limit=5"

3. Get Platform Statistics (0.5 credits)​

curl -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/stats

4. v1.5 Advanced Sorting with Field Selection (1 credit)​

# Fast critical vulnerability monitoring with 85% payload reduction
curl -H "X-API-Key: your-api-key-here" \
     "https://api.cybersecfeed.com/api/v1/cves?severity=critical&sort=severity_desc&fields=cve_id,severity,kev,epss&limit=10"

5. Enhanced Exploit Filtering (v1.5 Feature - 1 credit)​

# CVEs with confirmed exploits - no enrichment parameter needed in v1.5
curl -H "X-API-Key: your-api-key-here" \
     "https://api.cybersecfeed.com/api/v1/cves?exploit=true&severity=critical,high&sort=epss_desc&limit=5"

6. Enterprise Batch Operation (35 credits - 86% savings!)​

# Process multiple CVEs in one request
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{"cve_ids":["CVE-2024-0001","CVE-2024-0002","CVE-2021-44228"],"fields":["cve_id","severity","kev","epss"]}' \
     https://api.cybersecfeed.com/api/v1/cve/batch

Credit Tracking Best Practices​

Monitor Your Usage​

Always track your credit consumption to optimize costs:

import requests

def check_credits_and_make_call(api_key, endpoint_url):
    # Check credits first
    usage_response = requests.get(
        "https://api.cybersecfeed.com/api/v1/usage",
        headers={"X-API-Key": api_key}
    )

    usage_data = usage_response.json()['data']['usage']
    print(f"Credits remaining: {usage_data['credits_remaining']}")

    # Make your API call
    if usage_data['credits_remaining'] > 5:  # Ensure you have enough credits
        response = requests.get(endpoint_url, headers={"X-API-Key": api_key})
        return response.json()
    else:
        print("Insufficient credits remaining")
        return None

Credit Optimization Tips​

  • Use enterprise batch operations for bulk processing (86% savings)
  • Leverage field selection to reduce payload and processing costs
  • Choose the right endpoint - check if you need full detail or basic data
  • Monitor usage patterns to plan subscription tier upgrades

Next Steps​

Now that you've made your first v1.5 API call:

  1. Parameters Reference - Learn v1.5 advanced sorting and severity levels
  2. Enterprise Batch Operations - Achieve 86% cost savings
  3. Performance Optimization - Field selection and caching strategies
  4. Pricing & Plans - Understand credit allocation and plan upgrades

Troubleshooting​

If your API call isn't working:

  1. Verify your API key is correct and active
  2. Check the URL - ensure you're using https://api.cybersecfeed.com
  3. Confirm the CVE ID format (e.g., CVE-2024-0001)
  4. Review error messages in the response
  5. See our Troubleshooting Guide for more help