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.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”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
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.
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.
One saved provider. The inference clients don’t use its settings.
object
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.
The saved provider kind. An empty or unknown kind is rejected on save. Changing it doesn’t choose or rebuild an inference client.
Saved on/off flag. It doesn’t start or stop any inference client. Left out or null on save, it becomes false.
Saved display name. An empty one is rejected; spaces are kept as sent, and a name of only spaces is accepted.
Saved model name. It isn’t checked with the provider or used by the inference clients. Left out of responses when empty.
Saved endpoint address. It isn’t contacted or checked, and the inference clients don’t use it. Left out of responses when empty.
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.
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.
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
Saved sampling temperature. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.
Saved top-p sampling cutoff. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.
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.
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.
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.
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.
Responses
Section titled “ Responses ”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
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.
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.
One saved provider. The inference clients don’t use its settings.
object
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.
The saved provider kind. An empty or unknown kind is rejected on save. Changing it doesn’t choose or rebuild an inference client.
Saved on/off flag. It doesn’t start or stop any inference client. Left out or null on save, it becomes false.
Saved display name. An empty one is rejected; spaces are kept as sent, and a name of only spaces is accepted.
Saved model name. It isn’t checked with the provider or used by the inference clients. Left out of responses when empty.
Saved endpoint address. It isn’t contacted or checked, and the inference clients don’t use it. Left out of responses when empty.
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.
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.
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
Saved sampling temperature. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.
Saved top-p sampling cutoff. Left out of responses when not set; an explicit 0 is kept. The stated range isn’t checked.
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.
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.
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.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed