Skip to main content

API Overview

CXRay provides a comprehensive REST API for integrating security scanning into your applications and workflows.

Base URL​

Production: https://api.cxray.io/v1
Development: https://api-dev.cxray.io/v1

Authentication​

All API requests require authentication using an API key. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key​

  1. Log in to CXRay Dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
  4. Copy and securely store your API key

Rate Limits​

TierRequests per minuteRequests per hour
Free601,000
Pro30010,000
EnterpriseUnlimitedUnlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

API Endpoints​

Scans​

  • POST /scans - Initiate a new scan
  • GET /scans/{scanId} - Get scan status and results
  • GET /scans - List all scans
  • DELETE /scans/{scanId} - Delete a scan

Vulnerabilities​

  • GET /vulnerabilities - Search vulnerabilities
  • GET /vulnerabilities/{cveId} - Get CVE details
  • POST /vulnerabilities/check - Check component against CVE database

SBOM​

  • POST /sbom/generate - Generate SBOM
  • POST /sbom/analyze - Analyze existing SBOM
  • GET /sbom/{sbomId} - Retrieve SBOM

Projects​

  • GET /projects - List projects
  • POST /projects - Create project
  • GET /projects/{projectId} - Get project details
  • PUT /projects/{projectId} - Update project
  • DELETE /projects/{projectId} - Delete project

Quick Start Example​

cURL​

# Initiate a scan
curl -X POST https://api.cxray.io/v1/scans \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": ["cve", "sbom"],
"target": "https://github.com/user/repo",
"branch": "main"
}'

# Get scan results
curl https://api.cxray.io/v1/scans/scan_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"

JavaScript​

const axios = require('axios');

const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.cxray.io/v1';

async function scanRepository() {
const response = await axios.post(
`${BASE_URL}/scans`,
{
type: ['cve', 'cce', 'sbom'],
target: 'https://github.com/user/repo',
branch: 'main'
},
{
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
}
);

return response.data;
}

scanRepository()
.then(data => console.log('Scan initiated:', data.scanId))
.catch(error => console.error('Error:', error));

Python​

import requests

API_KEY = 'your-api-key'
BASE_URL = 'https://api.cxray.io/v1'

headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}

payload = {
'type': ['cve', 'sbom'],
'target': 'https://github.com/user/repo',
'branch': 'main'
}

response = requests.post(
f'{BASE_URL}/scans',
json=payload,
headers=headers
)

scan_data = response.json()
print(f"Scan ID: {scan_data['scanId']}")

Response Format​

All API responses follow this structure:

Success Response​

{
"status": "success",
"data": {
// Response data
},
"meta": {
"timestamp": "2023-01-15T10:30:00Z",
"version": "1.0"
}
}

Error Response​

{
"status": "error",
"error": {
"code": "INVALID_REQUEST",
"message": "Invalid scan type specified",
"details": {
"field": "type",
"value": "invalid_type"
}
},
"meta": {
"timestamp": "2023-01-15T10:30:00Z",
"version": "1.0"
}
}

Error Codes​

CodeHTTP StatusDescription
INVALID_REQUEST400Invalid request parameters
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
RATE_LIMIT_EXCEEDED429Rate limit exceeded
INTERNAL_ERROR500Internal server error

Webhooks​

Configure webhooks to receive real-time notifications:

POST /webhooks
{
"url": "https://your-app.com/webhook",
"events": ["scan.completed", "vulnerability.found"],
"secret": "your-webhook-secret"
}

Supported events:

  • scan.started
  • scan.completed
  • scan.failed
  • vulnerability.found
  • sbom.generated

SDK Libraries​

Official SDKs are available for:

  • JavaScript/TypeScript: npm install @cxray/sdk
  • Python: pip install cxray-sdk
  • Go: go get github.com/cxray/go-sdk
  • Java: Maven/Gradle coordinates available

Next Steps​