Settings API

The Settings API manages administrator site configuration and the unauthenticated public settings subset. Admin settings are stored as key-value records and use the unified code, data, and msg response shape.

Endpoint Overview

Authentication and Permissions

Admin endpoints require a JWT or an API key with the corresponding permission:

• admin:settings:read: read settings
• admin:settings:update: update, reset, and trigger notification-channel tests
• audit:export: audit-log archiving (both archive-audit-logs endpoints)

The public settings endpoint requires no authentication. The admin API is primarily used by the administration UI and should not be treated as an anonymous public API.

Read Settings

curl -X GET "https://your-domain.com/api/v1/admin/site-settings?category=general" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

The optional category filter accepts general, security, email, storage, notification, memory, audit, sso, retrieval, dingtalk, wechat, feishu, slack, and webhook. A single-setting response contains key, value, value_type, category, description, and is_public.

Update Settings

Update one setting:

curl -X PUT "https://your-domain.com/api/v1/admin/site-settings/site_name" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"value":"My Clouisle Instance"}'

Bulk update:

{
  "settings": {
    "site_name": "My Clouisle Instance",
    "smtp_enabled": true
  }
}

Send the object to PUT /api/v1/admin/site-settings. The backend validates each value against its type and constraints; inspect data and msg when validation fails.

Background Memory Settings

The memory category queues extraction for pending user turns after the configured cooldown, or immediately when the pending-turn threshold is reached. The Agent must also have memory enabled; disabling either the global switch or the Agent memory feature prevents extraction tasks. The administration page is /site-settings/memory.

Read the category:

curl -X GET "https://your-domain.com/api/v1/admin/site-settings?category=memory" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

The extraction model falls back in this order: explicitly configured enabled model, the Agent's assigned model, the system default chat model, then the first available chat model. The cooldown debounces extraction; reaching the pending-turn threshold queues it immediately.

Reset Settings

curl -X POST "https://your-domain.com/api/v1/admin/site-settings/reset?category=general" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Omit category to reset every setting. Include it to reset only that category.

Public Settings

curl -X GET "https://your-domain.com/api/v1/site-settings/public"

Only fields marked is_public: true are returned, such as the site name, default language, authentication-page layout, theme, registration policy, and knowledge-base upload limit. Background memory settings are not exposed through this endpoint.

Auto Notifications and Tests

Auto-notification configuration uses:

GET /api/v1/admin/site-settings/auto-notifications
PUT /api/v1/admin/site-settings/auto-notifications

Notification test endpoints include test-email, test-dingtalk, test-wechat, test-feishu, test-webhook, and test-slack; all require admin:settings:update. test-email accepts { "email": "admin@example.com" } and requires smtp_enabled to be true, otherwise it returns smtp_not_configured; the other test endpoints take no body, but the channel must be enabled and configured or they return *_not_configured.

Audit-Log Archiving

POST /api/v1/admin/site-settings/archive-audit-logs
GET  /api/v1/admin/site-settings/archive-audit-logs/{task_id}

The start endpoint returns a background task ID. Use the status endpoint to inspect the archive task. Both endpoints require the audit:export permission; once queued, the start endpoint returns { "task_id": "...", "status": "pending" }.

Common Errors

See Site Settings for the administrator-facing configuration guide.

Last Updated: 2026-09-09