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.
GET	/admin/pipeline-authoring/runtime-policy	Read effective Pipeline Authoring limits, inheritance sources, and monthly usage.
PATCH	/admin/pipeline-authoring/runtime-policy	Update a sparse Pipeline Authoring policy override at the current scope.
DELETE	/admin/pipeline-authoring/runtime-policy	Remove every Pipeline Authoring policy override at the current scope.

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.

Pipeline Authoring Runtime Policy

The Pipeline Authoring policy is separate from the grouped /admin/system-settings payload because it resolves an inheritable, validated policy snapshot and live monthly usage. Without an instance context, requests read or mutate the platform scope. With a verified runtime instance context, instance overrides take precedence over platform overrides. X-Instance-Id is only an optional consistency check for an already authenticated instance-scoped request; it cannot select an arbitrary instance from the control-plane route.

GET /admin/pipeline-authoring/runtime-policy

The response includes:

• scope: platform or instance.
• defaults, platform_override, and optional instance_override.
• effective: the fully resolved policy, including the derived max_ai_calls.
• sources: default, platform, or instance for every configurable field.
• usage: month boundaries, completed tokens and estimated cost, in-flight reserved tokens and cost, call count, and remaining values when a cap exists.

{
  "scope": "instance",
  "platform_override": {
    "monthly_token_budget": 2000000
  },
  "instance_override": {
    "work_ai_call_budget": 24
  },
  "effective": {
    "planner_timeout_seconds": 3600,
    "step_hard_timeout_seconds": 900,
    "work_ai_call_budget": 24,
    "final_review_ai_call_budget": 4,
    "repair_ai_call_budget": 8,
    "max_ai_calls": 36,
    "monthly_token_budget": 2000000,
    "monthly_cost_budget_micro_cents": null
  },
  "sources": {
    "work_ai_call_budget": "instance",
    "monthly_token_budget": "platform"
  },
  "usage": {
    "period_start": "2026-07-01T00:00:00Z",
    "period_end": "2026-08-01T00:00:00Z",
    "tokens_used": 125000,
    "reserved_tokens": 8000,
    "estimated_cost_micro_cents": 2750000,
    "reserved_cost_micro_cents": 160000,
    "call_count": 42,
    "tokens_remaining": 1867000,
    "cost_remaining_micro_cents": null
  }
}

The example abbreviates effective and sources; actual responses contain all policy fields.

Policy fields

Group	Fields
Workflow	planner_timeout_seconds, step_hard_timeout_seconds, min_step_budget, max_tool_calls, max_replans, max_retries_per_step
AI call lanes	work_ai_call_budget, final_review_ai_call_budget, repair_ai_call_budget; max_ai_calls is their read-only sum
Parallelism	parallel_subagent_max_concurrency, execution_unit_max_concurrency
Repair and research	generation_repair_max_attempts, validation_repair_max_attempts, semantic_repair_attempts_per_cluster, general_repair_attempt_limit, research_attempt_limit, decomposition_information_repair_attempts, decomposition_information_research_attempts, proposal_research_attempts, unchanged_failure_repeat_limit
Completion	run_summary_retry_attempts, post_completion_enrichment_attempts, post_completion_worker_timeout_seconds
Monthly caps	monthly_token_budget, monthly_cost_budget_micro_cents

Timeout fields accept 1–3600 seconds. The minimum step budget accepts 1–200; tool calls accept 0–100; call-lane allocations accept 0–200 each; parallelism accepts 1–16; and replan, retry, repair, research, summary, and enrichment attempt fields accept 0–10. Monthly caps are positive integers or unlimited. monthly_cost_budget_micro_cents uses one million micro-cents per US dollar.

Update or inherit fields

PATCH /admin/pipeline-authoring/runtime-policy
Content-Type: application/json

{
  "work_ai_call_budget": 24,
  "repair_ai_call_budget": 6,
  "monthly_token_budget": 2000000,
  "monthly_cost_budget_micro_cents": 25000000
}

A JSON null removes the named field from the current scope so it inherits again. For either monthly cap, send "unlimited" to store an explicit unlimited value at the current scope. DELETE /admin/pipeline-authoring/runtime-policy removes the entire current-scope override.

The resolved policy must keep step_hard_timeout_seconds less than or equal to planner_timeout_seconds and allocate at least one total AI call. Invalid relationships, unknown fields, or out-of-range values return 400.

Monthly token and cost caps are reserved atomically before Pipeline Authoring provider calls, including later repair or retry calls. Completed AI logs and active reservations both count toward the cap. Cost enforcement fails closed when the selected model has no known pricing. A budget exhaustion result uses the stable failure kind pipeline_authoring_budget_exhausted and reports the exhausted dimension, configured limit, current usage, reserved usage, and reset period.

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.

Related Docs

• System Settings user guide
• Storage Configuration
• AI Operations API
• Repositories API