Replace the AI inference settings
PUT /admin/ai/config
Replaces all of the AI inference settings and returns them. Send
every field: one left out is saved as empty, off or 0, and leaving
out privacy turns the privacy lock off.
You need ai.admin or system.admin for the whole install; a
permission held only for a team doesn’t count. A body that can’t be
decoded into the request shape, such as one with a value of the
wrong type like a fraction for a limit, gets a plain-text 400, even
when you aren’t signed in. Otherwise signed-out callers get 401 and
callers without the permission 403.
The save is refused with 422, and nothing is saved, when routing
doesn’t name a provider for each of the five tasks (complete,
embed, transcribe, tag and caption), or when the privacy
lock is on with no local_providers. That’s all that’s checked:
provider names aren’t matched against anything, task names you add
are saved but dropped when the settings are read, fallback lists and
negative limits are accepted, and turning enabled off doesn’t skip
the checks. Unknown fields are ignored.
All six settings are saved in one transaction, so they change together or not at all. An error while saving gets a plain-text 500, but it doesn’t show that nothing was saved, so read the settings again before retrying. There’s no version check: when two saves overlap, the one that commits last wins whole, which isn’t necessarily the one that answers last. The response is read back after the save, so it can show values from another save made at the same time. A save isn’t recorded in the audit log.
How the saved settings are used:
enabledisn’t read by anything yet, so turning it off doesn’t stop any AI feature.routing,fallback_chainsandlocal_providerschoose the providers for AI jobs such as embedding and transcription, once each server has refreshed its copy, which a save asks every server to do. Only providers a server set up when it started can be used; other names are skipped without a finding.lock_sensitive_to_localis read when a server starts, so a change needs a restart.- The spending limits are read the first time a server checks a provider in a month, so a change may not count until the next month or a restart.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”The settings to save: the same fields as AIInferenceConfig without findings. Every field replaces the saved one; a field left out is saved as empty, off or 0.
object
The master switch. Saved, but nothing reads it yet.
The provider each task tries first. All five tasks need a non-empty name, or the save gets 422.
object
For each task, the providers to try after its first one. Optional; a task left out has no fallback.
object
The privacy lock for restricted and embargoed assets.
object
When true, AI work on an asset whose sensitivity is restricted or
embargo may only use local providers, and fails when none of the
task’s providers is local. A fresh install has it on. It’s read when
a server starts, so a change needs a restart. Only the sensitivity
counts, not team access or the mature flag.
The provider names treated as local by the privacy lock. Listing a provider is your statement that it keeps data local; nothing checks where it runs. MCP tool calls, such as image editing, ignore this list and use the privacy class each MCP server was registered with. A fresh install lists ollama, vllm, whisper_local and clip_local. It can come back as null instead of an empty list.
Monthly spending limits in whole US dollars. Each provider gets the same limits separately.
object
Meant to add a warning to the usage records when a provider’s spending first reaches this many dollars in a month. It’s saved and returned, but nothing records a warning yet. 0 means no warning, and is the fresh-install value.
The most each provider may spend in a month, in whole dollars. Before each AI call, the server refuses it when the provider’s recorded spending for the month, plus any cost declared for an MCP tool, would be over this limit. 0, the fresh-install value, refuses every call to every provider, local ones included. Spending isn’t reserved and calls aren’t stopped part-way, so the limit can be passed. Each server reads the limit and the recorded spending the first time it checks a provider in a month and can keep them until the month ends or it restarts, so later spending and a changed limit may not count until then.
Responses
Section titled “ Responses ”The settings read back after the save, with any problems found in them.
The AI inference settings, as getAIInferenceConfig and
updateAIInferenceConfig return them. findings is worked out by the
server each time and isn’t saved.
object
The master switch. A fresh install has it off. It’s saved and returned, but nothing reads it yet, so it doesn’t turn any AI feature on or off.
The provider each task tries first, keyed by task: complete,
embed, transcribe, tag and caption. Other keys are dropped
when the settings are read. The built-in default is claude,
clip_local, whisper_local, ollama and claude, in that order.
Names aren’t checked, and the saved AI provider list (getAIConfig)
isn’t read; a name the server has no provider for is skipped when
the task runs.
object
For each task, the providers to try after its first one, in order. The next one is tried when a call fails with a temporary or network error or a rate limit; a permanent error or a budget refusal ends the task. A name already tried is skipped. A task left out has no fallback. Other keys are dropped when the settings are read. Each task has a built-in default list.
object
The privacy lock for restricted and embargoed assets.
object
When true, AI work on an asset whose sensitivity is restricted or
embargo may only use local providers, and fails when none of the
task’s providers is local. A fresh install has it on. It’s read when
a server starts, so a change needs a restart. Only the sensitivity
counts, not team access or the mature flag.
The provider names treated as local by the privacy lock. Listing a provider is your statement that it keeps data local; nothing checks where it runs. MCP tool calls, such as image editing, ignore this list and use the privacy class each MCP server was registered with. A fresh install lists ollama, vllm, whisper_local and clip_local. It can come back as null instead of an empty list.
Monthly spending limits in whole US dollars. Each provider gets the same limits separately.
object
Meant to add a warning to the usage records when a provider’s spending first reaches this many dollars in a month. It’s saved and returned, but nothing records a warning yet. 0 means no warning, and is the fresh-install value.
The most each provider may spend in a month, in whole dollars. Before each AI call, the server refuses it when the provider’s recorded spending for the month, plus any cost declared for an MCP tool, would be over this limit. 0, the fresh-install value, refuses every call to every provider, local ones included. Spending isn’t reserved and calls aren’t stopped part-way, so the limit can be passed. Each server reads the limit and the recorded spending the first time it checks a provider in a month and can keep them until the month ends or it restarts, so later spending and a changed limit may not count until then.
Problems found in the settings, sorted by code and then by task, and left out when there are none. Only two things are checked: that every task has a provider, and, while the privacy lock is on, that there is at least one local provider.
object
What the problem is. The server sends routing_missing_concern (a
task has no provider), privacy_lock_with_empty_local_list (the
lock is on with no local providers) and, from a read, internal
(the settings couldn’t be read; see message).
The task the problem is about; left out when it isn’t about one task.
The problem in English. For internal, the error that stopped the read.
Authentication 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 completedNothing was saved: a task has no provider, or the privacy lock is on with no local providers.
object
The problems in one line, as “ai: config invalid: ” followed by each message.
One entry for each problem, sorted by code and then by task.
object
What the problem is. The server sends routing_missing_concern (a
task has no provider), privacy_lock_with_empty_local_list (the
lock is on with no local providers) and, from a read, internal
(the settings couldn’t be read; see message).
The task the problem is about; left out when it isn’t about one task.
The problem in English. For internal, the error that stopped the read.