Referencia API

CyberOrigen proporciona una API REST completa para integrarse con sus herramientas y flujos de trabajo existentes.

URL Base

https://backend.cyberorigen.com/api/v1

Todas las solicitudes API se hacen a esta URL base.

Documentacion Interactiva

Una vez autenticado, acceda a la documentacion interactiva de la API en:

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

Autenticacion

Todas las solicitudes API requieren autenticacion via token JWT bearer.

Obtener un Token

curl -X POST https://api.yourdomain.com/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=yourpassword"

Respuesta:

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

Usar el Token

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

Limite de Tasa

Los limites de tasa varian segun el nivel de suscripcion:

Plan	Solicitudes/Hora	Solicitudes/Dia
Startup	100	1,000
Professional	500	5,000
Enterprise	Personalizado	Personalizado

Cuando se exceden los limites, la API devuelve HTTP 429 (Too Many Requests).

Los encabezados de limite de tasa se incluyen en las respuestas:

X-RateLimit-Limit: <solicitudes_permitidas>
X-RateLimit-Remaining: <solicitudes_restantes>
X-RateLimit-Reset: <marca_tiempo_unix>

¿Necesita Limites Mayores?

Contacte a [email protected] para limites de tasa personalizados.

Endpoints Comunes

Verificacion de Estado

GET /api/health

Respuesta:

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

Listar Escaneos

GET /api/v1/scans

Respuesta:

{
  "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
}

Crear Escaneo

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

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

Obtener Estado de Control

GET /api/v1/controls

Respuesta:

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

Respuestas de Error

Todos los errores siguen un formato consistente:

{
  "detail": "Mensaje de error aqui",
  "error_code": "VALIDATION_ERROR",
  "field": "email"
}

Codigos de Estado HTTP

Codigo	Significado
200	Exito
201	Creado
400	Solicitud Incorrecta
401	No Autorizado
403	Prohibido
404	No Encontrado
422	Error de Validacion
429	Demasiadas Solicitudes
500	Error del Servidor

Paginacion

Los endpoints de lista soportan paginacion:

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

La respuesta incluye metadatos de paginacion:

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

Webhooks

Configure webhooks para recibir notificaciones en tiempo real:

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

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

SDKs

Los SDKs oficiales estan planificados para:

• Python
• TypeScript/JavaScript
• Go

Por ahora, use la API REST directamente o genere un cliente desde la especificacion OpenAPI.