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
  • the workspace time zone, the day “today” and “tomorrow” mean in answers
  • 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 event dates to look up dated evidence (in the date range a question names, or upcoming events for a question that lists them), to boost it, and to order it by date.

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.

Time zone

A question like “what’s on tomorrow?” is answered against today’s date, and today depends on where the visitor is: at 18:00 in Los Angeles it is already tomorrow in UTC. The workspace time zone is the zone Radioso reads today’s date in for a turn whose visitor reports no zone of their own. Email, Slack and voice conversations, evals, Retrieval API and MCP calls, and website visitors whose browser reports no zone all use it. Document enrichment reads it too: a relative date in a document, such as “next Friday”, counts from the day the document was created in this zone.

text
PUT /api/v1/settings/time-zone
json
{ "timeZone": "America/Los_Angeles" }

timeZone is an IANA zone name, and GET /api/v1/settings/time-zone reads back the name you saved: Asia/Kolkata stays Asia/Kolkata, though the server’s zone data also knows that zone as Asia/Calcutta. A name the zone data lists comes back in its listed case, so america/los_angeles reads back as America/Los_Angeles. null, the default, reads today in UTC. A name the server’s zone data does not know, or a fixed offset such as +05:00, answers 400. Reading needs workspace.settings.read and setting it needs workspace.settings.manage; each change records a workspace.time_zone_settings.updated audit event with the zones it moved between.

The zone decides every “today” a turn reads: the query rewrite that turns “this weekend” into dates, the answer and rerank prompts, the upcoming-events lookup, the today() token in metadata rules, and a routine’s date slots and lookups. A visitor’s own zone takes precedence for their turns: the website embed and the hosted chat page send the browser’s zone, Test Chat sends the operator’s, and the chat APIs take userTimeZone (see Chat and history). A routine resumed by an approval click has no visitor request behind it, so it reads the zone of the visitor’s last message, then the workspace zone. An unknown visitor zone is ignored and the workspace zone applies; UTC applies only when no zone is named at all.

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 the model providers openai, openai-compatible, gemini, and claude, and the voice runtime elevenlabs. The response is 204 No Content.

The elevenlabs key is the one Radioso creates and maintains an agent’s ElevenLabs agent with (Connect on the agent’s Voice card, which needs the key’s Agents permission with write access) and starts ElevenLabs voice sessions with, so a web page can open a call without holding it. It is always the workspace’s own: there is no deployment-level ElevenLabs key, so envProviderAvailability lists only the model providers. The dashboard shows it under Settings → Providers → Voice runtime keys.

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 managed plan (Comet, Satellite, or Planet with Radioso’s models) runs the catalog’s managed model set for chat (including Ray), query rewrite, and rerank, using Radioso deployment credentials. A stored key for the provider a capability selected lifts that managed default for that capability; remove the key to return to Radioso’s managed model. Planet and self-hosted deployments choose freely: a workspace key takes precedence over the plan’s default, and resolution falls back to the deployment’s environment key when the workspace has none. 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 managed plan runs gpt-5.4-mini because the workspace has no Claude key. The dashboard shows the same picture: the picker is read-only with the managed model and a line explaining why. Adding a Claude workspace key lifts the managed default for chat and applies the stored preference; removing the key restores the managed default. The same override rule applies to every managed plan, including Planet with Radioso’s models.

The response also carries two model lists per provider. knownModelsByProvider is every model Radioso supports. runnableModelsByProvider is the subset this workspace can run, and it is what the dashboard pickers offer. The two match unless the deployment’s shared OpenAI key is an Azure OpenAI key: then runnableModelsByProvider.openai holds only the models deployed for it (see Data residency), until the workspace adds its own OpenAI key.

PUT /api/v1/settings/llm-models is a merge-update. Send only the jobs you want to change. Pass null to clear one and use the policy’s default provider and model: the managed default on a managed plan, or the environment default otherwise. The response is the same shape as GET: the full stored preferences plus the plan’s managed view and both model lists, refreshed for the change just applied. A model outside runnableModelsByProvider is refused with 400, and the error message lists the models the workspace can run; re-sending the model a job already stores is accepted.

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, and takes a model from runnableModelsByProvider under the same rule as a workspace preference. 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/time-zone
PUT /api/v1/settings/time-zone
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. On PUT /api/v1/settings/llm-models it can also mean the model is supported but this workspace cannot run it; pick one from runnableModelsByProvider or add the workspace’s own key for that provider.
  • 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.