API Reference: Application runtime settings

The Runtime Settings API provides endpoints for listing, reading, and updating runtime configuration settings in automation orchestrator. Use this API to manage runtime settings programmatically without redeploying the application.

Considerations

Settings are identified by dot-namespaced keys, such as context_manager.max_total_tokens, and support optimistic locking through version numbers.

Permissions

Access is controlled using permissions. The Settings API uses two permission levels:

Permission Required for Description
setting.read List settings, get a setting, list categories View runtime settings and their values
setting.write Update a setting, bulk update settings Modify runtime setting values

By default, the Auditor role has read permissions, and the Administrator role has write permissions.

List settings

Retrieve a paginated list of all runtime settings. You can filter by category or group and control the sort order.

Request:

GET /api/v1/settings

Query parameters:

Parameter Type Required Description
limit integer No Maximum number of settings to return per page.Default: 20.Maximum: 100.
cursor string No Opaque cursor for pagination. Use thenext orprev value from a previous response.
sort string No Field to sort by. Prefix with- for descending order. Sortable fields: key, category.Default: key.
include_total boolean No Set totrue to include a total count of matching settings in the response.Default: false.
category string No Filter settings by category slug.Example:context_manager,workflow_execution.
group string No Filter settings by group name within a category.Example: Token limits, Execution.

Response: 200 OK

{
   "resources": [
     {
       "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "created_at": "2026-01-15T10:30:00Z",
       "updated_at": "2026-04-28T14:22:00Z",
       "key": "context_manager.max_total_tokens",
       "name": "Max total tokens",
       "description": "Maximum total tokens in context package",
       "helper_text": "The maximum number of tokens for the entire prompt sent to the LLM, including system, context, and user sections",
       "depends_on": "null",
       "category": "context_manager",
       "group": "Token limits",
       "value": 8000,
       "default_value": 4000,
       "effective_value": 8000,
       "value_type": "integer",
       "requires_restart": false,
       "cache_ttl_seconds": null,
       "validation_schema": {
         "min": 1
       },
       "version": 3
     }
   ],
   "next": "eyJpZCI6InV1aWQifQ",
   "prev": null,
   "total": 30
}

List categories

Retrieve all setting categories and their group names. Categories define how settings are organized in the user interface.

Request:

GET /api/v1/settings/categories

This endpoint does not accept query parameters.

Response: 200 OK

{
   "results": [
     {
       "slug": "ai_llm",
       "name": "AI / LLM",
       "description": "Artificial intelligence and large language model settings",
       "display_order": 5,
       "group_names": []
     },
     {
       "slug": "context_manager",
       "name": "Context Manager",
       "description": "Token limits, retrieval, grounding, compression, and context assembly",
       "display_order": 20,
       "group_names": [
         "Grounding scores",
         "Token limits",
         "Retrieval",
         "Snippets",
         "Context assembly",
         "Performance",
         "Compression"
       ]
     },
     {
       "slug": "workflow_execution",
       "name": "Workflow Execution",
       "description": "Workflow execution timeouts, duration limits, and input constraints",
       "display_order": 30,
       "group_names": [
         "Execution"
       ]
     },
     {
       "slug": "authentication",
       "name": "Authentication",
       "description": "Authentication, identity provider, and group sync settings",
       "display_order": 45,
       "group_names": [
         "Local login"
       ]
     },
     {
       "slug": "integrations",
       "name": "Integrations",
       "description": "Integration health check and connection test settings",
       "display_order": 50,
       "group_names": []
     },
     {
       "slug": "rate_limiting",
       "name": "Rate Limiting",
       "description": "API rate limiting and throttling settings",
       "display_order": 55,
       "group_names": []
     }
   ]
}

Get a setting

Retrieve a single runtime setting by its dot-namespaced key.

Request:

GET /api/v1/settings/key

Path parameters:

Parameter Type Required Description
key string Yes Dot-namespaced setting key. Must match the pattern ^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)+$.Example:context_manager.max_total_tokens

