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​