## 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 and returns it under the stable family id `ubuntu-2404-lts`: the same `id` is returned for every build, while the platform resolves that family to the latest build with security patches at the moment the server is created.

## Parameters

| Parameter | In | Type | Required | 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  // 'ubuntu-2404-lts' — the stable Ubuntu 24.04 LTS family id
```

### 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. For Bitrix24 Cloud it is the family slug `ubuntu-2404-lts` (equal to `data[].family`) and stays the same across build updates. Other providers can return their own opaque ids, so read the value from the response instead of assuming the slug |
| `data[].name` | string | Image name for display to the user |
| `data[].family` | string | Image family (`ubuntu-2404-lts`) |
| `data[].version` | string | OS version; for Bitrix24 Cloud it is the release `24.04` and does not identify a build |

## Response example

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

## 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` | The key is not recognized — no such key exists on the platform |
| 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

- **The `id` is a stable family slug, not a per-build value.** Bitrix24 Cloud returns `ubuntu-2404-lts` for every build of Ubuntu 24.04 LTS, so the `id` never changes and cannot be used to detect that a new build has been published. The concrete current build is resolved on the platform side when the server is created, so passing this `id` — or omitting `image` entirely — always launches the latest build.
- **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)
- [Provider plans](./plans.md)
- [Provider regions](./regions.md)
- [Creating a server](/docs/infra/servers/create)