syncova-backup/SYNCOVA_API.md

Syncova Backups V1 — REST API Specification

Base URL:

/api/v1

Transport:

• HTTPS
• JSON
• UTF-8

Authentication:

Authorization: Bearer <access-token>

Every request should support a correlation identifier:

X-Correlation-ID: <uuid>

1. Standard Response

Success:

{
  "data": {},
  "meta": {
    "request_id": "uuid"
  }
}

Error:

{
  "error": {
    "code": "BACKUP_REPOSITORY_UNAVAILABLE",
    "message": "The configured repository is unavailable.",
    "details": {},
    "request_id": "uuid"
  }
}

2. Authentication

POST /auth/login

Request:

{
  "username": "admin",
  "password": "password"
}

Response may require MFA:

{
  "data": {
    "mfa_required": true,
    "challenge_id": "uuid"
  }
}

POST /auth/mfa/verify

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

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

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

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

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

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

metric
entity_type
entity_id
from
to
interval

Example:

/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

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

{
  "data": {
    "status": "healthy",
    "components": {
      "database": "healthy",
      "repositories": "healthy",
      "scheduler": "healthy",
      "agents": "healthy"
    }
  }
}

24. WebSocket / Live Updates

Recommended endpoint:

/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:

Idempotency-Key: <uuid>

for:

• create backup job
• start backup
• create restore
• create repository
• destructive configuration changes

28. Pagination

Preferred:

?page=1&page_size=50

Response:

{
  "data": [],
  "meta": {
    "page": 1,
    "page_size": 50,
    "total": 1000
  }
}