Response: 200 OK

{
   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
   "created_at": "2026-01-15T10:30:00Z",
   "updated_at": "2026-04-28T14:22:00Z",
   "key": "context_manager.max_total_tokens",
   "name": "Max total tokens",
   "description": "Maximum total tokens in context package",
   "category": "context_manager",
   "group": "Token limits",
   "value": 8000,
   "default_value": 4000,
   "effective_value": 8000,
   "value_type": "integer",
   "requires_restart": false,
   "cache_ttl_seconds": null,
   "validation_schema": {
     "min": 1
   },
   "version": 3
}

Update a setting

Update the value of a single runtime setting. This endpoint supports optimistic locking to prevent concurrent write conflicts.

All setting updates are recorded in the audit log.

Request:

PATCH /api/v1/settings/key

Path parameters:

Parameter Type Required Description
key string Yes Dot-namespaced setting key. Must match the pattern ^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)+$.Example:workflow_engine.max_loop_iterations

Request body:

Field Type Required Description
value any Yes The new value for the setting. Must match the setting'svalue_type and pass any constraints defined invalidation_schema. Cannot be null. To reset a setting to its default, set value to the setting's default_value.
expected_version integer No The version number you expect the setting to have. If provided and the current version does not match, the API returns a 409 Conflict response. Use this to prevent overwriting changes made by another user.

Example request body:

{
   "value": 20000,
   "expected_version": 3
}

Response: 200 OK

Returns the updated setting with an incremented version number:

{
   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
   "created_at": "2026-01-15T10:30:00Z",
   "updated_at": "2026-04-29T09:15:00Z",
   "key": "workflow_engine.max_loop_iterations",
   "name": "Max loop iterations",
   "description": "Maximum iterations for loops to prevent runaway execution",
   "category": "workflow_execution",
   "group": "Execution",
   "value": 20000,
   "default_value": 10000,
   "effective_value": 20000,
   "value_type": "integer",
   "requires_restart": false,
   "cache_ttl_seconds": null,
   "validation_schema": {
     "min": 1
   },
   "version": 4
}

Bulk update settings

Update multiple settings in a single request. The operation is atomic: all updates succeed together or all fail together. If any individual update fails validation or version checking, no settings are modified.

All bulk setting updates are recorded in the audit log.

Request:

PATCH /api/v1/settings

Request body:

Field Type Required Description
updates array Yes Array of setting updates. Maximum 500 items. Each item requires key and value. Duplicate keys within a single request are rejected.

Each item in the updates array has the following fields:

Field Type Required Description
key string Yes Dot-namespaced setting key.
value any Yes The new value for the setting.
expected_version integer No Expected current version for optimistic locking.

Example request body:

{
   "updates": [
     {
       "key": "context_manager.max_total_tokens",
       "value": 8000,
       "expected_version": 3
     },
     {
       "key": "context_manager.max_context_tokens",
       "value": 6000
     },
     {
       "key": "workflow_engine.script_timeout_seconds",
       "value": 600
     }
   ]
 }

Response: 200 OK

Returns an array of all updated settings:

[
   {
     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "key": "context_manager.max_total_tokens",
     "name": "Max total tokens",
     "value": 8000,
     "default_value": 4000,
     "effective_value": 8000,
     "value_type": "integer",
     "version": 4,
     "..."
   },
   {
     "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
     "key": "context_manager.max_context_tokens",
     "name": "Max context tokens",
     "value": 6000,
     "default_value": 3000,
     "effective_value": 6000,
     "value_type": "integer",
     "version": 2,
     "..."
   },
   {
     "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
     "key": "workflow_engine.script_timeout_seconds",
     "name": "Script timeout (seconds)",
     "value": 600,
     "default_value": 300,
     "effective_value": 600,
     "value_type": "integer",
     "version": 2,
     "..."
   }
 ]

