REST API

The Kymaros API server (kymaros-api) exposes a JSON REST API consumed by the dashboard and available to external tooling. By default it listens on port 8080 inside the kymaros-system namespace.

All responses use Content-Type: application/json unless stated otherwise. Timestamps are RFC 3339 UTC strings. Durations are Go duration strings (e.g., "11m35s", "1h").

Base URL

When accessed via kubectl port-forward:

kubectl port-forward -n kymaros-system svc/kymaros-api 8080:8080

The base URL is http://localhost:8080.

---

Endpoints

GET /api/v1/health

Liveness probe. Returns 200 when the API server is running.

Response

{"status": "ok"}

Status codes

Code	Meaning
200	API server is running.

Example

curl http://localhost:8080/api/v1/health

---

GET /api/v1/summary

Returns aggregate metrics across all RestoreTest resources.

Response

{
  "averageScore": 87,
  "totalTests": 12,
  "testsLastNight": 8,
  "totalFailures": 1,
  "totalPartial": 2,
  "averageRTO": "14m22s",
  "namespacesCovered": 18
}

Field	Type	Description
averageScore	int	Average confidence score across all tests over the last 24 hours.
totalTests	int	Total number of RestoreTest resources present.
testsLastNight	int	Number of tests that completed a run in the last 24 hours.
totalFailures	int	Number of fail results across all tests in the last 24 hours.
totalPartial	int	Number of partial results across all tests in the last 24 hours.
averageRTO	string	Mean measured RTO across all runs in the last 24 hours.
namespacesCovered	int	Total distinct source namespaces covered by at least one RestoreTest.

Status codes

Code	Meaning
200	Success.

Example

curl http://localhost:8080/api/v1/summary

---

GET /api/v1/summary/daily

Returns a time series of daily summary metrics for trend analysis.

Query parameters

Parameter	Type	Default	Description
days	int	30	Number of days of history to return.

Response

Array of DailySummary objects, one per day, ordered chronologically.

[
  {
    "date": "2024-03-15",
    "score": 94,
    "tests": 8,
    "failures": 0
  },
  {
    "date": "2024-03-16",
    "score": 71,
    "tests": 8,
    "failures": 2
  }
]

Field	Type	Description
date	string	Date in YYYY-MM-DD format.
score	int	Average confidence score for that day.
tests	int	Number of test runs completed that day.
failures	int	Number of fail results that day.

Status codes

Code	Meaning
200	Success.

Example

curl "http://localhost:8080/api/v1/summary/daily?days=7"

---

GET /api/v1/tests

Returns all RestoreTest resources and their current status.

Response

Array of TestResponse objects.

[
  {
    "name": "my-app-nightly",
    "namespace": "kymaros-system",
    "provider": "velero",
    "schedule": "0 2 * * *",
    "phase": "Idle",
    "lastScore": 96,
    "lastResult": "pass",
    "lastRunAt": "2024-03-15T02:11:47Z",
    "nextRunAt": "2024-03-16T02:00:00Z",
    "sourceNamespaces": ["my-app"],
    "rtoTarget": "30m"
  }
]

Field	Type	Description
name	string	RestoreTest resource name.
namespace	string	Kubernetes namespace of the resource.
provider	string	Backup provider (velero, kasten, trilio).
schedule	string	Cron expression from spec.schedule.cron.
phase	string	Current phase: Idle, Running, Completed, or Failed.
lastScore	int	Score from the most recent run.
lastResult	string	Result from the most recent run: pass, fail, or partial.
lastRunAt	string	Timestamp of the most recent run completion.
nextRunAt	string	Scheduled time for the next run.
sourceNamespaces	[]string	Source namespace names from spec.backupSource.namespaces[*].name.
rtoTarget	string	Value of spec.sla.maxRTO, or empty if SLA not configured.

Status codes

Code	Meaning
200	Success.

Example

curl http://localhost:8080/api/v1/tests

---

POST /api/v1/tests

Creates a new RestoreTest resource.

