API Reference

CyberOrigen provides a comprehensive REST API for integrating with your existing tools and workflows.

Base URL

https://api.yourdomain.com/api/v1

Replace yourdomain.com with your CyberOrigen instance domain.

Interactive Documentation

Once authenticated, access interactive API documentation at:

• Swagger UI: /docs
• ReDoc: /redoc
• OpenAPI Spec: /openapi.json

Authentication

All API requests require authentication via JWT bearer token.

Obtaining a Token

curl -X POST https://api.yourdomain.com/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=yourpassword"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Using the Token

curl https://api.yourdomain.com/api/v1/scans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate Limiting

Rate limiting is enforced on all API endpoints to ensure service availability. When limits are exceeded, the API returns HTTP 429 (Too Many Requests).

Rate limit headers are included in responses:

X-RateLimit-Limit: <requests_allowed>
X-RateLimit-Remaining: <requests_remaining>
X-RateLimit-Reset: <unix_timestamp>

Common Endpoints

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2025-12-21T12:00:00Z"
}

List Scans

GET /api/v1/scans

Response:

{
  "items": [
    {
      "id": "scan_abc123",
      "target": "example.com",
      "status": "completed",
      "created_at": "2025-12-21T10:00:00Z",
      "vulnerabilities_found": 5
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Create Scan

POST /api/v1/scans
Content-Type: application/json

{
  "target": "example.com",
  "scan_type": "full",
  "frameworks": ["soc2", "pci-dss"]
}

Get Control Status

GET /api/v1/controls

Response:

{
  "items": [
    {
      "id": "ctrl_123",
      "name": "Access Control Policy",
      "status": "implemented",
      "frameworks": ["SOC 2", "ISO 27001"],
      "evidence_count": 3
    }
  ]
}

Error Responses

All errors follow a consistent format:

{
  "detail": "Error message here",
  "error_code": "VALIDATION_ERROR",
  "field": "email"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Too Many Requests
500	Server Error

Pagination

List endpoints support pagination:

GET /api/v1/scans?page=2&per_page=50

Response includes pagination metadata:

{
  "items": [...],
  "total": 150,
  "page": 2,
  "per_page": 50,
  "pages": 3
}

Webhooks

Configure webhooks to receive real-time notifications:

POST /api/v1/webhooks
Content-Type: application/json

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

SDKs

Official SDKs are planned for:

• Python
• TypeScript/JavaScript
• Go

For now, use the REST API directly or generate a client from the OpenAPI spec.