## Preview available models

`GET /v1/ai/credentials/:id/available-models`

Reads the live provider list through this key without saving models. `connected` and `rowId` refer only to this key. If the list is unavailable, the response is still `200`: `models: []` and `unavailable` with a sanitized message. You can [connect a model by name](./models-add.md).

Requires the `vibe:ai` scope. The public API accepts only your own USER key. A key owned by another user, a missing key or a PORTAL key returns `404 not_found`.

## Parameters

| Parameter | Type | Req. | Description |
|---|---|---|---|
| `id` (path) | string | yes | Key ID from the [list](./list.md) |

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/ai/credentials/cred_xyz/available-models \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/ai/credentials/cred_xyz/available-models \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/ai/credentials/cred_xyz/available-models', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data } = await res.json()
console.log(data)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/ai/credentials/cred_xyz/available-models', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    Authorization: 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log(data)
```

## Response fields

| Field | Type | Description |
|---|---|---|
| `data.models[].id` | string | Raw provider model ID |
| `data.models[].modelId` | string | Public ID `<slug>/<id>` |
| `data.models[].name` | string | Display name |
| `data.models[].contextLength` | integer | Context in tokens. Defaults to 4096 |
| `data.models[].maxOutputTokens` | integer / null | Maximum output tokens |
| `data.models[].capabilities` | object / null | Model capabilities |
| `data.models[].connected` | boolean | Already connected to this key |
| `data.models[].rowId` | string / null | ID of the key's model row, the same `id` as in the [key's model list](./models-list.md), or `null` |
| `data.unavailable` | object | Optional object: `code` is `provider_list_models_unavailable`, `message` has the key and proxy address removed |

## Response example

```json
{"success":true,"data":{"models":[{"id":"gpt-4o-mini","modelId":"openai/gpt-4o-mini","name":"GPT-4o mini","contextLength":128000,"maxOutputTokens":16384,"capabilities":{"tools":true},"connected":false,"rowId":null}]}}
```

## Error response example

`404 not_found` — the key was not found or belongs to another user:

```json
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|---|---|---|
| 400 | `no_key` | The key has no API key value |
| 400 | `base_url_redirect` | The provider returned a forbidden redirect |
| 403 | `scope_missing` | `vibe:ai` |
| 404 | `not_found` | The key is not accessible |
| 429 | `model_discovery_busy` | Another model list request is already running |
| 429 | `model_discovery_rate_limit` | The model list request rate is exceeded |
| 500 | `decryption_error` | The stored key cannot be decrypted |

For the full list of common API errors, see [Errors](/docs/errors).

## Known specifics

Model list requests share their limits across `available-models`, `fetch-models` and connection: 20 seconds including all retries and pages, up to 5 MiB per response before JSON parsing, up to 1000 models and 10 pages. A repeated cursor stops pagination. Only one such request runs per Bitrix24 account at a time, and at most 10 run per minute. Incomplete lists never change absent models to `DEPRECATED`.

## See also

- [Add a model manually](./models-add.md)
- [Fetch the model catalog](./fetch-models.md)
- [List a key's models](./models-list.md)