# Servers

CRUD operations for servers: create a new server, list your servers, fetch details of a single server by ID, update its name and description, and delete a server. A created server is always in Black Hole mode — invisible from the internet, with access to the application only via an HTTPS subdomain.

Scope: `vibe:infra`

## Operations

- [Create a server](./servers/create.md) — `POST /v1/infra/servers`
- [List servers](./servers/list.md) — `GET /v1/infra/servers`
- [Get a server](./servers/get.md) — `GET /v1/infra/servers/:id`
- [Update the server name and description](./servers/update.md) — `PATCH /v1/infra/servers/:id`
- [Delete a server](./servers/delete.md) — `DELETE /v1/infra/servers/:id`

## Typical scenario

The full cycle "create → wait until ready → delete":

```javascript
// Create — returns id, SSH credentials (needed when switching to OPEN mode), subdomain
const { data: server } = await api('POST', '/infra/servers', {
  provider: 'bitrix-cloud', name: 'my-app',
  plan: 'bc-small', region: 'bc-eu-central', image: 'ubuntu-2404-lts',
})

// Poll status every 10 seconds until it becomes running + CONNECTED
let info
do {
  await new Promise(r => setTimeout(r, 10000))
  const res = await api('GET', `/infra/servers/${server.id}`)
  info = res.data
} while (info.status !== 'running' || info.blackholeStatus !== 'CONNECTED')

// … then Deploy API

// When the work is done — delete. The virtual machine is deleted on the provider side
await api('DELETE', `/infra/servers/${server.id}`)
```

## See also

- [Lifecycle](/docs/infra/lifecycle) — `start`/`stop`/`sleep`/`wake`/`repair` without deletion.
- [Deploy API](/docs/infra/deploy) — the next step after creation: deploying code.
- [Root section — Infrastructure](/docs/infra) — overview, limits, statuses, errors.