> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrubbe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changes API — create and manage infrastructure changes

> Track planned modifications to your systems. Create, retrieve, update, and delete change records to correlate deployments with incidents.

Change requests in Scrubbe represent planned or in-progress modifications to your systems — deployments, configuration updates, infrastructure changes, and similar events. Tracking changes alongside incidents lets Scrubbe correlate service disruptions with recent modifications, improving the speed and accuracy of root cause analysis. Every change record supports scheduling, rollback planning, and risk classification.

<Note>
  All endpoints require `Authorization: Bearer <token>`.
</Note>

**Base path:** `https://your-api-domain.com/api/v1/changes`

***

## Create a change request

`POST /`

<ParamField body="title" type="string" required>
  Short title for the change request (e.g. `"Upgrade PostgreSQL to 16.2"`).
</ParamField>

<ParamField body="description" type="string" required>
  Detailed description of the change being made.
</ParamField>

<ParamField body="type" type="string" required>
  Change type: `STANDARD`, `NORMAL`, or `EMERGENCY`.
</ParamField>

<ParamField body="risk" type="string">
  Risk level: `LOW`, `MEDIUM`, or `HIGH`.
</ParamField>

<ParamField body="serviceArea" type="string">
  Affected service or team area.
</ParamField>

<ParamField body="environment" type="string">
  Target environment (e.g. `"production"`, `"staging"`).
</ParamField>

<ParamField body="scheduledAt" type="string">
  ISO 8601 timestamp for the planned change window.
</ParamField>

<ParamField body="assignedToEmail" type="string">
  Email of the engineer responsible for implementing the change.
</ParamField>

<ParamField body="rollbackPlan" type="string">
  Description of how to revert the change if it fails.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api-domain.com/api/v1/changes \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Upgrade PostgreSQL to 16.2",
      "description": "Rolling upgrade of the primary database cluster from 15.4 to 16.2.",
      "type": "NORMAL",
      "risk": "HIGH",
      "serviceArea": "database",
      "environment": "production",
      "scheduledAt": "2026-05-25T02:00:00Z",
      "assignedToEmail": "dba@example.com",
      "rollbackPlan": "Restore from pre-upgrade snapshot taken at T-30min."
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://your-api-domain.com/api/v1/changes",
      headers={"Authorization": "Bearer <token>"},
      json={
          "title": "Upgrade PostgreSQL to 16.2",
          "description": "Rolling upgrade of the primary database cluster from 15.4 to 16.2.",
          "type": "NORMAL",
          "risk": "HIGH",
          "serviceArea": "database",
          "environment": "production",
          "scheduledAt": "2026-05-25T02:00:00Z",
          "assignedToEmail": "dba@example.com",
          "rollbackPlan": "Restore from pre-upgrade snapshot taken at T-30min.",
      },
  )
  print(resp.json())
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "success": true,
  "message": "Change request created",
  "data": {
    "id": "CHG-20260522-0015",
    "title": "Upgrade PostgreSQL to 16.2",
    "type": "NORMAL",
    "risk": "HIGH",
    "status": "PENDING",
    "scheduledAt": "2026-05-25T02:00:00Z",
    "createdAt": "2026-05-22T10:00:00Z"
  }
}
```

***

## List change requests

Returns a paginated list of change requests ordered by creation date descending.

`GET /`

<ParamField query="page" type="number" default="1">Page number.</ParamField>
<ParamField query="limit" type="number" default="20">Items per page (max 100).</ParamField>
<ParamField query="status" type="string">Filter by status: `PENDING`, `APPROVED`, `IN_PROGRESS`, `COMPLETED`, or `CANCELLED`.</ParamField>
<ParamField query="environment" type="string">Filter by environment.</ParamField>
<ParamField query="risk" type="string">Filter by risk level: `LOW`, `MEDIUM`, or `HIGH`.</ParamField>

***

## Get a change request

`GET /:id`

<ParamField path="id" type="string" required>
  The change request ID.
</ParamField>

***

## Update a change request

Accepts the same fields as `POST /`. Only provided fields are updated. Use this endpoint to progress status, adjust the scheduled window, or add a rollback plan after initial creation.

`PUT /:id`

<ParamField path="id" type="string" required>
  The change request ID.
</ParamField>

```bash cURL theme={null}
curl -X PUT https://your-api-domain.com/api/v1/changes/CHG-20260522-0015 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "APPROVED" }'
```

***

## Delete a change request

`DELETE /:id`

<ParamField path="id" type="string" required>
  The change request ID to delete.
</ParamField>

<Warning>
  Deleted change requests are permanently removed and cannot be recovered. If a change has already been executed or is linked to an incident, update its status to `CANCELLED` instead to preserve the audit trail.
</Warning>