# Servers

CRUD operations for servers and an activity feed: create a new server, list your servers, fetch details of a single server by ID, update its name and description, delete a server, and a chronology of server failures. 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`
- [Server activity feed](./servers/activity.md) — `GET /v1/infra/servers/:id/activity`
- [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`
- [Unstick the channel](./servers/unstick.md) — `POST /v1/infra/servers/:id/unstick`
- [Publish to the Bitrix24 catalog](./servers/b24-catalog-publish.md) — `POST /v1/infra/servers/:id/b24-catalog/publish`

## Typical scenario

The full cycle "create → wait until ready → delete". The scenario describes a standalone virtual machine — `kind` equals `STANDALONE` in the create response. A Galaxy app (`kind` equals `GALAXY_APP`) never reaches `blackholeStatus: "CONNECTED"`. Its code is uploaded right after creation — [Galaxy app](/docs/infra/galaxy).

```javascript
// Create — returns id and 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
// or creation ends with error / sleeping
let info
do {
  await new Promise(r => setTimeout(r, 10000))
  const res = await api('GET', `/infra/servers/${server.id}`)
  info = res.data
  if (info.status === 'error' || info.status === 'sleeping') {
    throw new Error(`Server ${server.id}: ${info.status}, ${info.provisionError ?? 'no reason given'}`)
  }
} while (info.status !== 'running' || info.blackholeStatus !== 'CONNECTED')

// … then Deploy API

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

## See also

- [Lifecycle](/docs/infra/lifecycle)
- [Deploy API](/docs/infra/deploy)
- [Root section — Infrastructure](/docs/infra)