RuntimeSettingRead response schema

Each setting object returned by the API contains the following fields:

Field Type Description
id string (UUID) Unique identifier for the setting.
created_at string (ISO 8601) Timestamp when the setting was created.
updated_at string (ISO 8601) Timestamp when the setting was last modified.
key string Dot-namespaced setting identifier. Globally unique.
name string Human-readable display name.
description string or null Longer description of the setting.
helper_text string or null Short inline guidance shown below the setting field in the UI.
depends_on string or null Dot-namespaced key of a boolean setting that controls this setting's visibility.
category string Category slug for grouping.
group string or null Display group within the category.
value any User-set override value, or null if the default is in use.
default_value any Factory default value.
effective_value any The active value: value if set, otherwisedefault_value.
value_type string Expected value type. One of: string, integer, float, boolean, json.
requires_restart boolean Whether a service restart is needed for the change to take effect.
cache_ttl_seconds integer or null Per-setting cache time-to-live override in seconds.null uses the default of 60 seconds.
validation_schema object or null Constraints for value validation. See Validation constraints.
version integer Optimistic lock counter. Starts at 1 and increments with each update.

SettingCategoryRead response schema

Each category object returned by the List categories endpoint contains the following fields:

Field Type Description
slug string Machine-readable identifier for the category.
name string Human-readable display name.
description string or null Description of the category.
display_order integer Sort position for rendering. Lower values appear first.
group_names array of strings List of group names within this category.

Setting value types

Each setting has a value_type that determines what values are accepted:

Value type JSON type Description Example
string string Text value. "INFO"
integer number (integer) Whole number. Boolean values are rejected. 4000
float number Decimal number. Integer values are accepted. Boolean values are rejected. 0.7
boolean boolean true or false. true
json any Any valid JSON value, including objects and arrays. ["system", "context", "user"]

Validation constraints

Settings can define a validation_schema that enforces additional constraints on values. The API validates values against these constraints before saving.

Constraint Applies to Description Example
min integer, float Minimum allowed value (inclusive). {"min": 0}
max integer, float Maximum allowed value (inclusive). {"max": 1.0}
allowed_values string List of accepted string values. {"allowed_values": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]}
pattern string Regular expression that the value must match. {"pattern": "^[a-z]+$"}

Additional constraints enforced by the API:

  • Values cannot be null. To reset a setting to its default, set value to the setting's default_value.
  • The serialized JSON representation of a value must not exceed 65,536 bytes (64 KB).

Optimistic locking

The Settings API uses optimistic locking to prevent concurrent write conflicts. Each setting has a version field that increments with every successful update. Include expected_version in your update request so the API rejects the update if another user modified the setting after you retrieved it. The application UI always sends expected_version as a best practice. However, expected_version is optional to allow scripts and automation to declaratively apply configuration changes without first reading the current version.

If you omit expected_version, the update proceeds without version checking.

For step-by-step instructions, see Use optimistic locking with the Settings API.

Error codes

HTTP status Code Description Retryable
400 (varies) Invalid request format or duplicate keys in a bulk update. No
401 (varies) Missing or invalid authentication token. No
403 (varies) Authenticated user lacks the required permission. No
404 SETTING_NOT_FOUND The specified setting key does not exist. No
409 SETTING_VERSION_CONFLICT The expected_version does not match the current version. Re-fetch and retry. Yes
422 SETTING_VALIDATION_ERROR The value fails constraint validation (for example, below minimum or not in allowed values). No
422 SETTING_TYPE_ERROR The value type does not match the setting'svalue_type (for example, a string was provided for an integer setting). No
500 (varies) Internal server error. No

Audit logging

All write operations (single and bulk updates) are recorded in the audit log. Each audit event captures:

  • Event category: USER_ACTION
  • Actor Id: The authenticated user who made the change
  • Source component: Which automation orchestrator component setting was changed
  • Event message: A confirmation message about what was updated
  • Setting: The setting that was modified
  • Version: The new version number after the update
  • Category: The event category
  • New value: The value after the update
  • Value Type: The expected value type for UI rendering and validation

