System Settings API

System Settings APIs expose the superadmin configuration surface used by the control-plane Administration -> System Settings route.

info

All endpoints are mounted under /api/v1.0. Paths below omit that prefix for readability. These endpoints require superadmin access.

Endpoints

Method	Endpoint	Description
`GET`	`/admin/system-settings`	Read grouped effective platform settings.
`PATCH`	`/admin/system-settings`	Update one or more editable setting overrides.
`DELETE`	`/admin/system-settings/{setting_key}`	Reset one setting override to its deployment/default value.

Related system surfaces are documented separately:

AI Operations API for AI provider, model routing, budgets, prompts, embeddings, and AI Ops endpoints.
Repositories API for Analysis Git/Gitea status, project repository defaults, connection tests, and repair.
Dead Letter API for failed background task inspection and retry.

Setting Groups

GET /admin/system-settings returns a JSON object grouped by UI section. Groups currently include:

Group	Contains
`worker`	Redis URL display and worker mode.
`database`	Database connection display metadata.
`email`	Email enablement, sender, SMTP host, port, TLS/SSL, and mock mode.
`security`	Platform-wide security controls such as Python package vulnerability scanning.
`authoring`	Shared authoring network policy, proxy URL, allowed hosts, and private destination behavior.
`pipeline_authoring`	Generated-code validation package fetch policy, public index, Qarion package base URL, code-writer routing, and dependency smoke validation.
`transform_authoring`	Transform package fetch policy, public index, and Qarion package base URL.
`notebook_authoring`	Notebook package fetch policy, public index, and Qarion package base URL.
`data_questions`	Data question summary trigger settings.
`analysis`	Analysis link suggestion settings.
`tickets`	Ticket issue detection and tagging settings.
`search`	Search connection settings.
`storage`	Default attachment storage backend and provider fields.
`storage_families`	Per-family storage overrides for Python packages, OCI registry blobs, and model artifacts.
`maps`	Map style and place-search provider settings.

Each setting field is returned as metadata:

{
  "value": "external",
  "is_editable": true,
  "is_overridden": false
}

is_secret is present for secret fields. Secret values are masked or returned as an empty string; clients should never expect to read the stored credential.

Read Settings

GET /admin/system-settings

Example response fragment:

{
  "worker": {
    "redis_url": {
      "value": "redis://example:****@redis:6379/0",
      "is_editable": false,
      "is_overridden": false
    },
    "worker_mode": {
      "value": "external",
      "is_editable": true,
      "is_overridden": true
    }
  },
  "storage": {
    "backend": {
      "value": "s3",
      "is_editable": true,
      "is_overridden": true
    },
    "s3_secret_key": {
      "value": "••••••••",
      "is_editable": true,
      "is_overridden": true,
      "is_secret": true
    }
  }
}

Use is_editable to decide whether to show an edit control. Use is_overridden to distinguish deployment defaults from database overrides.

Update Settings

PATCH /admin/system-settings

{
  "settings": {
    "worker.worker_mode": "external",
    "email.enabled": true,
    "pipeline_authoring.validation_package_fetch_policy": "qarion_plus_public"
  }
}

The response lists updated keys:

{
  "updated": [
    "worker.worker_mode",
    "email.enabled",
    "pipeline_authoring.validation_package_fetch_policy"
  ]
}

Only keys registered as editable platform settings can be changed. Unknown, read-only, or invalid keys return 400.

When updating secret settings, send the replacement secret value. Omit the key or leave the UI field unchanged when you want to keep the existing secret.

Reset An Override

DELETE /admin/system-settings/storage.s3_region

The endpoint returns 204 No Content when the override is removed. The next read shows the effective deployment/default value.

Resetting a secret removes the database override. If the deployment still provides that secret through environment configuration, the effective value continues to appear as set.

Storage Families

Storage settings include a default target and artifact-family overrides:

Family	Setting prefix	Notes
Default attachments	`storage.*`	General attachments and files.
Python packages	`storage.python_packages.*`	Package repository distributions.
OCI registry	`storage.oci_registry.*`	OCI registry blobs, including container and Helm artifacts.
Model artifacts	`storage.model_artifacts.*`	Managed model repository artifact uploads. Does not support `base64`.

Family values may inherit from the default storage target when no family override is set. Existing files keep their recorded backend and URI; setting changes affect new writes.

Errors

Status	Meaning
`400`	Invalid or read-only setting key, invalid value, or unsupported storage option.
`401`	Missing or expired authentication.
`403`	Authenticated user is not a superadmin.

Endpoints​

Setting Groups​

Read Settings​

Update Settings​

Reset An Override​

Storage Families​

Errors​

Related Docs​