> ## Documentation Index
> Fetch the complete documentation index at: https://reaperagent.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Endpoint
> Connect Reagent to your organization's AI model endpoint, choose its options, and fix endpoint errors
On an Enterprise account, Reagent sends all its AI requests to an endpoint your organization chooses, instead of Reagent's hosted models. The endpoint can be a model gateway (a service that passes requests on to AI models), a cloud provider, or a model server on your own computer. Free trials and individual plans use Reagent's hosted AI models, so they never see the **Custom Endpoint** window or **Settings > Endpoint**. If you're the IT admin choosing the endpoint and model, start with [For IT Admins](#for-it-admins).
## Before You Start
You need Reagent 0.15.1 or later, signed in with your work email (see [Single Sign-On](/docs/enterprise/sso)). Ask your IT team for:
* **Endpoint URL**: the base address of your organization's AI endpoint.
* **API key**: the key or token for that endpoint.
* **Model ID**: the exact name of the model to use.
* Any options they want changed from the defaults.
If the endpoint is only reachable on your organization's network, connect to that network or your VPN first.
## Connect Your Endpoint
The **Custom Endpoint** window opens after you sign in (and, the first time, answer the welcome questions) whenever this computer has no saved endpoint. That's the first time you sign in on a computer, after you sign out (**Log out** in the menu under your name, or **Sign out** in this window) or your sign-in session ends, and after you click **Clear** in **Settings > Endpoint**.
The window reads "Connect Reagent to your organization's OpenAI-compatible model gateway." You can't chat, or close it, until an endpoint passes the test. To leave without connecting, click **Sign out**.
Paste the base URL, for example `https://openrouter.ai/api/v1`. Don't add `/chat/completions` or `/responses`. Reagent adds those itself.
Paste the key or token. Type the model ID exactly as your endpoint lists it, including any vendor prefix, such as the `openai/` in `openai/gpt-5.4`.
Leave **Provider**, **API** and **Reasoning effort** on their defaults unless your IT team says otherwise. **Max output tokens** and **Context window** are under **Advanced**. See [Fields and Options](#fields-and-options).
Reagent tests the endpoint before it saves anything. On a pass, the window shows **Connected**, any [warnings](#apply-passed-with-a-warning), and the API it will use, such as "Reagent will use your endpoint's Chat Completions." Chat Completions and the Responses API are two request formats that OpenAI-compatible services offer.
If the test fails, Reagent saves nothing and shows the error under **Apply**. See [Troubleshooting](#troubleshooting).
The window closes and you can start using Reagent.
## Change or Clear Your Endpoint
1. Open **Settings** (click your name at the bottom of the sidebar and choose **Settings**, or press `Cmd+,` on macOS / `Ctrl+,` on Windows) and choose **Endpoint**. It replaces the **Subscription** tab.
2. Under **Connection**, change the fields you need. They match the **Custom Endpoint** window. The saved API key isn't shown again: the field reads "Saved API key (leave blank to keep)", so fill it in only to replace the key.
3. Click **Apply**. Reagent re-tests the endpoint and, on a pass, shows the API it uses, such as "Connected — using Chat Completions." Changes apply from the next request.
Once an endpoint is saved, **Connection** also shows a **Detected** line. See [What the Detected line shows](#what-the-detected-line-shows).
To remove the saved endpoint, go to **Settings > Endpoint** and, under **Credentials**, click **Clear** next to **Saved endpoint credentials**. Confirm with **Clear credentials**. Reagent forgets the URL, API key, model ID and options on this computer, and the **Custom Endpoint** window opens again.
Reagent saves your endpoint settings, API key included, on this computer only:
* **Encrypted.** They're saved in Reagent's app data folder (`enterprise-config.enc`), encrypted with your operating system's secure storage.
* **Warned if encryption isn't available.** If the operating system can't provide encryption, the **Custom Endpoint** window and **Settings > Endpoint** show "Encryption is unavailable on this system. Credentials will be stored as plain text in `/enterprise-config.json`."
* **Per computer.** Settings aren't synced between computers.
* **Cleared on sign out.** Reagent deletes them when you sign out or your sign-in session ends, and when you click **Clear**.
## Fields and Options
Output limits and context sizes are measured in tokens, the small chunks of text a model reads and writes.
| Field | What to enter |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Endpoint URL** | Required. The base URL of the endpoint's OpenAI-compatible API, usually ending in a version path such as `/v1`. |
| **API key** | Required. The key or token. Reagent uses it only to authenticate its requests to your endpoint. |
| **Model ID** | Required. The model's ID as your endpoint names it. |
| **Provider** | **Auto-detect**, **Anthropic**, **OpenAI**, **Gemini** or **Other**. Default: **Auto-detect**. |
| **API** | **Auto**, **Chat Completions** or **Responses API**. Default: **Auto**. |
| **Reasoning effort** | **Model default**, **None**, **Low**, **Medium**, **High** or **Extra high**. Default: **Model default**. |
| **Max output tokens** (under **Advanced**) | A whole number above zero. Leave it empty to use the model's default. |
| **Context window** (under **Advanced**) | The model's context size in tokens, as a whole number above zero. Leave it empty to use a default based on the model ID. |
How Reagent uses each field (**Context window** has its own section below):
Reagent recognizes a model family from the part of the ID after the last `/` (`openai/gpt-5.4` reads as `gpt-5.4`). The family decides which API **Auto** picks, which **Reasoning effort** values Reagent sends, and the default **Context window**.
Reagent can't recognize:
* **A gateway alias that doesn't name the model.** Set **API** and **Context window** yourself.
* **Claude IDs in other formats**, such as `us.anthropic.claude-…`. Set **Context window** and **Max output tokens** yourself, and leave **Reasoning effort** on **Model default** (see [Reasoning effort](#reasoning-effort)).
**Provider** only changes how Reagent formats its tool definitions for Gemini models. **Auto-detect** reads the model ID: an ID containing `claude` counts as Anthropic, `gpt` as OpenAI, `gemini` as Gemini, and anything else as Other.
Choose **Gemini** for a Gemini model whose ID doesn't contain "gemini". Otherwise, leave it on **Auto-detect**.
**Auto** picks the API for each model after testing the endpoint. **Chat Completions** or **Responses API** always uses that one. If you choose **Responses API** and the endpoint doesn't provide it for your model, the test fails.
With **API** on **Auto**, recognized OpenAI reasoning models use the Responses API when your endpoint provides it for that model, and Chat Completions otherwise. Every other model uses Chat Completions. Reagent recognizes model IDs that:
* start with `gpt-5` (except `-chat` variants), `gpt-6`, or `o` followed by a digit (such as `o3`)
* contain `codex`
* are GPT models whose ID includes `-pro`
On the Responses API, these models can use tools with reasoning on, and carry their reasoning from one tool call to the next.
How much the model reasons before it answers, for models that support it. Reagent sends your choice only to models that accept that value; others get none and use their default. Two exceptions:
* Model IDs that start with `claude` (after any prefix) never receive a reasoning effort on Chat Completions.
* Model IDs Reagent doesn't recognize receive your choice unchanged.
Your choice applies to the main chat and the Wwise subagent. For chat titles, long-chat summaries and the Analyst (a helper that works through large results), Reagent asks OpenAI reasoning models and Gemini models for the lowest reasoning effort they accept, so these tasks stay quick. Other models get no reasoning effort for them and use their default.
Caps the length of each response: Reagent never asks for more in one response. Empty uses the model's default, except for model IDs that start with `claude` on Chat Completions.
For those, Reagent asks for up to 32,000 tokens per response, because some gateways otherwise apply a much lower limit and cut responses short. If a model rejects that default, Reagent stops sending it.
### Context Window
How much conversation the model can take in. Reagent uses it for the context ring next to the send button and to decide when to summarize a long chat. It doesn't limit what your endpoint accepts.
When the field is empty, Reagent uses a default based on the model ID:
| Model ID (after any prefix) | Default context window |
| -------------------------------------------------------------------------------- | ---------------------- |
| Starts with `claude` | 200,000 tokens |
| Starts with `gemini` | 1,000,000 tokens |
| `gpt-5.4` and later GPT-5 versions, and `gpt-6` | 1,050,000 tokens |
| Other GPT-5 models, such as `gpt-5` or `gpt-5.1` | 400,000 tokens |
| Other recognized OpenAI reasoning models, such as `o3` | 200,000 tokens |
| Anything else, including `gpt-oss`, GPT-5 `-chat` variants and most local models | 128,000 tokens |
Set it when your model's real limit differs, especially for local models with small windows. Too large a value lets a chat run past what the model accepts before Reagent summarizes it. Whatever the window, Reagent starts summarizing at 50,000 tokens at the earliest, so choose a model whose window is well above that.
Hover over the context ring to see how much of the window the chat uses. If your endpoint doesn't report token usage while streaming, Reagent estimates it and the tooltip adds "(estimated — this endpoint reports no usage)".
## For IT Admins
* **One model for everything.** The model in **Model ID** handles every request Reagent sends to a language model: your chats, the Wwise subagent, the Analyst, chat titles, and long-chat summaries. There's no separate model for smaller tasks. To switch models, change **Model ID** in **Settings > Endpoint** and click **Apply**.
* **Features that need Reagent's servers.** Some features rely on Reagent's own servers and aren't offered on Enterprise accounts, whichever model you connect. See [Feature Availability](/docs/enterprise/overview#feature-availability).
* **Prompt caching.** Both the **Custom Endpoint** window and **Settings > Endpoint** say "Prompt caching is unavailable through custom endpoints." The prompt caching Reagent uses on its hosted service doesn't apply to your endpoint, so long chats can be slower and cost more on your provider's bill. Whether your provider caches prompts on its own is up to your provider.
* **Responses API requests.** Reagent sends the conversation with each request and sets `store: false`, so your endpoint isn't asked to keep conversation state between requests. It includes the chat's ID as `prompt_cache_key` on main chat requests (not on subagent, title or summary requests), which supporting providers can use to group a chat's requests.
### What the Endpoint Needs
| Requirement | Details |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OpenAI-compatible API | Chat Completions (`/chat/completions`), with streamed responses. |
| Responses API (optional) | `/responses`. With **API** on **Auto**, Reagent uses it only for recognized OpenAI reasoning models (see [API](#api)). An endpoint that serves only `/responses` works only with **API** set to **Responses API**. |
| Tool calling | Reagent works by calling tools, such as reading a REAPER project or editing items. Choose a model with strong tool-calling support. |
| HTTPS | Required, except for a server on the same computer as Reagent (`localhost`, `127.0.0.1` or `0.0.0.0`), which can use plain `http://`, for example `http://localhost:11434/v1`. |
| API key or token | Required, even for a local server. If it doesn't check keys, enter any placeholder. Sent in the standard `Authorization: Bearer` header. |
| Reachable from each member's computer | The app calls the endpoint from the computer it runs on. |
| Works with | OpenAI-compatible endpoints that meet these requirements. The app's compatibility note names the gateways and providers TrueFoundry, LiteLLM, OpenRouter, Azure OpenAI and Together.ai, and the model servers Ollama and vLLM. |
On Chat Completions, `gpt-5.4` and later GPT-5 versions, and `gpt-6`, refuse tools unless reasoning is off, so Reagent turns reasoning off for them and shows a warning. `gpt-6` can't turn reasoning off, so it works only through the Responses API. For these models, make sure your gateway provides `/responses`.
### What Apply Checks
Reagent first checks the fields, then sends a few short test requests and notes whether the endpoint reports token usage while streaming. The test doesn't touch REAPER or your project.
1. **Simple request:** a one-word reply on Chat Completions confirms the URL, key and model ID work. Skipped when **API** is **Responses API**; step 2 does the same check.
2. **Responses API** (recognized OpenAI reasoning models on **Auto**, or when you chose **Responses API**): does the endpoint provide it for this model?
3. **Tool call:** a streamed request with one test tool, like a real chat step. Does the model call it?
4. **Follow-up request:**
* **Responses API:** if the model called the test tool, Reagent sends the result back with the model's reasoning, to check that your endpoint accepts reasoning carried from one step to the next.
* **Chat Completions:** Reagent repeats the tool request and asks the endpoint to report token usage while streaming.
If both the Chat Completions and Responses paths answer "not found", Reagent tries once more with `/v1` added to your URL and keeps it if that works. Any step is retried once after a temporary failure, such as a timeout, a rate limit (429) or a server error (5xx). If a step still fails, Reagent saves nothing and shows your endpoint's own error under **Apply**.
For the field errors and warnings **Apply** can show, see [Troubleshooting](#troubleshooting).
## Troubleshooting
Make changes in the **Custom Endpoint** window during setup, or in **Settings > Endpoint** once connected. Some messages call the **Apply** button "Test & Apply".
Reagent checks the fields before it sends any request. **Apply** can stop with:
* "Endpoint must be a valid URL"
* "Endpoint must use HTTPS unless it targets localhost, 127.0.0.1, or 0.0.0.0"
* "API key is required"
* "Model ID is required"
* "Max output tokens must be a whole number above zero"
* "Context window must be a whole number above zero"
During setup, the error under **Apply** adds "This endpoint may only be reachable from your organization's network or VPN." In chat, an error box reads "Can't reach your organization's model endpoint."
Connect to your organization's network or VPN, check the **Endpoint URL** with your IT team (for a local server, check that it's running at that address), then click **Apply** again.
If the test times out, the endpoint answered too slowly. A local server may still be loading the model. Wait, then click **Apply** again.
The URL doesn't point at the endpoint's OpenAI-compatible API.
* Use the base URL, usually ending in a version path such as `/v1`, without `/chat/completions` or `/responses`. For OpenRouter, use `https://openrouter.ai/api/v1`.
* "Check the base URL and the model ID": the endpoint may not serve that model ID. Check **Model ID** too.
* "The Responses API is not available for this model on this endpoint": set **API** to **Auto** or **Chat Completions**, or ask your gateway admin to enable `/responses` for the model.
* "Check the endpoint URL and provider API path": the URL returned a web page instead of an API response.
Under **Apply**, or in chat as an error box reading "Your organization's model endpoint returned", the message shows the status code and your endpoint's own explanation. A hint follows when Reagent can explain the failure.
| Status | Usual cause and fix |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 or 403 | The API key isn't accepted, or has no access to that model. Check the key with your IT team, paste it again, and click **Apply**. |
| 429 | Your provider's rate limit. Reagent's own credit and rate-limit banners don't appear, because limits and costs come from your provider. Wait and try again, or ask your admin about the limit. |
| 500 and above | A problem at the provider or gateway. Try again later. |
Give the text under **Endpoint response** (the endpoint's raw response, or its message when it sent no body) to your gateway admin.
A warning means the endpoint works and Reagent saved it, with a caveat:
* **"Your endpoint's Responses API could not be used for this model (…), so Reagent uses Chat Completions."** The endpoint has no Responses API Reagent can use for this OpenAI reasoning model, and the reason is in parentheses. You can leave it, or ask your gateway admin to enable `/responses` for the model, then click **Apply** again.
* **"The model accepted tools but did not call one, so Reagent's tools may not work with it."** The model answered without calling the test tool, so it may chat without acting on your project. Choose a model with stronger tool calling.
* **"This model only runs tools on Chat Completions with reasoning turned off, so Reagent will use it without reasoning."** The model refused tools with reasoning on. If your endpoint provides the Responses API for this model, set **API** to **Responses API** and click **Apply** again to keep reasoning on.
* **"Your endpoint's Responses API returns reasoning without its encrypted content…"** or **"Your endpoint could not use replayed reasoning…"** Reagent can't carry the model's reasoning between tool calls, so the model reasons afresh at each step. There's nothing to do: Reagent handles it.
The message reads "The endpoint passed the test, but Reagent could not save its settings" and gives the reason. If another program had the file open, click **Apply** again. If it keeps failing, send the full message to [Reagent support](https://www.reaperagent.com/contact).
If **Apply** warned that the model accepted tools but didn't call one, see [Apply passed with a warning](#apply-passed-with-a-warning).
If an error says the model refuses Reagent's tools on Chat Completions while reasoning is on, or "can only run Reagent's tools through the Responses API", ask your gateway admin to enable `/responses` for the model. Then set **API** to **Auto** (or **Responses API** if Reagent doesn't [recognize your model ID](#api)) and click **Apply**.
The response probably hit an output limit.
* If you set **Max output tokens**, raise or clear it.
* If it's empty, your gateway may apply its own low default. Set it to a value your model supports.
* If the model rejects your value ("The model rejected the output-token cap. Lower or clear Max output tokens.", or a message naming the value Reagent sent from your settings), lower or clear it.
Reagent may be assuming a larger window than your model has. Set [**Context window**](#context-window) under **Advanced** to the model's real limit and click **Apply**.
Reagent starts summarizing a chat at 50,000 tokens at the earliest, so a model with a smaller window can run out of room first. Use a model with a larger window, or start a new chat.
Once an endpoint is saved, the **Detected** line under **Connection** in **Settings > Endpoint** shows the API Reagent uses for your model, such as "Responses API — reasoning on" or "Chat Completions — reasoning off". Notes under it explain why, for example that the endpoint doesn't report token usage while streaming, or why reasoning is off and which **API** setting could turn it back on.
If your endpoint refuses a request in a way Reagent knows how to fix (it rejects an option Reagent sent, or needs a different API for your model), Reagent retries once with adjusted settings and remembers the change. The **Detected** line then notes "Changed after the last test" and suggests clicking **Apply** to re-test.
## Related
How Enterprise accounts work and which features differ.
Sign in with your company account.
Where your conversation goes on an Enterprise account.
Fixes for common problems.