For bulk updates, the audit log captures the entire request body with all updates.

Caching behavior

Runtime settings are cached using a two-tier architecture to minimize database queries:

  • L1 cache (in-process): A per-process dictionary providing zero-latency access.
  • L2 cache (Redis): A shared cache across all application processes. Optional; the API functions without Redis.

By default, cached values expire after 60 seconds. Individual settings can override this with the cache_ttl_seconds field. Settings with requires_restart set to true are cached for the lifetime of the process.

When a setting is updated through the API, the cache is invalidated immediately and a change notification is published to all processes through Redis Pub/Sub. This means that updates typically propagate to all processes within seconds.

Rate limits and constraints

Constraint Value
Maximum items per page 100
Maximum items in a bulk update 500
Maximum value size (serialized JSON) 65,536 bytes (64 KB)
Setting key format Lowercase letters, digits, and underscores, with dot separators. Must contain at least one dot.

Available runtime settings

The following tables list all runtime settings available in automation orchestrator, organized by category.

Setting categories

The following categories organize runtime settings. The List categories endpoint returns categories, which you can use to filter the List settings endpoint.

Category slug Display name Description
ai_llm AI / LLM Artificial intelligence and large language model settings
system System System-level settings including observability and diagnostics
context_manager Context Manager Token limits, retrieval, grounding, compression, and context assembly
workflow_execution Workflow Execution Workflow execution timeouts, duration limits, and input constraints
application Application Application-level settings including document conversion
authentication Authentication Authentication, identity provider, and group sync settings
integrations Integrations Integration health check and connection test settings
rate_limiting Rate Limiting API rate limiting and throttling settings

AI / LLM settings

Key Name Type Default Restart required Constraints
agentic.max_completion_tokens Agentic max completion tokens integrer 0 No None

System settings

Key Name Type Default Restart required Constraints
logging.log_level System Log Level string "INFO" No Allowed values: DEBUG, INFO, WARNING, ERROR, CRITICAL
metrics.perf_test_mode Performance test mode boolean false No None

Context Manager settings

Grounding scores

Key Name Type Default Constraints
context_manager.required_grounding_score Required grounding score float 0.7 Min: 0.0, Max: 1.0
context_manager.minimum_grounding_score Minimum grounding score float 0.5 Min: 0.0, Max: 1.0

Token limits

Key Name Type Default Constraints
context_manager.max_total_tokens Max total tokens integer 4000 Min: 1
context_manager.max_context_tokens Max context tokens integer 3000 Min: 1
context_manager.max_system_tokens Max system tokens integer 500 Min: 1
context_manager.max_user_tokens Max user tokens integer 500 Min: 1
context_manager.output_token_reserve Output token reserve integer 4096 Min: 256
context_manager.tokenizer_safety_margin Tokenizer safety margin float 0.90 Min: 0.5, Max: 1.0

Retrieval

Key Name Type Default Constraints
context_manager.default_k Default K (documents to retrieve) integer 10 Min: 1
context_manager.enable_hybrid_search Hybrid search boolean true None
context_manager.semantic_weight Semantic weight float 0.7 Min: 0.0, Max: 1.0
context_manager.lexical_weight Lexical weight float 0.3 Min: 0.0, Max: 1.0

Snippets

Key Name Type Default Constraints
context_manager.max_snippets_per_doc Max snippets per document integer 3 Min: 1
context_manager.snippet_min_length Snippet min length (chars) integer 100 Min: 1
context_manager.snippet_max_length Snippet max length (chars) integer 500 Min: 1

Context assembly

Key Name Type Default Constraints
context_manager.enforce_hierarchy Hierarchical ordering boolean true None
context_manager.priority_order Priority order json ["system", "context", "user"] None
context_manager.include_citations Include source citations boolean true None

