## Provider list

`GET /v1/ai/providers`

Returns the catalog of providers available for connecting a BYOK key. Use it before [`POST /v1/ai/credentials`](/docs/ai/credentials/create) to get the correct `providerId` and learn which fields the provider expects in `credentials`.

## Parameters

No request parameters.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/ai/providers \
  -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/providers', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
data.forEach((p) => {
  const fields = Object.keys(p.credentialFields).join(', ')
  console.log(`${p.name} (${p.slug}) — required fields: ${fields}`)
})
```

### JavaScript — OAuth application

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

const { data } = await res.json()
const openai = data.find((p) => p.slug === 'openai')
console.log('OpenAI ID:', openai.id)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of providers, sorted by `name` |
| `data[].id` | string | Provider ID — use it in the `providerId` of a request to [`POST /v1/ai/credentials`](/docs/ai/credentials/create) |
| `data[].name` | string | Display name |
| `data[].slug` | string | System name of the provider: `openai`, `anthropic`, `custom-openai-compat`, etc. |
| `data[].credentialFields` | object | Description of the fields to pass in `credentials` when creating a key |
| `data[].credentialFields.<field>.type` | string | Input type: `password`, `url`, `text` |
| `data[].credentialFields.<field>.label` | string | Field label |
| `data[].credentialFields.<field>.required` | boolean | Whether it is required |
| `data[].credentialFields.<field>.placeholder` | string | Hint for an empty field |
| `data[].credentialFields.<field>.hint` | string | Hint for the user — usually the domain of the page where the key is issued |
| `data[].credentialFields.<field>.help` | string | Explanatory text for the field. Returned by the `custom-openai-compat` provider for the `baseUrl` field |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "slug": "anthropic",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    },
    {
      "id": "cprv_custom_seed",
      "name": "Custom OpenAI-Compatible",
      "slug": "custom-openai-compat",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        },
        "baseUrl": {
          "type": "url",
          "label": "Base URL",
          "required": true,
          "placeholder": "https://api.example.com/v1",
          "help": "OpenAI-compatible endpoint."
        }
      }
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "slug": "openai",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    }
  ]
}
```

## Error response example

`403 scope_missing` — the API key does not have the `vibe:ai` scope:

```json
{
  "success": false,
  "error": {
    "code": "scope_missing",
    "message": "API key does not have the vibe:ai scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 403 | `scope_missing` | The API key is missing the `vibe:ai` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |

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

## Known specifics

**The `bitrix` provider is excluded.** The list does not contain the platform provider `bitrix` — its models (BitrixGPT 5.5, GPT-OSS, Whisper, etc.) are available to everyone without connecting a BYOK key.

**Most providers require only `apiKey`.** The `baseUrl` field is required only for `custom-openai-compat`. For all other providers `baseUrl` is fixed by the platform and is not passed in `credentials`.

**The system name `custom-openai-compat` is for arbitrary services.** Use it to connect any OpenAI-compatible service: Minimax, Cerebras, Cohere, a corporate `vLLM`/`Ollama`, a local inference server. After connecting, models are either loaded automatically via [`fetch-models`](/docs/ai/credentials/fetch-models), or registered manually via [`models-add`](/docs/ai/credentials/models-add).

**The `hint` field.** For some providers the `hint` field contains the domain of the key-issuing page: `platform.deepseek.com`, `console.groq.com`, `aistudio.google.com`. Show it to the user next to the key input field.

## See also

- [Connect a key](/docs/ai/credentials/create)
- [Your own keys (BYOK)](/docs/ai/credentials)
- [AI Router](/docs/ai)