Settings & personal AI API

Application boundary#

These paths belong to your YAADMIN installation. They are not callable product-website APIs. Authenticated mutations require a session-matched X-CSRF-Token unless the route is public. Handler-local error codes are not exhaustive downstream schemas.

Verified routes#

Find a route in this category

9 routes

GET/api/personal-ai/preferences

Personal ai preferences.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, **_public_personal_ai_preferences(_read_personal_ai_preferences(state, identity)), providers}
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_personal_ai_preferences. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/personal-ai/preferences

Personal ai preferences update.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: PersonalAIPreferencesPayload [mode, provider, base_url, model, api_key, clear_api_key]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, **_public_personal_ai_preferences(updated)}
Important errors: 400, 409
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`mode`	`str = Field(default="system", min_length=1, max_length=32)`
`provider`	`str = Field(default="openai", min_length=1, max_length=64)`
`base_url`	`str = Field(default="", max_length=2048)`
`model`	`str = Field(default="", max_length=255)`
`api_key`	`type/default redacted; field name verified`
`clear_api_key`	`type/default redacted; field name verified`

Verified route registration · handler api_personal_ai_preferences_update. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/personal-ai/models/discover

Personal ai models discover.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: PersonalAIModelsDiscoveryPayload [provider, base_url, api_key]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, provider, base_url, models} (visible return; credential setup statements redacted)
Important errors: 404, 409, 502
Approval behavior: no standalone approval behavior in this handler. Snapshot redaction prevents full credential/body reconstruction.

Request fields

Field	Verified definition
`provider`	`str = Field(min_length=1, max_length=64)`
`base_url`	`str = Field(default="", max_length=2048)`
`api_key`	`type/default redacted; field name verified`

Verified route registration · handler api_personal_ai_models_discover. Some definitions may be partially redacted; no missing fields are inferred.

GET/settings

Settings page.

Authentication: session
Permission: codex.use (special default-allow fallback for assigned role; see §6)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: HTML template response (handler names the template)
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler settings_page. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/settings/llm/profile/{provider}

Settings llm profile.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {key: value for (key, value) in profile.items() if key != 'api_key'}
Important errors: 404
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_settings_llm_profile. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/settings/llm/models

Settings llm models.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: base_url, provider
Headers: none beyond shared session/CSRF
Response structure: {ok, provider, base_url, models}
Important errors: 404, 409, 502
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_settings_llm_models. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/settings/llm/models/discover

Settings llm models discover.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: LLMModelsDiscoveryPayload [provider, base_url, api_key]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, provider, base_url, models}
Important errors: 404, 409, 502
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`provider`	`str = Field(min_length=1, max_length=64)`
`base_url`	`str = Field(min_length=1, max_length=2048)`
`api_key`	`type/default redacted; field name verified`

Verified route registration · handler api_settings_llm_models_discover. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/settings/llm/profile/{provider}

Update llm profile.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: LLMProviderProfilePayload [base_url, model, api_key, clear_api_key]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, profile, hot_applied}
Important errors: 404, 409, 502
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`base_url`	`str = Field(min_length=1, max_length=2048)`
`model`	`str = Field(min_length=1, max_length=255)`
`api_key`	`type/default redacted; field name verified`
`clear_api_key`	`type/default redacted; field name verified`

Verified route registration · handler api_update_llm_profile. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/settings/{section_id}

Update settings.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: ModuleSettingsPayload [values, clear_fields]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, settings, restart_required, hot_applied}
Important errors: 502
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`values`	`dict[str, Any] = Field(default_factory=dict)`
`clear_fields`	`list[str] = Field(default_factory=list, max_length=200)`

Verified route registration · handler api_update_settings. Some definitions may be partially redacted; no missing fields are inferred.

Implementation reference: 2026-10-02. Labels distinguish verified behavior, partial implementation and architectural intent.