## Provider OS images

`GET /v1/infra/providers/:providerId/images`

Returns the list of operating system images a server can be launched from. The `id` value is used as the `image` parameter when [creating a server](/docs/infra/servers/create). Bitrix24 Cloud supports only Ubuntu 24.04 LTS — the image in the response is regularly updated to the latest build with security patches.

## Parameters

| Parameter | In | Type | Req. | Description |
|----------|---|-----|:-----:|----------|
| `providerId` | path | string | yes | Provider ID from [`GET /v1/infra/providers`](./list.md), e.g. `bitrix-cloud` |

## Examples

### curl — personal key

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/providers/bitrix-cloud/images
```

### curl — OAuth application

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/infra/providers/bitrix-cloud/images
```

### JavaScript — personal key

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/infra/providers/bitrix-cloud/images',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: images } = await res.json()
const defaultImage = images[0].id  // current Ubuntu 24.04 LTS build
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/infra/providers/bitrix-cloud/images',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of images |
| `data[].id` | string | Image ID, passed as `image` when creating a server. Changes when the build is updated — always take the current one from the response, do not hardcode it |
| `data[].name` | string | Image name for display to the user |
| `data[].family` | string | Image family (`ubuntu-2404-lts`) |
| `data[].version` | string | Build version |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": "fd83esfomhq25p2ono90",
      "name": "Ubuntu 24.04 lts v20260410040341",
      "family": "ubuntu-2404-lts",
      "version": "ubuntu.24.04.lts.v20260413"
    }
  ]
}
```

## Error response example

404 — unknown `providerId`:

```json
{
  "success": false,
  "error": {
    "code": "NO_CREDENTIALS",
    "message": "No credentials configured for provider nonexistent"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 404 | `NO_CREDENTIALS` | A provider with this `providerId` is not configured on the platform |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **Do not cache the `id` on the client.** The image ID changes with every build update — request a fresh one before each server creation.
- **Other OS families are not supported.** The cloud-init scripts that configure the tunnel and runtimes are designed specifically for Ubuntu 24.04 LTS. Debian, CentOS, and other distributions do not work, even if their images are directly available in Bitrix24 Cloud.
- The response is not paginated.

## See also

- [List of providers](./list.md) — `GET /v1/infra/providers`.
- [Provider plans](./plans.md) — `GET /v1/infra/providers/:providerId/plans`.
- [Provider regions](./regions.md) — `GET /v1/infra/providers/:providerId/regions`.
- [Creating a server](/docs/infra/servers/create) — the `image` parameter.