Inconsistent /v1 requirement in Posit Assistant's custom provider base URL

[AdaemmerP]

There's an inconsistency in how Posit Assistant handles the base URL for custom providers:

• When configuring a custom provider through the Assistant's "Configure AI providers", the base URL must not end in /v1 -- including it triggers a validation error.
• However, the OpenAI-standard chat completions endpoint (and the API itself) requires the base URL to end in /v1. Our endpoints are also set in that way.
• The only workaround we have found is to complete setup through the UI, then manually edit providers.json and append /v1 to the baseURL afterward. Requests only work correctly once this manual edit is made.

Question 1
Is the UI's rejection of a trailing /v1 a bug, or is this intended behavior (with manual editing of providers.json expected as a workaround)? If intended, could you explain why the UI disallows /v1 when the underlying API requires it . Is the /v1 appended automatically somewhere downstream, and if so, why doesn't that happen for custom providers?

Question 2
Separately: is there a supported way to store the API token via the filesystem or providers.json directly, rather than through the UI? We're aware of the security tradeoffs, but we'd like to enable the Assistant for students ahead of a full launch, and provisioning tokens outside the UI would help with that rollout.

[juliasilge]

Thanks for the clear write up, @AdaemmerP! The short answer to your first question is that the /v1 in providers.json is correct. It is not a workaround, and the dialog is wrong to push back on it.

For a custom OpenAI-compatible provider, Positron uses the base URL exactly as you write it. Model discovery requests <baseUrl>/models, chat requests go to <baseUrl>/chat/completions, and nothing adds a version segment for you. Positron adds /v1 in only two cases. The first is a small set of known public hosts, such as https://api.openai.com. The second is the LiteLLM and Portkey providers, which normalize the URL themselves. A custom gateway is neither, so its base URL must carry /v1.

The JSON schema for providers.json says the same thing. Some providers need a version segment, and a bare host fails for those.

Where the rejection probably comes from

There is no format rule in Positron that rejects a trailing /v1. We read both the form schema and the file schema, and both accept it. The message you saw is more likely the key check that runs when you save the provider. That check sends a POST to <baseUrl>/chat/completions with a placeholder model and an empty message list. It then reads the status code. A 404 passes and is ignored. A 401 or 403 becomes "Invalid API key". Any other error becomes "Unable to validate credentials (HTTP n)".

This can invert the result you expect. A base URL without /v1 reaches a path that does not exist, returns 404, and is accepted in silence. A base URL with /v1 reaches the real endpoint, which then judges the placeholder request and can refuse it. We have seen this same check misreport a working /v1 endpoint before, in #13489.

What would help us confirm this is if you can:

1. Share the exact error text from the dialog.
2. Share your Positron version and build number.
3. Open the Output panel, select the "Authentication" channel, and send any line that starts with [Custom Provider].

For your second question, Positron stores API keys in the OS credential store, so providers.json cannot hold one.

There is, however, an environment variable path for the built-in OpenAI-compatible provider. Try setting OPENAI_COMPATIBLE_BASE_URL and OPENAI_COMPATIBLE_API_KEY. Positron reads both, and no student then has to open the dialog. This works for the built-in provider only, as a named custom entry has no per-entry variable for its key.

[AdaemmerP]

Thanks a lot for taking the time and for the detailed explanation, @juliasilge!

Here's what I see (Positron 2026.09.0):

• URL without /v1: saving works without any error, but chat requests only work once I add /v1 in providers.json.
• URL with /v1 + real API key: the dialog shows "Could not validate credentials within 10 seconds."
• URL with /v1 + random text as key: I accidentally pasted multi-line text as the key. Saving succeeded without any error, but chatting then failed with Error making request (HTTP 400): malformed auth header.
• Output → Authentication: no [Custom Provider] lines, even at Trace level. The only entry is:
  2026-09-23 12:23:58.056 [info] Provider action: "save" for provider "openai-compatible"

So the check seems to time out with the real key, while it accepts a key that the gateway actually rejects.

[juliasilge]

Thank you! I opened #16194 for us to track and prioritize this fix.