# Syncova Backups V1 — REST API Specification Base URL: ```text /api/v1 ``` Transport: - HTTPS - JSON - UTF-8 Authentication: ```text Authorization: Bearer ``` Every request should support a correlation identifier: ```text X-Correlation-ID: ``` ## 1. Standard Response Success: ```json { "data": {}, "meta": { "request_id": "uuid" } } ``` Error: ```json { "error": { "code": "BACKUP_REPOSITORY_UNAVAILABLE", "message": "The configured repository is unavailable.", "details": {}, "request_id": "uuid" } } ``` ## 2. Authentication ### POST /auth/login Request: ```json { "username": "admin", "password": "password" } ``` Response may require MFA: ```json { "data": { "mfa_required": true, "challenge_id": "uuid" } } ``` ### POST /auth/mfa/verify ```json { "challenge_id": "uuid", "code": "123456" } ``` ### POST /auth/refresh Refresh an access token. ### POST /auth/logout Invalidate the current session. ## 3. Current User ### GET /me Returns: - user - roles - permissions - MFA status ## 4. Users ### GET /users Filters: - status - role - search ### POST /users ```json { "username": "operator", "email": "operator@example.com", "roles": ["backup_operator"] } ``` ### GET /users/{id} ### PATCH /users/{id} ### DELETE /users/{id} Deletion must be audited. ## 5. Roles ### GET /roles ### POST /roles ### GET /roles/{id} ### PATCH /roles/{id} ### DELETE /roles/{id} ## 6. Agents ### GET /agents ### POST /agents/register Used by an enrollment flow. ### GET /agents/{id} ### POST /agents/{id}/revoke ### POST /agents/{id}/rotate-credentials ### GET /agents/{id}/health ## 7. Proxmox ### GET /proxmox/clusters ### POST /proxmox/clusters Request: ```json { "name": "Production PVE", "api_endpoint": "https://pve.example.local:8006", "credential_ref": "secret-ref" } ``` ### GET /proxmox/clusters/{id} ### POST /proxmox/clusters/{id}/test ### POST /proxmox/clusters/{id}/discover ### GET /proxmox/clusters/{id}/hosts ### GET /proxmox/clusters/{id}/vms ### GET /proxmox/vms/{id} ## 8. Repositories ### GET /repositories ### POST /repositories Example: ```json { "name": "Repository-01", "type": "hardened_linux", "endpoint": "/backup/repository-01", "immutable": true, "encryption_required": true } ``` ### GET /repositories/{id} ### PATCH /repositories/{id} ### POST /repositories/{id}/test ### POST /repositories/{id}/health-check ### POST /repositories/{id}/integrity-scan ### POST /repositories/{id}/rebuild-catalog The rebuild operation must require appropriate authorization. ## 9. Backup Jobs ### GET /jobs Filters: - status - source - repository - search ### POST /jobs ```json { "name": "Production VMs", "description": "Nightly production backup", "priority": "high", "schedule": { "type": "daily", "time": "02:00" }, "sources": [ { "type": "proxmox_vm", "id": "uuid" } ], "repository_id": "uuid", "retention_policy_id": "uuid", "encryption_policy_id": "uuid", "verification_policy_id": "uuid", "rpo_seconds": 14400, "rto_seconds": 7200 } ``` ### GET /jobs/{id} ### PATCH /jobs/{id} ### DELETE /jobs/{id} Deletion is audited and may require step-up authentication. ### POST /jobs/{id}/run Run immediately. ### POST /jobs/{id}/pause ### POST /jobs/{id}/resume ### GET /jobs/{id}/runs ## 10. Backup Runs ### GET /backup-runs/{id} ### POST /backup-runs/{id}/cancel ### GET /backup-runs/{id}/logs ### GET /backup-runs/{id}/metrics ## 11. Backups ### GET /backups Filters: - source - job - repository - status - date range - verification status ### GET /backups/{id} ### GET /backups/{id}/manifest ### GET /backups/{id}/integrity ### POST /backups/{id}/verify ## 12. Recovery Points ### GET /recovery-points ### GET /recovery-points/{id} ### POST /recovery-points/{id}/validate ## 13. Restore ### POST /restores/validate Request: ```json { "backup_id": "uuid", "target_type": "proxmox_vm", "target": { "cluster_id": "uuid", "host_id": "uuid", "vm_name": "restored-vm" } } ``` ### POST /restores Create a restore job. ### GET /restores ### GET /restores/{id} ### POST /restores/{id}/cancel ### GET /restores/{id}/logs ### GET /restores/{id}/metrics ## 14. Verification ### GET /verification ### POST /verification ### GET /verification/{id} ### POST /verification/{id}/cancel ### GET /verification/{id}/results ## 15. Alerts ### GET /alerts Filters: - severity - status - date - entity ### POST /alerts/{id}/acknowledge ### POST /alerts/{id}/resolve ### GET /alert-rules ### POST /alert-rules ### PATCH /alert-rules/{id} ### DELETE /alert-rules/{id} ## 16. Events ### GET /events Filters: - severity - type - entity - date range ## 17. Audit ### GET /audit-events Filters: - user - action - entity - date range - result Audit access must be restricted. ## 18. Metrics ### GET /metrics Parameters: ```text metric entity_type entity_id from to interval ``` Example: ```text /metrics?metric=repository.used&entity_id=uuid&from=...&to=...&interval=1h ``` ## 19. Dashboard ### GET /dashboard/summary Returns: - protected systems - successful backups - failed backups - warnings - critical alerts - storage - recovery assurance - security score ### GET /dashboard/backup-trends ### GET /dashboard/storage-trends ### GET /dashboard/rpo ### GET /dashboard/ransomware-risk ## 20. Security ### GET /security/score ### GET /security/findings ### GET /security/status ### GET /security/certificates ## 21. Reports ### GET /reports ### POST /reports/generate ```json { "type": "daily_backup", "from": "2026-08-01T00:00:00Z", "to": "2026-08-10T23:59:59Z", "format": "pdf" } ``` ## 22. Policies ### GET /retention-policies ### POST /retention-policies ### GET /encryption-policies ### POST /encryption-policies ### GET /verification-policies ### POST /verification-policies ### GET /notification-policies ### POST /notification-policies ## 23. System Health ### GET /health/live ### GET /health/ready ### GET /health Returns component health: ```json { "data": { "status": "healthy", "components": { "database": "healthy", "repositories": "healthy", "scheduler": "healthy", "agents": "healthy" } } } ``` ## 24. WebSocket / Live Updates Recommended endpoint: ```text /api/v1/events/stream ``` Events: - job.started - job.progress - job.completed - job.failed - restore.progress - alert.created - repository.health_changed - agent.status_changed ## 25. HTTP Status Codes Use standard codes: - 200 OK - 201 Created - 202 Accepted - 204 No Content - 400 Bad Request - 401 Unauthorized - 403 Forbidden - 404 Not Found - 409 Conflict - 422 Unprocessable Entity - 429 Too Many Requests - 500 Internal Server Error - 503 Service Unavailable ## 26. API Rules - Validate all input. - Enforce RBAC server-side. - Never trust frontend permissions. - Never expose secrets. - Use pagination on large collections. - Use idempotency keys for operations where duplicate execution could be dangerous. - Audit destructive actions. - Use request IDs and correlation IDs. - Keep error messages useful but avoid leaking sensitive internals. ## 27. Idempotency Support: ```text Idempotency-Key: ``` for: - create backup job - start backup - create restore - create repository - destructive configuration changes ## 28. Pagination Preferred: ```text ?page=1&page_size=50 ``` Response: ```json { "data": [], "meta": { "page": 1, "page_size": 50, "total": 1000 } } ```