Settings API

Prefix: /api/settings | Tag: settings

General configuration, YAML rule management (with approval workflow), user management, and audit log.

Endpoints

Method	Path	Description
GET	/api/settings/general	Get general settings
PUT	/api/settings/general	Update general settings
GET	/api/settings/health-rules	Get health scoring YAML
PUT	/api/settings/health-rules	Update health scoring YAML
GET	/api/settings/issue-rules	Get issue grouping YAML
PUT	/api/settings/issue-rules	Update issue grouping YAML
GET	/api/settings/risk-rules	Get risk analysis YAML
PUT	/api/settings/risk-rules	Update risk analysis YAML
GET	/api/settings/config-changes	List config change proposals
GET	/api/settings/config-changes/{change_id}	Config change detail with diff
POST	/api/settings/config-changes/{change_id}/review	Approve or reject a change
POST	/api/settings/recompute	Recompute health scores
POST	/api/settings/recompute-risk	Recompute risk snapshots
GET	/api/settings/users	List all users
POST	/api/settings/users/invite	Invite a new user
PATCH	/api/settings/users/{email}	Update user role or active status
DELETE	/api/settings/users/{email}	Remove a user
GET	/api/settings/audit	Audit log entries
GET	/api/settings/roles	Available role names

---

General Settings

GET /api/settings/general

Returns {"health_scoring_method": "rules", "alert_criticality_method": "rules"}.

PUT /api/settings/general

Request body:

{
  "health_scoring_method": "rules",
  "alert_criticality_method": "rules"
}

---

YAML Rule Management

Each rule set (health, issue, risk) follows the same pattern:

GET /api/settings/{rule-type}

Returns {"content": "<yaml string>", "source": "live"}.

PUT /api/settings/{rule-type}

Request body:

{
  "content": "scoring:\n  dimensions:\n    ..."
}

• Superadmin: YAML is validated and written directly to disk. Returns {"status": "ok", "applied": true}.
• Other roles: Change is submitted for approval. Returns {"status": "pending", "applied": false, "change_id": "abc123"}.

Validation rules:

• Must be valid YAML
• Must be a mapping (dict)
• health-rules must contain a scoring key
• risk-rules must contain a risk key

---

Config Change Approval

GET /api/settings/config-changes

Query params: status_filter (string, optional -- e.g., "pending")

Superadmin sees all changes; other roles see only their own.

GET /api/settings/config-changes/{change_id}

Returns full detail including current_content and proposed_content for diffing.

POST /api/settings/config-changes/{change_id}/review

Superadmin only. Approve or reject a pending change.

Request body:

{
  "action": "approve",
  "note": "Looks good"
}

action must be "approve" or "reject".

---

Score Recomputation

POST /api/settings/recompute

Recomputes health scores from the current rules YAML. Returns {"status": "ok", "cluster_count": 172}.

POST /api/settings/recompute-risk

Recomputes risk snapshots. Returns {"status": "ok", "cluster_count": 172, "critical": 5, "warning": 12}.

---

User Management

GET /api/settings/users

Returns {"users": [{"id": "...", "email": "...", "display_name": "...", "role": "viewer", "is_active": true}]}.

POST /api/settings/users/invite

Request body:

{
  "email": "new@celerdata.com",
  "display_name": "New User",
  "role": "viewer"
}

Returns {"status": "ok", "email_sent": true}. If email sending fails, returns the activation_token for manual sharing.

PATCH /api/settings/users/{email}

Request body (all optional):

{
  "role": "admin",
  "is_active": false
}

DELETE /api/settings/users/{email}

Removes the user. Returns {"status": "ok"}.

---

Audit Log

GET /api/settings/audit

Query params: action (string, optional -- filter by action type)

Returns {"entries": [...], "action_types": ["login", "logout", "invite", ...]}.

GET /api/settings/roles

Returns {"roles": ["superadmin", "admin", "viewer"]}.