Request body (CreateTestInput)

{
  "name": "my-app-nightly",
  "namespace": "kymaros-system",
  "provider": "velero",
  "backupName": "latest",
  "sourceNamespaces": ["my-app"],
  "cron": "0 2 * * *",
  "timezone": "UTC",
  "namespacePrefix": "rp-test",
  "ttl": "30m",
  "networkIsolation": "strict",
  "healthCheckPolicy": "my-app-health-policy",
  "maxRTO": "30m",
  "alertOnExceed": true,
  "historyLimit": 10
}

Status codes

Code	Meaning
201	Resource created successfully.
400	Request body is invalid or missing required fields.
409	A RestoreTest with this name already exists in the namespace.

Example

curl -X POST http://localhost:8080/api/v1/tests \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-nightly",
    "namespace": "kymaros-system",
    "provider": "velero",
    "backupName": "latest",
    "sourceNamespaces": ["my-app"],
    "cron": "0 2 * * *"
  }'

---

PUT /api/v1/tests/:name

Updates an existing RestoreTest resource. The :name path parameter is the resource name.

Request body

Same schema as POST /api/v1/tests (CreateTestInput).

Status codes

Code	Meaning
200	Resource updated successfully.
400	Request body is invalid.
404	No RestoreTest with this name exists.

Example

curl -X PUT http://localhost:8080/api/v1/tests/my-app-nightly \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 3 * * *",
    "maxRTO": "45m"
  }'

---

DELETE /api/v1/tests/:name

Deletes a RestoreTest resource. Associated RestoreReport objects are garbage-collected by the controller via owner references.

Status codes

Code	Meaning
204	Resource deleted.
404	No RestoreTest with this name exists.

Example

curl -X DELETE http://localhost:8080/api/v1/tests/my-app-nightly

---

POST /api/v1/tests/:name/trigger

Triggers an immediate out-of-schedule test run for the named RestoreTest. The controller begins a run regardless of the cron schedule.

Status codes

Code	Meaning
200	Run triggered. The test phase transitions to Running.
404	No RestoreTest with this name exists.
409	A run is already in progress for this test.

Example

curl -X POST http://localhost:8080/api/v1/tests/my-app-nightly/trigger

---

GET /api/v1/reports

Returns RestoreReport objects, with optional filtering.

Query parameters

Parameter	Type	Default	Description
test	string	—	Filter by RestoreTest name.
days	int	30	Return reports from the last N days.
latest	bool	false	When true, return only the most recent report per test.

Response

Array of RestoreReport objects (full CRD representation).

Status codes

Code	Meaning
200	Success.
404	The specified test name does not exist (only when test is provided).

Example

# All reports for a specific test from the last 7 days
curl "http://localhost:8080/api/v1/reports?test=my-app-nightly&days=7"

# Latest report for each test
curl "http://localhost:8080/api/v1/reports?latest=true"

---

GET /api/v1/alerts

Returns recent test failures and score regressions.

Query parameters

Parameter	Type	Default	Description
hours	int	48	Look-back window in hours.

Response

Array of Alert objects ordered by timestamp descending.

[
  {
    "timestamp": "2024-03-16T03:18:33Z",
    "testName": "orders-db-validation",
    "namespace": "kymaros-system",
    "score": 42,
    "prevScore": 91,
    "result": "fail",
    "message": "postgres-pod-ready: CrashLoopBackOff — OOMKilled"
  }
]

Field	Type	Description
timestamp	string	Time the alert was generated.
testName	string	Name of the RestoreTest that triggered the alert.
namespace	string	Namespace of the RestoreTest.
score	int	Score from the current run.
prevScore	int	Score from the preceding run (for regression comparison).
result	string	Result of the current run.
message	string	Human-readable description of the failure or regression.

Status codes

Code	Meaning
200	Success.

Example

curl "http://localhost:8080/api/v1/alerts?hours=24"

---

GET /api/v1/compliance

Returns a compliance evidence summary for a specific framework and reporting period.

Query parameters

