syncova-backup/SYNCOVA_API.md

# Syncova Backups V1 — REST API Specification

Base URL:

```text
/api/v1
```

Transport:

- HTTPS
- JSON
- UTF-8

Authentication:

```text
Authorization: Bearer <access-token>
```

Every request should support a correlation identifier:

```text
X-Correlation-ID: <uuid>
```

## 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: <uuid>
```

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
  }
}
```