Skip to content

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:

  • enabled isn’t read by anything yet, so turning it off doesn’t stop any AI feature.
  • routing, fallback_chains and local_providers choose 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_local is 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.

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
enabled
required

The master switch. Saved, but nothing reads it yet.

boolean
routing
required

The provider each task tries first. All five tasks need a non-empty name, or the save gets 422.

object
key
additional properties
string
fallback_chains
required

For each task, the providers to try after its first one. Optional; a task left out has no fallback.

object
key
additional properties
Array<string>
privacy
required

The privacy lock for restricted and embargoed assets.

object
lock_sensitive_to_local
required

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.

boolean
local_providers
required

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.

Array<string>
default_budget
required

Monthly spending limits in whole US dollars. Each provider gets the same limits separately.

object
soft_warning_usd
required

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.

integer format: int64
hard_cap_usd
required

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.

integer format: int64

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
enabled
required

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.

boolean
routing
required

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
key
additional properties
string
fallback_chains
required

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
key
additional properties
Array<string>
privacy
required

The privacy lock for restricted and embargoed assets.

object
lock_sensitive_to_local
required

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.

boolean
local_providers
required

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.

Array<string>
default_budget
required

Monthly spending limits in whole US dollars. Each provider gets the same limits separately.

object
soft_warning_usd
required

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.

integer format: int64
hard_cap_usd
required

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.

integer format: int64
findings

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.

Array<object>
object
code
required

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).

string
concern

The task the problem is about; left out when it isn’t about one task.

string
Allowed values: complete embed transcribe tag caption
message
required

The problem in English. For internal, the error that stopped the read.

string

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

Nothing was saved: a task has no provider, or the privacy lock is on with no local providers.

object
error
required

The problems in one line, as “ai: config invalid: ” followed by each message.

string
findings
required

One entry for each problem, sorted by code and then by task.

Array<object>
object
code
required

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).

string
concern

The task the problem is about; left out when it isn’t about one task.

string
Allowed values: complete embed transcribe tag caption
message
required

The problem in English. For internal, the error that stopped the read.

string