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.
`GET`	`/admin/pipeline-authoring/execution-topology`	Read effective Agentic placement, inheritance source, protocol, and readiness.
`PATCH`	`/admin/pipeline-authoring/execution-topology`	Set the execution topology for new Agentic sessions at the current scope.
`DELETE`	`/admin/pipeline-authoring/execution-topology`	Remove the current-scope topology override.

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.

Pipeline Authoring Execution Topology

Execution topology is separate from runtime limits and controls placement for new durable Agentic sessions. Without instance context, requests read or mutate the platform scope. With verified instance context, an instance override takes precedence. As with runtime policy, X-Instance-Id cannot be used to select an arbitrary instance from the control-plane route.

GET /admin/pipeline-authoring/execution-topology

{
  "scope": "instance",
  "default_mode": "pooled",
  "platform_override": "orchestrator",
  "instance_override": null,
  "effective_mode": "orchestrator",
  "source": "platform",
  "protocol_version": 1,
  "fallback_policy": "fail_closed",
  "dedicated_idle_timeout_seconds": 1800,
  "readiness": {
    "pooled": {"available": true, "blockers": []},
    "orchestrator": {"available": true, "blockers": []},
    "dedicated_session": {
      "available": false,
      "blockers": ["dedicated_runtime_manager_unavailable"]
    }
  }
}

The three modes are:

Mode	Placement
`pooled`	Coordinator advances and operations run on the shared authoring execution pool.
`orchestrator`	The control plane runs coordinator advances and sends blocking operations to the execution pool.
`dedicated_session`	One isolated worker is bound to the runtime thread until terminal cleanup or idle expiry.

readiness combines structural deployment checks with live health, queue, heartbeat, protocol, and capability checks. Treat blocker strings as stable machine-readable codes. Empty worker capability manifests deny placement; pooled workers must advertise the runtime or operation capabilities required by the command, and the configured dedicated image must advertise agent_kernel_v1 plus every delegated operation.

Set one current-scope override with a strict payload:

PATCH /admin/pipeline-authoring/execution-topology
Content-Type: application/json

{
  "mode": "pooled"
}

Allowed values are pooled, orchestrator, and dedicated_session. Unknown fields or modes return 422. A structurally unavailable target returns 409 with its blocker codes. A successful response is the same snapshot shape as the GET response.

DELETE /admin/pipeline-authoring/execution-topology

Delete removes only the current-scope override. New sessions then inherit the platform override or pooled default. The selected topology, protocol, idle timeout, source, and fail-closed policy are frozen into each root Agentic session, so PATCH and DELETE never move active sessions.

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.

System Settings user guide
Pipeline Authoring security guide
Authoring API Egress for the separate global routing profiles and connector bindings
Storage Configuration
AI Operations API
Repositories API

Endpoints​

Setting Groups​

Read Settings​

Update Settings​

Reset An Override​

Pipeline Authoring Runtime Policy​

Policy fields​

Update or inherit fields​

Pipeline Authoring Execution Topology​

Storage Families​

Errors​

Related Docs​