API Reference
Changes
List, create, and retrieve infrastructure changes via the API.
List changes
GET /api/changesQuery parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page, max 100 (default: 25) |
q | string | Full-text search on title |
service_id | uuid | Filter by service |
risk_level | string | low, medium or high |
status | string | planned, in_progress, completed or rolled_back |
Example
curl "https://app.changevault.dev/api/changes?status=completed&per_page=10" \
-H "x-api-key: cvk_prod_••••••••"Response
{
"data": [...],
"count": 42,
"page": 1,
"per_page": 10,
"total_pages": 5
}Get a change
GET /api/changes/:idExample
curl https://app.changevault.dev/api/changes/uuid \
-H "x-api-key: cvk_prod_••••••••"Response
{
"data": {
"id": "uuid",
"title": "Deployed api-service v3.1.0",
"description": null,
"risk_level": "medium",
"status": "completed",
"service": { "id": "uuid", "name": "api-service", "color": "#6366f1" },
"host_ref": { "id": "uuid", "hostname": "web-01", "environment": "prod" },
"tags": ["deploy", "prod"],
"scheduled_for": null,
"created_at": "2025-04-07T10:00:00Z",
"organization_id": "org_..."
}
}Create a change
POST /api/changesCreating changes via the API requires the Pro plan or higher.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | ✓ | Short description of the change (3–300 chars) |
description | string | Detailed description | |
service_id | uuid | Associate with a service | |
host_id | uuid | Associate with a host | |
risk_level | string | low (default), medium or high | |
status | string | planned (default), in_progress, completed, rolled_back | |
impact | string | Expected impact description | |
tags | string[] | Up to 20 tags | |
scheduled_for | ISO 8601 | When the change is scheduled |
Example
curl -X POST https://app.changevault.dev/api/changes \
-H "x-api-key: cvk_prod_••••••••" \
-H "Content-Type: application/json" \
-d '{
"title": "Deployed api-service v3.1.0",
"risk_level": "medium",
"status": "completed",
"tags": ["deploy", "api", "prod"]
}'Response
{
"data": {
"id": "uuid",
"title": "Deployed api-service v3.1.0",
"risk_level": "medium",
"status": "completed",
"organization_id": "org_...",
"created_at": "2025-04-07T10:00:00Z"
}
}