API Reference
Hosts
List, create, and retrieve hosts via the API.
List hosts
GET /api/hostsReturns all hosts in your organization, ordered by hostname.
Example
curl https://app.changevault.dev/api/hosts \
-H "x-api-key: cvk_prod_••••••••"Response
{
"data": [
{
"id": "uuid",
"hostname": "web-01",
"fqdn": "web-01.example.com",
"ip_address": "10.0.0.1",
"os": "Ubuntu 24.04",
"platform": "on-prem",
"environment": "prod",
"roles": ["web", "load-balancer"],
"organization_id": "org_...",
"created_at": "2025-04-01T08:00:00Z"
}
]
}Get a host
GET /api/hosts/:idExample
curl https://app.changevault.dev/api/hosts/uuid \
-H "x-api-key: cvk_prod_••••••••"Response
{
"data": {
"id": "uuid",
"hostname": "web-01",
"fqdn": "web-01.example.com",
"ip_address": "10.0.0.1",
"os": "Ubuntu 24.04",
"platform": "on-prem",
"environment": "prod",
"roles": ["web", "load-balancer"],
"organization_id": "org_...",
"created_at": "2025-04-01T08:00:00Z"
}
}Create a host
POST /api/hostsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
hostname | string | ✓ | Short hostname (1–100 chars) |
fqdn | string | Fully qualified domain name | |
ip_address | string | IPv4 or IPv6 address | |
os | string | Operating system, e.g. Ubuntu 24.04 | |
platform | string | on-prem, private-cloud, aws, gcp, azure, or other (default: on-prem) | |
environment | string | prod, staging, dev, or test | |
roles | string[] | List of roles, e.g. ["web", "database"] | |
description | string | Optional description (max 1000 chars) |
Example
curl -X POST https://app.changevault.dev/api/hosts \
-H "x-api-key: cvk_prod_••••••••" \
-H "Content-Type: application/json" \
-d '{
"hostname": "db-01",
"fqdn": "db-01.internal.example.com",
"os": "Debian 12",
"platform": "on-prem",
"environment": "prod",
"roles": ["database"]
}'Response
{
"data": {
"id": "uuid",
"hostname": "db-01",
"fqdn": "db-01.internal.example.com",
"os": "Debian 12",
"platform": "on-prem",
"environment": "prod",
"roles": ["database"],
"organization_id": "org_...",
"created_at": "2025-04-07T12:00:00Z"
}
}Returns 409 Conflict if a host with the same hostname already exists.