API Overview

CRA Evidence provides a REST API for programmatic access to all platform features. You can use it to automate SBOM uploads from CI/CD pipelines, integrate vulnerability data into your tools, or build custom workflows.

Base URL

All API requests go to:

https://api.craevidence.com/api/v1

Both api.craevidence.com and app.craevidence.com resolve to the same service, but api.craevidence.com is the canonical API endpoint. Replace with your instance URL if self-hosting.

Authentication

The API accepts two authentication methods, both using the Authorization header with the Bearer scheme.

API Keys (Recommended for Automation)

API keys are the preferred method for CI/CD pipelines and automated integrations. Create one at Settings > API Keys.

curl -H "Authorization: Bearer cra_your_api_key" \
  https://api.craevidence.com/api/v1/products

API keys can be scoped to specific permissions. For example, a key with only sbom:write scope can upload SBOMs but cannot delete products. See API Keys for details on available scopes.

JWT Tokens (For Web Applications)

If you're building a web application that authenticates users, use JWT tokens obtained from the login flow. These tokens expire after 15 minutes and must be refreshed using the refresh token.

# Login to get tokens
curl -X POST https://api.craevidence.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@company.com", "password": "password"}'

# Use the access token
curl -H "Authorization: Bearer eyJ0eXAiOiJKV1Q..." \
  https://api.craevidence.com/api/v1/products

Request Format

Send JSON data with POST, PUT, and PATCH requests:

curl -X POST https://api.craevidence.com/api/v1/products \
  -H "Authorization: Bearer cra_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Product",
    "category": "default"
  }'

For file uploads, use multipart form data:

curl -X POST https://api.craevidence.com/api/v1/sboms/ingest \
  -H "Authorization: Bearer cra_your_api_key" \
  -F "file=@sbom.json" \
  -F "version_id=uuid-here"

Response Format

Successful responses return JSON with the requested data:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Product",
  "created_at": "2025-01-15T10:00:00Z"
}

Collection endpoints return paginated results:

{
  "items": [...],
  "total": 100,
  "page": 1,
  "per_page": 50,
  "has_next": true
}

Error Handling

Errors follow RFC 7807 format with a consistent structure:

{
  "error": {
    "type": "https://api.craevidence.com/errors/resource-not-found",
    "title": "Resource Not Found",
    "status": 404,
    "detail": "Product with ID xyz not found",
    "code": "RESOURCE_NOT_FOUND",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

The request_id helps our support team investigate issues. Include it when reporting problems.

Common Status Codes

Common Error Codes

Rate Limiting

The API enforces rate limits to ensure fair usage:

Rate limit information is included in response headers:

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

When you exceed the limit, you'll receive a 429 response. Wait until the reset time before retrying.

Key Endpoints

Products and Versions

# List products
GET /products

# Create product
POST /products
{"name": "My Product", "category": "default"}

# Get product details
GET /products/{id}

# List versions for a product
GET /products/{id}/versions

# Create version
POST /versions
{"product_id": "uuid", "version_number": "1.2.3"}

SBOMs

# Upload SBOM
POST /sboms/ingest
# (multipart: file, version_id, auto_scan=true)

# List SBOMs for a version
GET /versions/{id}/sboms

# Download SBOM file
GET /sboms/{id}/download

Vulnerabilities

# List vulnerabilities
GET /vulnerabilities

# Get vulnerability details
GET /vulnerabilities/{id}

# Update vulnerability status
PATCH /vulnerabilities/{id}
{"status": "in_progress", "notes": "Investigating"}

Exports

# Export technical file (ZIP archive)
GET /versions/{id}/export

# Export compliance report (PDF or HTML)
GET /exports/sboms/{sbom_id}/compliance-report?format=pdf

CI/CD Automation

These endpoints support the CLI and CI/CD integrations:

# Upload SBOM (multipart)
POST /sboms/ingest
# Fields: file, version_id, auto_scan (bool)

# Trigger vulnerability scan
POST /versions/{id}/scan

# Get CRA compliance status
GET /versions/{id}/cra-status

# Set release state
PATCH /versions/{id}/release-state
{"state": "released"}

# Compare two versions (POST with JSON body)
POST /comparison/versions
{"version_a_id": "{id}", "version_b_id": "{id}"}

# Export technical file
GET /versions/{id}/export

# Export compliance report (PDF or HTML)
GET /exports/sboms/{sbom_id}/compliance-report?format=pdf

Interactive Documentation

Explore the full API interactively:

Swagger UI at /docs provides a visual interface where you can try endpoints directly in your browser.

OpenAPI Spec at /openapi.json gives you the machine-readable schema for generating client libraries.

Client Libraries

You can generate client libraries from the OpenAPI spec using tools like:

# Python
openapi-python-client generate --url https://api.craevidence.com/openapi.json

# TypeScript
openapi-generator-cli generate -i https://api.craevidence.com/openapi.json -g typescript-fetch

Best Practices

Use API keys for automation. They're designed for CI/CD and can be scoped to minimum required permissions.

Handle rate limits gracefully. Implement exponential backoff when you receive 429 responses.

Check response codes. Don't assume success. Handle errors appropriately in your integration.

Store the request ID. When something goes wrong, the request ID helps us investigate.

Use pagination. Don't try to fetch all records at once. Page through large datasets.

Related Documentation

• API Keys for creating and managing API access
• CI/CD Integration for pipeline examples
• CLI Reference for command-line usage