Replace the AI inference subsystem configuration

PUT

/admin/ai/config

• Local development behind nginx (port 8088 by default)

Full-replacement write. Validates the supplied config before persisting — invalid configs return 422 with structured findings; the existing config stays in place until the admin resolves the findings.

Requires ai.admin capability.

Authorizations

• cookieAuth
• bearerAuth

Request Body ^required

PUT body for /admin/ai/config. Same shape as the read minus the validator-computed findings.

object

enabled

required

boolean

routing

required

object

key

additional properties

string

fallback_chains

required

object

key

additional properties

Array<string>

privacy

required

object

lock_sensitive_to_local

required

When true, assets at sensitivity tier restricted or embargo route to local providers only. Defaults to true on fresh install.

boolean

local_providers

required

Provider names considered “local” for the gate above.

Array<string>

default_budget

required

object

soft_warning_usd

required

USD threshold at which a soft-warn audit event fires.

integer format: int64

hard_cap_usd

required

USD ceiling beyond which CheckBudgetBefore rejects calls with ai_budget_exhausted. Zero (the fresh-install default) fails-closed with cloud_budget_not_configured on the very first call until the operator raises it.

integer format: int64

Responses

200

Updated config (with any non-blocking findings)

AI inference subsystem snapshot. Returned by GET /admin/ai/config; writable via PUT with the AIInferenceConfigWrite shape (the read shape carries findings + computed defaults that the write shape doesn’t include).

object

enabled

required

Master switch. Defaults to false on fresh install (operator opts in).

boolean

routing

required

Per-task default provider. Keys are concern names (complete | embed | transcribe | tag | caption); values are provider names registered via /admin/system/ai.

object

key

additional properties

string

fallback_chains

required

Ordered fallback list per concern. The router walks transient + rate-limit failures down the chain; permanent/budget/privacy errors short-circuit.

object

key

additional properties

Array<string>

privacy

required

object

lock_sensitive_to_local

required

When true, assets at sensitivity tier restricted or embargo route to local providers only. Defaults to true on fresh install.

boolean

local_providers

required

Provider names considered “local” for the gate above.

Array<string>

default_budget

required

object

soft_warning_usd

required

USD threshold at which a soft-warn audit event fires.

integer format: int64

hard_cap_usd

required

USD ceiling beyond which CheckBudgetBefore rejects calls with ai_budget_exhausted. Zero (the fresh-install default) fails-closed with cloud_budget_not_configured on the very first call until the operator raises it.

integer format: int64

findings

Validator findings against the current config (e.g. routing references a provider that isn’t registered). Empty when the config is clean.

Array<object>

object

code

required

Stable identifier (routing_missing_concern, privacy_lock_with_empty_local_list, routing_undefined_provider, etc.) the admin UI uses to render a localised message.

string

concern

Empty when the finding isn’t concern-specific.

string

Allowed values: complete embed transcribe tag caption

message

required

Operator-readable English fallback message.

string

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

422

Config rejected by validator

object

error

required

string

findings

required

Array<object>

object

code

required

Stable identifier (routing_missing_concern, privacy_lock_with_empty_local_list, routing_undefined_provider, etc.) the admin UI uses to render a localised message.

string

concern

Empty when the finding isn’t concern-specific.

string

Allowed values: complete embed transcribe tag caption

message

required

Operator-readable English fallback message.

string