## Provider regions

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

Returns the list of data centers (zones) where the provider can place virtual machines. The `id` value is used as the `region` parameter when [creating a server](/docs/infra/servers/create). By default, choose the **first element of the array** — it is the platform's current fallback zone with a reserve of free IPs.

## 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/regions
```

### 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/regions
```

### JavaScript — personal key

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/infra/providers/bitrix-cloud/regions',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: regions } = await res.json()
const defaultRegion = regions[0].id  // current platform fallback
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/infra/providers/bitrix-cloud/regions',
  {
    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 regions |
| `data[].id` | string | Region ID, passed as `region` when creating a server (e.g. `bc-eu-central`) |
| `data[].name` | string | Display name for the user (e.g. `"Frankfurt (EU Central)"`) |
| `data[].country` | string | Two-letter ISO 3166-1 country code (`DE`) |

## Response example

```json
{
  "success": true,
  "data": [
    { "id": "bc-eu-central", "name": "Frankfurt (EU Central)", "country": "DE" },
    { "id": "bc-eu-west", "name": "Ireland (EU West)", "country": "IE" },
    { "id": "bc-us-east", "name": "N. Virginia (US East)", "country": "US" },
    { "id": "bc-us-west", "name": "Oregon (US West)", "country": "US" },
    { "id": "bc-ap-southeast", "name": "Singapore (AP Southeast)", "country": "SG" }
  ]
}
```

## 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

- **Switching to a backup zone when IP addresses are exhausted.** If the requested zone has run out of free IPs at the provider, when creating a server the platform automatically tries the next zones in the array in the order they appear and, in the creation response, sets `region` to the one the server actually landed in. The switch to a backup zone is recorded in the audit log as a `SERVER_ZONE_FALLBACK` event with the original and actual zones.
- 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 OS images](./images.md) — `GET /v1/infra/providers/:providerId/images`.
- [Creating a server](/docs/infra/servers/create) — the `region` parameter.