Changes API

Endpoints Overview

List Changes

curl -H "Authorization: Bearer $TOKEN"   "https://your-instance.stackflow-tech.com/prod/api/changes?state=scheduled&type=normal&limit=20"

Get Change

{
  "id": "CHG0000456",
  "type": "normal",
  "state": "cab_review",
  "short_description": "Upgrade Aurora PostgreSQL from 16.1 to 16.4",
  "description": "Apply minor version upgrade during maintenance window...",
  "risk": "medium",
  "risk_score": 42,
  "implementation_plan": "1. Take Aurora snapshot\n2. Apply version upgrade\n3. Validate connections\n4. Run smoke tests",
  "backout_plan": "1. Restore from pre-upgrade snapshot",
  "test_plan": "Run StackFlow health check and full regression test suite",
  "cab_approval_required": true,
  "cab_approvers": ["arch-review@example.com", "security@example.com"],
  "scheduled_start": "2026-05-25T02:00:00Z",
  "scheduled_end": "2026-05-25T04:00:00Z",
  "assignment_group": "Platform Engineering",
  "created_at": "2026-05-19T10:00:00Z"
}

Create Change

curl -X POST   https://your-instance.stackflow-tech.com/prod/api/changes   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{
    "type": "normal",
    "short_description": "Deploy StackFlowAPI v2026.2 release",
    "description": "Deploy new Lambda function version with incident auto-classification improvements",
    "implementation_plan": "1. Upload new Lambda ZIP\n2. Update alias to new version\n3. Monitor error rate for 15 min",
    "backout_plan": "1. Update Lambda alias back to previous version",
    "test_plan": "Run API smoke tests, verify health endpoint, check CloudWatch alarms",
    "risk": "low",
    "scheduled_start": "2026-05-22T01:00:00Z",
    "scheduled_end": "2026-05-22T02:00:00Z",
    "assignment_group": "Platform Engineering"
  }'

Submit for CAB Approval

curl -X POST   https://your-instance.stackflow-tech.com/prod/api/changes/CHG0000456/submit-cab   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{
    "cab_meeting_date": "2026-05-21T14:00:00Z",
    "notes": "Urgent: addresses P1 incident PRB0000123"
  }'

Update Change

curl -X PATCH   https://your-instance.stackflow-tech.com/prod/api/changes/CHG0000456   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"state": "in_progress", "actual_start": "2026-05-22T01:05:00Z"}'

Change state machine:

draft → submitted → cab_review → scheduled → in_progress → completed → closed
draft → cancelled
cab_review → rejected → draft (revision)
in_progress → failed → post_review

Risk Score

The AI risk scoring endpoint analyzes the change plan text and returns a 0-100 risk score with contributing factors.

curl -H "Authorization: Bearer $TOKEN"   https://your-instance.stackflow-tech.com/prod/api/changes/CHG0000456/risk

{
  "risk_score": 42,
  "risk_level": "medium",
  "factors": [
    {"factor": "Production database change", "weight": 0.4, "score": 70},
    {"factor": "Maintenance window scheduled", "weight": 0.2, "score": 10},
    {"factor": "Rollback plan present", "weight": 0.2, "score": 15},
    {"factor": "Test plan present", "weight": 0.2, "score": 20}
  ],
  "recommendation": "Proceed with CAB review. Ensure DBA is on call during maintenance window."
}

Field Reference