Skip to content
Radioso Docs home
Open app

Settings

Settings are workspace-scoped. They control how Radioso processes documents, presents public surfaces, stores provider credentials, and selects models. Authenticate with the workspace token, and send the request to the host that issued it (Workspaces and tokens).

Retrieval configuration is not a workspace setting. It lives on each agent’s retrieval.answer skill settings. The settings API exposes read-only retrieval defaults so the agent Skills tab can show inherited values for unset fields.

How it works

The setting groups are:

  • ingestion settings for chunking behavior
  • general settings for anonymous chat, assistant defaults, and Enterprise website widget behavior
  • platform settings that merge assistant and channel behavior into one resource
  • model and credential settings for provider access
  • reusable webhook destinations for routine completion export

When ingestion settings change, you can requeue eligible documents so the new chunking or enrichment behavior is applied to existing content.

Retrieval defaults

GET /api/v1/settings/retrieval-defaults returns the system retrieval defaults for the authenticated workspace. It is read-only.

The response includes inherited retrieval values such as:

  • queryRewriteEnabled
  • semanticRewriteInstructions
  • lexicalRewriteInstructions
  • rerankEnabled
  • vectorTopK
  • rerankTopK
  • retrievalStrategy
  • metadataRules
  • customInstruction
  • metadataFieldSuggestions
  • temporalStructuredLookupEnabled
  • temporalBoostUpcomingEnabled
  • temporalDeterministicSortEnabled

metadataRules is empty in the system defaults response. metadataFieldSuggestions is workspace-aware and comes from indexed document metadata. The agent Skills tab uses this endpoint and the retrieve capability descriptor to show inherited values and suggested metadata fields before saving per-agent overrides in skillSettings["retrieval.answer"]. When a retrieve skill field is unset, the dashboard shows the inherited default inline. Saving the form still stores only fields that were explicitly overridden.

To configure retrieval answer behavior, update the agent rather than the settings resource. Retrieval-only API calls, such as POST /api/v1/retrieval/answer, use system defaults and still accept per-call request controls such as metadataFilter.

The three temporal fields default to true. They control whether an agent can use extracted event dates for upcoming-event lookup, upcoming-event boosting, and deterministic date ordering.

Ingestion settings

This payload includes fields such as:

  • chunkingStrategy
  • fixedWindowChunkSize
  • fixedWindowChunkOverlap
  • structuredMinChunkSize
  • structuredMaxChunkSize
  • documentEnrichmentEnabled

Supported chunkingStrategy values are:

  • fixed_window, which keeps predictable fixed-size overlapping chunks for every input type
  • structured_semantic, which uses embedding similarity and format-aware preprocessing
  • recursive_text, which uses natural text boundaries and format-aware preprocessing

For structured_semantic and recursive_text, Markdown and HTML tables use table-aware chunking with repeated headers. Fenced code blocks and source-code documents use code-aware chunking when parser support is available. Fixed-window chunking does not use table-aware or code-aware chunking.

Code-aware chunking is attempted for these language hints and file extensions:

  • Bash, shell, Fish, and Zsh
  • C, C++, C headers, and C#
  • CSS, SCSS, and Less
  • Go
  • Java
  • JavaScript, JSX, JSON, TypeScript, and TSX
  • Kotlin
  • PHP
  • Python
  • Ruby
  • Rust
  • Scala
  • SQL
  • Swift
  • TOML
  • XML
  • YAML and YML

If you change these values and want them applied to existing documents, call:

text
POST /api/v1/settings/ingestion/reprocess

documentEnrichmentEnabled is disabled by default. When enabled, the worker makes one enrichment model call per processed document to classify document shape and extract supported temporal facts. Reprocess requests may include a one-run override:

json
{
  "documentEnrichmentOverride": "on"
}

The override can be on or off. It applies only to the processing jobs created by that reprocess request.

General settings

This payload covers user-facing workspace behavior such as:

  • anonymousChatEnabled
  • anonymousChatLastUsedAt
  • assistantName
  • greetingInstruction
  • assistantDefaultLocale
  • proactiveGreetingEnabled
  • websiteEmbedEnabled
  • websiteEmbedLastUsedAt
  • websiteEmbedAllowedOrigins
  • websiteEmbedLauncherLabel
  • websiteEmbedLauncherPosition
  • websiteEmbedTheme
  • websiteEmbedCopy
  • websiteEmbedExpertOverrides

Enterprise Edition Website widget token rotation and hosted widget customization require the website-embed surface extension. Public chat has its own keys and its own rotation endpoint, so the two placements are enabled and rotated independently even though the dashboard configures both on the agent’s Web chat page.

Public link and embed token rotation use explicit endpoints:

text
POST /api/v1/settings/general/anonymous-chat-token/rotate
POST /api/v1/settings/general/website-embed-token/rotate

Rotation is also the revocation lever: the old link or install code stops launching new sessions the moment the token changes.

Provider credentials

Workspaces can supply their own provider API keys instead of relying on the deployment’s environment variables. Stored keys are encrypted at rest using CONNECTOR_ENCRYPTION_KEY (the same key that protects connector secrets) and are never returned to clients.

GET /api/v1/settings/credentials returns the list of configured providers, whether encryption is configured on the backend, and which providers have a deployment-level environment key available:

json
{
  "encryptionConfigured": true,
  "credentials": [
    { "provider": "claude", "updatedAt": "2026-05-18T18:14:22.123Z" }
  ],
  "envProviderAvailability": {
    "openai": true,
    "openai-compatible": false,
    "gemini": false,
    "claude": false
  }
}

envProviderAvailability reports whether each provider has a deployment-level API key (OPENAI_API_KEY, OPENAI_COMPATIBLE_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY) set. A provider is usable for model selection when it has either a workspace credential or a deployment-level key; the dashboard hides unavailable providers in model pickers.

PUT /api/v1/settings/credentials/:provider stores or replaces a key. The body is { "apiKey": "..." }. Valid provider values are openai, openai-compatible, gemini, and claude. The response is 204 No Content.

DELETE /api/v1/settings/credentials/:provider removes a stored key. The response is 204 No Content, or 404 if no credential was stored for that provider.

If CONNECTOR_ENCRYPTION_KEY is not configured on the backend, writes return 503 encryption_not_configured and GET reports "encryptionConfigured": false. The bootstrap command generates a key automatically; operators can also produce one with openssl rand -base64 32.

Webhook destinations

Webhook destinations are named endpoints that routines can reference by stable id. They are workspace-scoped. A routine stores the destination id, not the URL or the name, so renaming a destination does not break published routines.

Create a destination with a name and an HTTPS URL:

http
POST /api/v1/settings/webhook-destinations
json
{
  "name": "crm-leads",
  "url": "https://example.com/hooks/leads"
}

The create response includes a signing secret once:

json
{
  "destination": {
    "id": "9ce5f2c1-8e47-47d3-b75d-8608e1a4be52",
    "name": "crm-leads",
    "url": "https://example.com/hooks/leads",
    "lastDeliveryStatus": null,
    "lastDeliveryAt": null,
    "createdAt": "2026-06-11T12:00:00.000Z",
    "updatedAt": "2026-06-11T12:00:00.000Z"
  },
  "secret": "..."
}

Store that secret in the receiving system. It is encrypted at rest with CONNECTOR_ENCRYPTION_KEY and is not returned by list, get, or update responses. Use POST /api/v1/settings/webhook-destinations/:id/rotate-secret to issue a new secret. Rotation also returns the new plaintext secret once.

Destination URLs must use HTTPS and must pass the same public-host SSRF policy used by outbound contact webhooks. Local HTTP endpoints are not accepted by default.

Deleting a destination is blocked while any published routine references it. The error names the published routine so you can remove or change the reference first.

When a routine reaches a terminal included in its completion export trigger set, Radioso dispatches webhook.send and posts a JSON body to the destination URL through the existing action outbox. The request includes:

  • Idempotency-Key
  • X-Radioso-Timestamp
  • X-Radioso-Signature

X-Radioso-Signature has the form sha256=<hex digest>. The digest is HMAC SHA-256 over <timestamp>.<raw request body> using the destination secret. Verify against the raw body bytes received by your server, not a re-serialized JSON object.

Delivery uses the same public-host SSRF policy as outbound contact webhooks. Transient transport failures retry through the action outbox. A missing destination, missing conversation agent, or agent with webhook exports disabled is treated as a terminal skip. lastDeliveryStatus is updated to success, retry, failed, or skipped; lastDeliveryAt records when that latest outcome was written.

LLM model selection

Workspaces choose which provider and model are used for each LLM job — chat, query rewrite, rerank. (This is a model-selection job slot, distinct from a skill’s capability field elsewhere in this API, such as retrieve or email — see Agents and skills.) Resolution at request time walks: agent override (chat only) → workspace preference → env default. API keys come from the workspace credential first, then the matching environment variable.

GET /api/v1/settings/llm-models returns the current preferences. null for a job means “inherit env default”:

json
{
  "chat": { "provider": "claude", "model": "claude-sonnet-4-5" },
  "rewrite": null,
  "rerank": null
}

PUT /api/v1/settings/llm-models is a merge-update. Send only the jobs you want to change. Pass null to clear one and fall back to the env default. The response echoes the full resolved preferences.

json
{
  "chat": { "provider": "claude", "model": "claude-sonnet-4-5" },
  "rerank": null
}

The openai-compatible provider also requires OPENAI_COMPATIBLE_BASE_URL to be configured on the backend. Selecting it for a workspace without a base URL fails at resolve time with a clear error instead of silently calling the default OpenAI endpoint.

For per-agent chat model overrides, set chatModelOverride on the agent through PUT /api/v1/agents/<agentId>. null clears the override; { "provider": "...", "model": "..." } sets it.

Endpoint reference

Every settings group takes a different body, and the API Reference documents each one.

text
GET /api/v1/settings/retrieval-defaults
GET /api/v1/settings/ingestion
PUT /api/v1/settings/ingestion
POST /api/v1/settings/ingestion/reprocess
GET /api/v1/settings/general
PUT /api/v1/settings/general
GET /api/v1/settings
PUT /api/v1/settings
GET /api/v1/settings/credentials
PUT /api/v1/settings/credentials/:provider
DELETE /api/v1/settings/credentials/:provider
GET /api/v1/settings/webhook-destinations
POST /api/v1/settings/webhook-destinations
GET /api/v1/settings/webhook-destinations/:id
PUT /api/v1/settings/webhook-destinations/:id
POST /api/v1/settings/webhook-destinations/:id/rotate-secret
DELETE /api/v1/settings/webhook-destinations/:id
GET /api/v1/settings/llm-models
PUT /api/v1/settings/llm-models

Common failure modes

  • 400 usually means the payload is invalid for that settings group.
  • 401 means the workspace token is missing or invalid.
  • 404 on general settings usually means the workspace context is not available.