Update the AI provider configuration

PATCH

/admin/system/ai

• Local development behind nginx (port 8088 by default)

Persists the AI provider list and default-provider selection. Providers are stored but NOT yet used for inference — the AI auto-tagging / search phase wires the providers into a real client. API keys are stored as plain strings for now (admin-only table); a secrets-backend migration is planned.

providers[*].api_key is write-only: supply it to set or rotate a key, omit it (or send an empty string) to keep the stored one. Saving an unrelated field therefore cannot wipe a key. The response echoes api_key_set, never the key.

Authorizations

• cookieAuth
• bearerAuth

Request Body ^required

AI provider configuration. Persisted under the sysconfig key ai. API keys are stored as plain strings for now (admin- only table; never federated); a secrets-backend migration is planned. Keys are write-only on this surface — see providers[*].api_key / providers[*].api_key_set.

object

default_provider_id

Picks the providers[*].id used when nothing else specifies. Empty = no default (callers must choose, or AI features stay disabled).

string

providers

required

Array<object>

object

id

string

kind

required

string

Allowed values: openai anthropic google local

enabled

required

boolean

display_name

required

string

model

E.g. gpt-4o, claude-sonnet-4-6

string

base_url

Override for self-hosted / proxied endpoints.

string

api_key

Write-only. Provide to set or rotate this provider’s API key; omit (or send an empty string) on PATCH to keep the current value. The response NEVER echoes this field — read api_key_set instead to check whether one is on file. A stored credential has no read-back workflow, so it is not returned to any capability, system.admin included (#711).

string format: password

api_key_set

True when an API key is currently stored for this provider. Set by the server on GET responses; ignored if sent on PATCH.

boolean

config

Per-provider inference defaults. Closed schema, for the same reason as SSOProviderConfig (#718): a free-form map on a provider record is where credentials end up, and the read path cannot tell an unknown key holding a rate limit from one holding a token. Every field here is a tuning knob; the provider’s one credential is api_key, which is write-only.

object

temperature

Sampling temperature. Unset = the model’s own default.

number

<= 2

top_p

Nucleus-sampling cutoff. Unset = the model’s own default.

number

<= 1

max_output_tokens

Cap on generated tokens per request. 0 = no override.

integer

system_prompt

Prepended to every request routed to this provider.

string

request_timeout_seconds

Per-request timeout. 0 = the client default.

integer

rate_limit_rpm

Client-side requests-per-minute ceiling. 0 = unthrottled.

integer

Responses

200

Updated AI config

AI provider configuration. Persisted under the sysconfig key ai. API keys are stored as plain strings for now (admin- only table; never federated); a secrets-backend migration is planned. Keys are write-only on this surface — see providers[*].api_key / providers[*].api_key_set.

object

default_provider_id

Picks the providers[*].id used when nothing else specifies. Empty = no default (callers must choose, or AI features stay disabled).

string

providers

required

Array<object>

object

id

string

kind

required

string

Allowed values: openai anthropic google local

enabled

required

boolean

display_name

required

string

model

E.g. gpt-4o, claude-sonnet-4-6

string

base_url

Override for self-hosted / proxied endpoints.

string

api_key

Write-only. Provide to set or rotate this provider’s API key; omit (or send an empty string) on PATCH to keep the current value. The response NEVER echoes this field — read api_key_set instead to check whether one is on file. A stored credential has no read-back workflow, so it is not returned to any capability, system.admin included (#711).

string format: password

api_key_set

True when an API key is currently stored for this provider. Set by the server on GET responses; ignored if sent on PATCH.

boolean

config

Per-provider inference defaults. Closed schema, for the same reason as SSOProviderConfig (#718): a free-form map on a provider record is where credentials end up, and the read path cannot tell an unknown key holding a rate limit from one holding a token. Every field here is a tuning knob; the provider’s one credential is api_key, which is write-only.

object

temperature

Sampling temperature. Unset = the model’s own default.

number

<= 2

top_p

Nucleus-sampling cutoff. Unset = the model’s own default.

number

<= 1

max_output_tokens

Cap on generated tokens per request. 0 = no override.

integer

system_prompt

Prepended to every request routed to this provider.

string

request_timeout_seconds

Per-request timeout. 0 = the client default.

integer

rate_limit_rpm

Client-side requests-per-minute ceiling. 0 = unthrottled.

integer

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

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