Servers API

List servers

GET /api/v1/servers

const { data: servers } = await puchify.servers.list({ status: "running" })

servers = puchify.servers.list(status="running")

servers, err := client.Servers.List(ctx, &puchify.ServerListParams{
  Status: puchify.String("running"),
})

puchify servers list --status running

curl https://api.puchify.com/api/v1/servers \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)
`status`	string	Filter by status (`running`, `stopped`, etc.)
`sort`	`name` \| `created_at`	Sort field
`order`	`asc` \| `desc`	Sort direction

Create a server

POST /api/v1/servers

const { data: server } = await puchify.servers.create({
  name: "web-01",
  plan: "shared-2",
  region: "us-east",
  image: "ubuntu-24.04",
})

server = puchify.servers.create(
  name="web-01",
  plan="shared-2",
  region="us-east",
  image="ubuntu-24.04",
)

server, err := client.Servers.Create(ctx, &puchify.CreateServerInput{
  Name: "web-01", Plan: "shared-2", Region: "us-east",
})

curl -X POST https://api.puchify.com/api/v1/servers \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-01","plan":"shared-2","region":"us-east"}'

Request body:

Field	Type	Required	Description
`name`	string	yes	Server name (2-40 chars, lowercase alphanumeric + dashes)
`plan`	string	yes	Server plan ID
`region`	string	yes	Region ID
`image`	string	no	OS image (default: `ubuntu-24.04`)
`ssh_keys`	string[]	no	SSH key IDs to inject

Get a server

GET /api/v1/servers/{id}

Update a server

PATCH /api/v1/servers/{id}

Delete a server

DELETE /api/v1/servers/{id}

Restart a server

POST /api/v1/servers/{id}/restart

Destroy a server

POST /api/v1/servers/{id}/destroy

Permanently destroys the server and releases all provider resources. This action cannot be undone.

Reconcile a server

POST /api/v1/servers/{id}/reconcile

Reconciles the server's state with the cloud provider. Useful when the provider state is out of sync.

Polling for readiness

const server = await puchify.servers.waitFor("svr_123", "running", {
  timeout: 300_000,   // 5 minutes
  pollInterval: 5_000, // every 5 seconds
})

server = puchify.servers.wait_for("svr_123", "running", timeout=300)

server, err := puchify.WaitFor(ctx, client.Servers.Get, "svr_123", "running",
  puchify.WithTimeout(5*time.Minute),
)

Response shape

{
  "data": {
    "id": "svr_abc123",
    "name": "web-01",
    "status": "running",       // creating | running | stopped | destroyed
    "plan": "shared-2",
    "region": "us-east",
    "image": "ubuntu-24.04",
    "ipv4": "203.0.113.42",
    "ipv6": null,
    "created_at": "2026-05-28T10:30:00Z",
    "updated_at": "2026-05-28T10:32:00Z"
  },
  "meta": {
    "persistence": "synced",
    "provider": "connected"
  }
}

Servers API

On this page