Performance

Key Name Type Default Constraints
context_manager.request_timeout_seconds Request timeout (seconds) integer 30 Min: 1
context_manager.max_concurrent_requests Max concurrent requests integer 5 Min: 1

Compression

Key Name Type Default Constraints
context_manager.compression_mode Compression mode string "extractive" Allowed values: extractive, abstractive
context_manager.compression_loop Compression loop integer 3 Min: 0
context_manager.compression_temperature Compression temperature float 0.3 Min: 0.0, Max: 1.0
context_manager.compression_max_tokens Compression max tokens integer 2000 Min: 1

Workflow Execution settings

Key Name Type Default Constraints
workflow_engine.max_loop_iterations Max loop iterations integer 10000 Min: 1
workflow_engine.script_timeout_seconds Script timeout (seconds) integer 300 Min: 1
workflow_engine.agentic_timeout_seconds Agentic timeout (seconds) integer 300 Min: 1
workflow_engine.max_prompt_length Max prompt length integer 100000 Min: 1000
workflow_engine.script_max_output_kb Script max output (KB) integer 1024 Min: 256, Max: 2048
workflow_engine.aap_timeout_seconds Ansible Automation Platform timeout (seconds) integer 3600 Min: 1
workflow_engine.approval_decision_window_seconds Approval decision window (seconds) integer 86400 Min: 1
workflow_engine.continue_on_failure Continue on failure (default) boolean false None
workflow_engine.converge_wait_duration_seconds Converge wait duration (seconds) integer 86400 Min: 1
workflow_engine.http_request_timeout_seconds HTTP request timeout (seconds) integer 30 Min: 1
workflow_engine.max_wait_duration_seconds Max wait duration (seconds) integer 2592000 Min: 1
workflow_engine.retry_backoff_coefficient Default retry backoff coefficient float 2.0 Min: 1.0
workflow_engine.retry_initial_interval Default retry initial interval (seconds) integer 1 Min: 1
workflow_engine.retry_max_interval Default retry max interval (seconds) integer 60 Min: 1
workflow_engine.retry_max_retries Default retry max retries integer 3 Min: 0

Application settings

Key Name Type Default Constraints
document_conversion.timeout_seconds Conversion timeout (seconds) integer 30 Min: 1, Max: 300
document_conversion.overwrite_existing Overwrite existing files boolean false None

Authentication settings

Key Name Type Default Constraints
authentication.local_login_enabled Local login boolean true None
service_accounts.credential_max_lifetime_days Credential maximum lifetime (days) integer true None

Integration settings

Key Name Type Default Restart required Constraints
integrations.health_check_interval_seconds Health check interval integer 300 No Min: 60
integrations.connection_test_timeout_seconds Connection test timeout integer 10 No Min: 1
integrations.health_check_batch_size Health check batch size integer 500 No Min: 1
integrations.discovery_interval_seconds Resource discovery interval integer 900 No Min: 60
integrations.discovery_batch_size Resource discovery batch size integer 500 No Min: 1

Rate Limiting settings

Key Name Type Default Restart required Constraints
rate_limiting.requests_per_window Requests per window integer 0 No Min: 0, Max: 10000
rate_limiting.window_duration_seconds Window duration (seconds) integer 60 No Min: 1, Max: 86400

Use optimistic locking with the Settings API

Use the Settings API optimistic locking feature to prevent concurrent write conflicts when updating runtime settings.

Procedure

  1. Retrieve the setting and note its current version value.
  2. Submit your update with expected_version set to the version you retrieved.

    The API will reject the update if another user modified the setting after you retrieved it. If you omit expected_version, the update proceeds without version checking.

Results

Check the API response:

  • If the version matches, the update succeeds and the version increments.

  • If the API returns a 409 Conflict response:

    1. Re-fetch the setting to get the current value and version.
    2. Evaluate whether your intended change is still appropriate.
    3. Resubmit the update with the new expected_version.