> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/llm-providers/custom.md).

# Custom

Register any OpenAI-compatible endpoint or AI gateway as a Custom LLM provider on SonarQube Server 2026.5.

Use the **Custom** provider type when you reach your models through an endpoint that exposes an OpenAI-compatible API. That covers a model service's own endpoint, an AI gateway, and a proxy you run yourself.

This page covers how to register a Custom provider so SonarQube Server can reach your endpoint and list its models. For the steps that apply to every provider type, see [LLM providers](/sonarqube-server/instance-administration/ai-features/llm-providers.md); to select this provider and choose a model for an AI agent, see [LLM providers](/sonarqube-server/instance-administration/ai-features/llm-providers.md#selecting-for-a-capability).

## Supported API <a href="#protocol" id="protocol"></a>

Your API provider must expose two OpenAI-compatible endpoints:

* `GET /models`, so SonarQube Server can list the models your provider serves
* `POST /chat/completions`, so an agent can run against the model you select

SonarQube Server calls `GET /models` when you add the provider, and `POST /chat/completions` when you select a model for an agent.

Gateways often expose an OpenAI-compatible API on one path and their own format on another, and some expose it only in certain configurations. Check your provider's documentation for the base URL to use, and for any headers that path requires.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* An endpoint that exposes an OpenAI-compatible API, serving both `GET /models` and `POST /chat/completions`.
* A credential for that endpoint, usually an API key, unless the endpoint authenticates another way.

## Fields <a href="#fields" id="fields"></a>

| Field              | Required | What to enter                                                                                                                                             |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**       | Yes      | The base URL, including the version path if your provider uses one. Don't include `/models` or `/chat/completions`; SonarQube Server appends those paths. |
| **API key**        | No       | The credential for the endpoint. Leave it empty if your endpoint authenticates another way.                                                               |
| **Custom headers** | No       | Any headers your provider or gateway requires, as name and value pairs. Mark a value as secret to hide it after you save.                                 |

## Example endpoints <a href="#reference-values" id="reference-values"></a>

Enter the values your own provider documents. The notes after the table cover the providers that need more than an endpoint and a key.

| Provider or gateway                                               | Endpoint                                                                                                                                              | Authentication                                                                                                           |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Portkey                                                           | `https://api.portkey.ai/v1`                                                                                                                           | API key generated in Portkey                                                                                             |
| OpenRouter                                                        | `https://openrouter.ai/api/v1`                                                                                                                        | API key generated in OpenRouter                                                                                          |
| Azure AI Foundry through APIM, with a header other than `api-key` | Your APIM base URL. See [Azure AI Foundry](/sonarqube-server/instance-administration/ai-features/llm-providers/azure-ai-foundry.md#azure-apim-fields) | Your APIM subscription-key header name and value, marked as secret. Check your own APIM policy for the exact header name |
| Self-hosted gateway                                               | Your own OpenAI-compatible base URL, for example `https://litellm.internal.example.com/v1`                                                            | API key or a custom header, depending on how you configured the gateway                                                  |

For a direct connection to Azure AI Foundry, or for an APIM policy that uses the `api-key` header, use the dedicated **Azure AI Foundry** type instead; see [Azure AI Foundry](/sonarqube-server/instance-administration/ai-features/llm-providers/azure-ai-foundry.md). To reach OpenAI or Anthropic's own API directly, or AWS Bedrock Mantle, use their dedicated provider types instead; see [LLM providers](/sonarqube-server/instance-administration/ai-features/llm-providers.md#choosing-a-provider-type).

### Portkey <a href="#portkey" id="portkey"></a>

In Portkey, configure your API key for the specific provider that serves the model you plan to select. A key with no provider configured, or one configured for a different provider, fails when you select a model in SonarQube Server.

## Entering the endpoint <a href="#endpoint" id="endpoint"></a>

Enter the base URL exactly as your provider documents it, including any version path. A self-hosted gateway, for example, might expose `https://litellm.internal.example.com/v1`. See [#reference-values](#reference-values "mention") for the endpoints documented for supported gateways.

## Authenticating with a header <a href="#header-authentication" id="header-authentication"></a>

If your provider or gateway authenticates through a header rather than a bearer token, leave **API key** empty in SonarQube Server and add the header under **Custom headers**. Mark the value as secret so it's hidden after you save.

## Entering the model identifier <a href="#model-identifier" id="model-identifier"></a>

Naming conventions differ from one provider and gateway to the next, and some gateways let you define your own model names.

1. Find the model in your provider or gateway's model catalog.
2. Copy the identifier exactly as your provider or gateway names it.
3. In SonarQube Server, go to the agent's page under **Administration** > **Configuration** > **AI capabilities**, paste the identifier into the model field, and select **Save**.

Copy the identifier from your own catalog rather than from another organization's examples.

If adding the provider fails, see [LLM providers](/sonarqube-server/instance-administration/ai-features/llm-providers.md#troubleshooting).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/llm-providers/custom.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.