Parameter	Type	Default	Description
framework	string	—	Compliance framework identifier. Supported values: soc2, iso27001, hipaa.
period	int	—	Reporting period in days (e.g., 90 for a quarterly period).

Response (ComplianceResponse)

{
  "framework": "soc2",
  "period": 90,
  "generatedAt": "2024-03-16T10:00:00Z",
  "totalTests": 720,
  "passRate": 0.96,
  "avgScore": 91,
  "slaCompliance": 0.94,
  "namespacesCovered": 18,
  "controls": [
    {
      "id": "CC9.1",
      "title": "Recovery procedures are tested",
      "status": "satisfied",
      "evidence": "720 restore validation runs over 90 days with 96% pass rate"
    }
  ]
}

Status codes

Code	Meaning
200	Success.
400	Unknown framework or missing parameters.

Example

curl "http://localhost:8080/api/v1/compliance?framework=soc2&period=90"

---

GET /api/v1/compliance/pdf

Generates and returns a PDF compliance report. Requires an Enterprise license tier.

Query parameters

Same as GET /api/v1/compliance: framework and period.

Response

Binary PDF blob with Content-Type: application/pdf and Content-Disposition: attachment; filename=kymaros-compliance-<framework>-<period>d.pdf.

Status codes

Code	Meaning
200	PDF generated and returned.
400	Unknown framework or missing parameters.
402	Active license does not include PDF export (Enterprise feature).

Example

curl "http://localhost:8080/api/v1/compliance/pdf?framework=soc2&period=90" \
  --output kymaros-compliance-soc2-90d.pdf

---

GET /api/v1/upcoming

Returns the next scheduled run for each RestoreTest.

Response

Array of UpcomingTest objects ordered by nextRunAt ascending.

[
  {
    "name": "my-app-nightly",
    "namespace": "kymaros-system",
    "nextRunAt": "2024-03-16T02:00:00Z",
    "lastScore": 96
  }
]

Field	Type	Description
name	string	RestoreTest name.
namespace	string	Namespace of the resource.
nextRunAt	string	Scheduled time for the next run.
lastScore	int	Score from the most recent completed run.

Status codes

Code	Meaning
200	Success.

Example

curl http://localhost:8080/api/v1/upcoming

---

GET /api/v1/schedules

Returns Velero Schedule objects discovered in the cluster. This endpoint is specific to the Velero provider and lists available backup schedules that can be referenced in a RestoreTest.

Response

Array of ScheduleInfo objects.

[
  {
    "name": "orders-daily",
    "cron": "0 22 * * *",
    "namespaces": ["orders", "orders-jobs"],
    "lastBackup": "2024-03-15T22:00:04Z"
  }
]

Field	Type	Description
name	string	Velero Schedule resource name.
cron	string	Cron expression configured on the Velero schedule.
namespaces	[]string	Namespaces included in this Velero schedule.
lastBackup	string	Timestamp of the most recent successful backup created by this schedule.

Status codes

Code	Meaning
200	Success.
503	Velero is not reachable or not installed.

Example

curl http://localhost:8080/api/v1/schedules

---

GET /api/v1/license

Returns the current license state.

Response (LicenseResponse)

{
  "tier": "pro",
  "expiresAt": "2025-01-01T00:00:00Z",
  "trialEndsAt": null,
  "isExpired": false,
  "isTrialing": false,
  "trialDaysLeft": 0,
  "features": ["compliance-export", "multi-namespace", "pagerduty"]
}

Field	Type	Description
tier	string	License tier: community, pro, or enterprise.
expiresAt	string	License expiry date, or null for perpetual.
trialEndsAt	string	Trial expiry date, or null if not trialing.
isExpired	bool	true if the license has expired.
isTrialing	bool	true if running on a trial license.
trialDaysLeft	int	Days remaining in the trial, or 0 if not trialing.
features	[]string	Feature flags enabled by the current license.

Status codes

Code	Meaning
200	Success.

Example

curl http://localhost:8080/api/v1/license