Skip to content

Save AI provider settings

PATCH
/admin/system/ai

Replaces the saved provider list and default selection, then returns what was saved, without API keys.

The app’s inference clients don’t use these settings.

You need system.ai.write or system.admin for the whole install; a permission held only for a team doesn’t count, and read permission alone isn’t enough. A body that can’t be decoded into the request shape gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

Send every provider you want to keep, each with its existing id. An omitted, null or empty provider list clears the list, and an omitted or empty default selection clears the selection, so a body of {} or null saves an empty configuration. Each provider’s fields and its whole config block are replaced, not merged, and unknown fields are ignored.

For a provider whose id matches a saved one, an omitted, null or empty api_key keeps the stored key, and a non-empty one replaces it. A kept provider’s key can’t be cleared on its own; removing the provider removes its key. A provider sent without an id, or with a null or empty one, gets a new ID and no key from any other entry. Keys are stored as plain strings in the settings JSON, and responses show api_key_set instead of api_key.

Each provider needs an allowed kind and a non-empty display_name, IDs must differ, and a non-empty default selection must match a provider in this request; otherwise you get a JSON 400. The declared number ranges aren’t checked, and no provider is contacted to check its address, model or key. If the saved settings can’t be read first, you get a plain-text 500 and nothing is saved. Errors while saving also get a JSON 400, including database errors.

There’s no version check: concurrent saves can overwrite each other, and one can restore a key that another save replaced or removed. The response shows what this request saved, not a fresh read. Auditing is attempted after the save and isn’t guaranteed, and the audit record leaves out the provider details.

Saved AI provider settings. The app’s inference clients don’t read this list or its default selection. API keys are stored as plain strings in the settings JSON and are never returned.

object
default_provider_id

The saved default provider. Left out of responses when empty. On save, leave it out or send an empty string to clear it; a non-empty value must match an id in the list you send. It doesn’t choose a provider for the inference clients.

string
providers
required

The complete saved list, in saved order. Send every provider you want to keep. On save, an omitted, null or empty list clears it, even though the field is marked required.

Array<object>

One saved provider. The inference clients don’t use its settings.

object
id

Matches this provider to its stored key, so keep it when editing. Leave it out, or send null or an empty string, to get a new ID generated by the server. An ID you send needn’t be a UUID, but the IDs in one request must differ.

string
kind
required

The saved provider kind. An empty or unknown kind is rejected on save. Changing it doesn’t choose or rebuild an inference client.

string
Allowed values: openai anthropic google local
enabled
required

Saved on/off flag. It doesn’t start or stop any inference client. Left out or null on save, it becomes false.

boolean
display_name
required

Saved display name. An empty one is rejected; spaces are kept as sent, and a name of only spaces is accepted.

string
model

Saved model name. It isn’t checked with the provider or used by the inference clients. Left out of responses when empty.

string
base_url

Saved endpoint address. It isn’t contacted or checked, and the inference clients don’t use it. Left out of responses when empty.

string
api_key

Write-only. For a provider whose id matches a saved one, leave it out or send null or an empty string to keep the stored key, or send a new key to replace it. It’s never returned, not even to system.admin. A new ID doesn’t inherit a key.

string format: password
api_key_set

True when this provider has a stored key that isn’t empty. Returned by both the read and the save; ignored if you send it.

boolean
config

Saved options for one provider. The inference clients don’t use them. The whole block is replaced on save, unknown members are dropped, and the declared number ranges aren’t enforced.

object
temperature

Saved sampling temperature. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.

number
<= 2
top_p

Saved top-p sampling cutoff. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.

number
<= 1
max_output_tokens

Saved output-token limit. Left out of responses when not set or 0; negative values are accepted. It doesn’t limit any current inference request.

integer
system_prompt

Saved system prompt. Left out of responses when empty. Anyone who can read these settings can see it, and it isn’t applied to current inference requests.

string
request_timeout_seconds

Saved timeout, in seconds. Left out of responses when not set or 0; negative values are accepted. It doesn’t time out any current inference request.

integer
rate_limit_rpm

Saved requests-per-minute limit. Left out of responses when not set or 0; negative values are accepted. It doesn’t throttle any current inference request.

integer

The AI provider settings saved by this request.

Saved AI provider settings. The app’s inference clients don’t read this list or its default selection. API keys are stored as plain strings in the settings JSON and are never returned.

object
default_provider_id

The saved default provider. Left out of responses when empty. On save, leave it out or send an empty string to clear it; a non-empty value must match an id in the list you send. It doesn’t choose a provider for the inference clients.

string
providers
required

The complete saved list, in saved order. Send every provider you want to keep. On save, an omitted, null or empty list clears it, even though the field is marked required.

Array<object>

One saved provider. The inference clients don’t use its settings.

object
id

Matches this provider to its stored key, so keep it when editing. Leave it out, or send null or an empty string, to get a new ID generated by the server. An ID you send needn’t be a UUID, but the IDs in one request must differ.

string
kind
required

The saved provider kind. An empty or unknown kind is rejected on save. Changing it doesn’t choose or rebuild an inference client.

string
Allowed values: openai anthropic google local
enabled
required

Saved on/off flag. It doesn’t start or stop any inference client. Left out or null on save, it becomes false.

boolean
display_name
required

Saved display name. An empty one is rejected; spaces are kept as sent, and a name of only spaces is accepted.

string
model

Saved model name. It isn’t checked with the provider or used by the inference clients. Left out of responses when empty.

string
base_url

Saved endpoint address. It isn’t contacted or checked, and the inference clients don’t use it. Left out of responses when empty.

string
api_key

Write-only. For a provider whose id matches a saved one, leave it out or send null or an empty string to keep the stored key, or send a new key to replace it. It’s never returned, not even to system.admin. A new ID doesn’t inherit a key.

string format: password
api_key_set

True when this provider has a stored key that isn’t empty. Returned by both the read and the save; ignored if you send it.

boolean
config

Saved options for one provider. The inference clients don’t use them. The whole block is replaced on save, unknown members are dropped, and the declared number ranges aren’t enforced.

object
temperature

Saved sampling temperature. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.

number
<= 2
top_p

Saved top-p sampling cutoff. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.

number
<= 1
max_output_tokens

Saved output-token limit. Left out of responses when not set or 0; negative values are accepted. It doesn’t limit any current inference request.

integer
system_prompt

Saved system prompt. Left out of responses when empty. Anyone who can read these settings can see it, and it isn’t applied to current inference requests.

string
request_timeout_seconds

Saved timeout, in seconds. Left out of responses when not set or 0; negative values are accepted. It doesn’t time out any current inference request.

integer
rate_limit_rpm

Saved requests-per-minute limit. Left out of responses when not set or 0; negative values are accepted. It doesn’t throttle any current inference request.

integer

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed