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. Use the signed-in dashboard session for settings that change workspace state, including provider and connector secrets. Personal and service API credentials can call only the eligible read or automation routes documented for them.

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: it merges the fields the document type catalog declares with the keys observed on indexed document metadata, and a declared field wins the value type on a collision. 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, run on system defaults and accept per-call request controls such as metadataFilter.

Pass agentId to run the call the way one agent runs it, using that agent’s source scope, answering instruction, and skillSettings["retrieval.answer"] overrides. The response echoes what it measured in agentScope: the agent it ran as, and retrievalEnabled for whether that agent grounds its answers at all. Without agentId, agentScope is null and the call describes workspace defaults rather than any agent. Scoping to an agent reads that agent’s configuration, so the caller needs workspace.agents.read alongside workspace.retrieval.query and gets 403 without it. An agentId that does not resolve to an agent in the workspace returns 404 rather than an answer measured on workspace defaults.

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: it classifies the document against the workspace document type catalog and extracts the fields that type declares. 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.

Document types

The document type catalog is what extraction classifies against. GET /api/v1/settings/document-types returns the built-in entries merged ahead of the types the workspace defines:

json
{
  "workspaceId": "3f9c...",
  "revision": "7",
  "types": [
    {
      "key": "event",
      "label": "Event",
      "description": "Event announcements — anything scheduled on a date or a date range.",
      "enabled": true,
      "origin": "built_in",
      "payload": "facts",
      "disableable": true,
      "fields": [
        { "key": "dateFrom", "label": "Start date", "valueType": "date", "instruction": "..." },
        { "key": "dateTo", "label": "End date", "valueType": "date", "instruction": "..." }
      ]
    },
    {
      "key": "product",
      "label": "Product",
      "description": "A product detail page: one purchasable item, with a price and availability.",
      "enabled": true,
      "origin": "operator",
      "payload": "fields",
      "disableable": true,
      "fields": [
        { "key": "price", "label": "Price", "valueType": "number", "instruction": "The listed price as a number, without a currency symbol." }
      ]
    }
  ],
  "retiredFields": [{ "key": "sku", "valueType": "string" }],
  "referencedFieldKeys": ["price"]
}

origin separates the five built-in entries — event, article, profile, reference, and the generic fallback — from operator-defined types. Built-in entries are read-only, and generic reports "disableable": false. payload says what a match produces: facts for the built-in dated types, fields for an operator type, none for a type that classifies without extracting anything. retiredFields lists deleted field keys with the value type they keep for good. referencedFieldKeys names the fields some agent’s metadata rules point at; it is advisory, and the dashboard uses it to warn before a delete.

PUT /api/v1/settings/document-types replaces the operator-owned slice of the catalog. It is a conditional write: send the revision your edit was based on, and a stale revision is rejected with 409 so concurrent editors never overwrite each other.

json
{
  "expectedRevision": "7",
  "types": [
    {
      "key": "product",
      "label": "Product",
      "description": "A product detail page: one purchasable item, with a price and availability.",
      "enabled": true,
      "fields": [
        {
          "key": "price",
          "label": "Price",
          "valueType": "number",
          "instruction": "The listed price as a number, without a currency symbol."
        }
      ]
    }
  ],
  "disabledBuiltInTypeKeys": ["profile"]
}

The response is the saved catalog at its new revision. Because the write replaces the whole slice, a type or field you omit is deleted, and its field keys are retired.

Validation answers 400 with a message naming the limit it hit. A workspace holds at most 20 operator types with at most 10 fields each; descriptions run to 500 characters, instructions to 240, labels to 80, and keys to 64. Keys match ^[A-Za-z][A-Za-z0-9_]{0,63}$. dateFrom and dateTo are reserved by the built-in types, disabledBuiltInTypeKeys accepts built-in keys other than generic, and a field key keeps its value type across every type that declares it — including keys already retired. The rendered catalog is also capped at 12,000 prompt characters, checked at save time.

valueType is string, number, date, or boolean, matching the value types a metadata rule compares against.

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

These rotation endpoints accept the signed-in dashboard session. Personal and service API credentials cannot rotate public-launch secrets. 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. This provider-secret inventory is available through the signed-in dashboard session; API credentials cannot read, write, or delete provider secrets:

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 from the signed-in dashboard session. 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 the routines that point at it.

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 a routine’s completion export references it. The error names the 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.

On Radioso Cloud, a workspace on a managed plan (Comet or Satellite) runs the plan catalog’s managed model set: gpt-5.4-mini on OpenAI for chat (answers and Ray), query rewrite, and rerank. The lock applies while the workspace has no credential of its own for the provider its preference or agent override names; add that credential and the preference takes effect exactly as on any other workspace. Planet and self-hosted deployments choose freely. Embedding models are set through ingestion settings and are never managed.

GET /api/v1/settings/llm-models returns the current preferences plus, under managed, what the plan runs instead of them. null for a job means “inherit env default”; null under managed means the workspace’s own choice applies:

json
{
  "chat": { "provider": "claude", "model": "claude-sonnet-4-5" },
  "rewrite": null,
  "rerank": null,
  "managed": {
    "chat": { "provider": "openai", "model": "gpt-5.4-mini" },
    "rewrite": { "provider": "openai", "model": "gpt-5.4-mini" },
    "rerank": { "provider": "openai", "model": "gpt-5.4-mini" }
  }
}

Here the workspace has asked for claude-sonnet-4-5 for chat, but its plan runs gpt-5.4-mini because the workspace holds no Claude key of its own. The dashboard shows the same picture: the picker is read-only with the managed model and a line explaining why. A stored preference stays stored, so it applies as soon as the workspace adds its own key or moves to Planet.

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 is the same shape as GET: the full stored preferences plus the plan’s managed view and knownModelsByProvider, refreshed for the change just applied.

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. The override covers every model call the agent makes on its own turn — planning the turn, assessing how well the retrieved sources cover the question, and composing the answer — so switching an agent to a smaller model cuts the whole turn’s latency, not just the answer’s. Recovery and refusal calls keep their own tiers: the staged router and interpreter that take over when a plan fails to parse run on the deployment’s rewrite default (LLM_REWRITE_PROVIDER / LLM_REWRITE_MODEL, with this workspace’s credentials), and the staged directive matcher and the no-context decline stay on the workspace chat model. Pick a model that can return the plan’s JSON schema: on the openai-compatible provider Radioso does not send that schema to the endpoint, and a model too small to follow it from the prompt alone fails the same way, so every turn pays the planner attempt and then the slower staged path.

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/document-types
PUT /api/v1/settings/document-types
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 dashboard session is missing or invalid, or an API credential was supplied to a session-only settings route.
  • 404 on general settings usually means the workspace context is not available.
  • 409 on the document type catalog means someone saved while you were editing. The error names the current revision; re-read the catalog, reapply your change on top of it, and send it again.