Skip to content
Radioso Docs home
Open app

Chat and history

Use the agent chat endpoint when an API client needs to converse with one configured agent. Its credential carries no workspace role and cannot switch agents.

How it works

  1. Open the agent’s Channels → API card and create a REST credential with a label and expiry.
  2. Copy the one-time secret before closing the result. Radioso stores only its hash.
  3. Send the secret to POST /api/v1/agents/{agentId}/chat and choose whether the response should stream.
  4. Reuse conversationId when you want continuity across turns.
  5. Use a personal token or service-account credential when an operator integration needs to inspect workspace history later.

Agents own assistant identity, instructions, greeting settings, retrieval participation, per-skill settings, and surface settings for authenticated chat, anonymous chat, and website embed. Retrieval answer configuration lives on the agent through skillSettings["retrieval.answer"]; omitted fields inherit system/model defaults. If an agent has retrieval enabled, assistant chat may use retrieval and return citations. Direct-only agents use the direct assistant path and return retrieval diagnostics with retrievalInvoked: false.

Ask a grounded question

This calls the hosted EU API; use https://api-us.radioso.ai or your own self-hosted origin instead, matching the host where the agent credential was issued.

bash
curl -sS -X POST https://api.radioso.ai/api/v1/agents/<agent-id>/chat \
  -H "Authorization: Bearer $RADIOSO_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"What does the FAQ say about uploaded content?","stream":false}'

The chat request schema also supports:

  • conversationId for follow-up turns
  • startConversation: true for bootstrap flows
  • userExpectedLocale when the caller knows the user’s locale

The agent id in the path must match the one stored on the credential. A REST credential for another agent, an MCP-audience credential, a personal token, or a service-account credential receives 401.

Manage REST agent credentials

The API card uses the same lifecycle endpoints as the MCP card, with audience=rest:

text
POST /api/v1/agents/{agentId}/channel-credentials
GET  /api/v1/agents/{agentId}/channel-credentials?audience=rest
POST /api/v1/agents/{agentId}/channel-credentials/{credentialId}/rotate
POST /api/v1/agents/{agentId}/channel-credentials/{credentialId}/revoke

Issuance, rotation, and revocation require a signed-in session with permission to manage that agent. An agent credential cannot call these lifecycle routes itself.

Bootstrap responses are ephemeral. When startConversation: true returns a greeting, the response can omit conversationId. Save and reuse a conversationId only after the first normal user message returns one.

Streaming and non-streaming modes

stream defaults to false; set it per request.

In practice:

  • use stream: false for simple request-response flows
  • use stream: true when you want incremental output

A stream can emit status before the answer begins. Its stage is one of interpreting, searching, or composing. Map these values to localized UI copy in the client; they are not assistant messages. A successful answer then uses chunk and done. A superseded pre-answer turn ends with cancelled, which is terminal.

Chunks indicate incremental delivery, not necessarily live model tokens. Replies that require validation or a durable write can be committed first and replayed in bounded chunks. Clients should ignore unknown event names so additive stream events remain compatible.

Use the API Reference for the exact streaming and non-streaming response contracts.

Conversation history

History is an operator-facing workspace surface. Use a signed-in session or an eligible personal or service-account credential for these calls, not the role-free agent chat credential.

Use GET /api/v1/history to list merged chat and document-search history.

Use GET /api/v1/history/chat to list saved conversations. Add ownership=human_owned to return only conversations currently owned by a human operator; the response total then counts waiting handoffs.

Use GET /api/v1/history/chat/{conversationId} to retrieve one conversation and its debug metadata. The older GET /api/v1/history/{conversationId} route is a compatibility alias.

That second route is the one to use when you need to inspect how a specific answer was produced.

Operator debug metadata can include answerCoverage and interactionTrace. Coverage is a recorded semantic verdict, separate from retrieval and citation details. An assessed partial, unanswered, unclear, or unavailable turn uses a coverage-specific outcome; no_context_refusal means the retrieval answer path actually declined. Interaction decisions include the originating assessment and target message IDs, plus a routine execution ID only after a routine starts.

A turn without a reply still shows up here. If the visitor sent another message before the assistant answered, or the answer attempt failed outright, the interrupted user message carries a turnFailure object: eventStatus of cancelled for the first case (with the pipeline stage it was interrupted at) or failure for the second (with errorMessage). turnFailure is dashboard-only — it never appears on the public or embed conversation reads.

Use GET /api/v1/history/chat/{conversationId}/tail to read messages created after a cursor. The cursor is the newest message the client has already seen. Conversation detail responses include tailCursor; use it for follow-up tail calls after loading the transcript. If cursor is omitted, Radioso returns the newest bounded page and a cursor for the newest returned message. Dashboard tail responses can include ownership when the conversation is currently human-owned.

A conversation detail response can also include visitor (id, firstSeenAt, conversationCount, verified), requestContext (the request facts Radioso observed when the conversation opened, including clientIp), and entryReferrer — the same fields the dashboard’s Visitor panel shows, gated behind the same operator session or credential as the rest of detail. A conversation summary carries visitorCountry alongside them, so a list view can show a country without fetching each conversation’s detail.

Use GET /api/v1/history/visitors/{visitorId}/conversations to page through a visitor’s other conversations — the same summaries GET /api/v1/history/chat returns, scoped to one visitor. Pass exclude to drop one conversation id from the results, typically the one already open. This route needs workspace.history.read, same as the rest of history.

Answer feedback

Persisted assistant answers accept thumbs-up or thumbs-down feedback in the dashboard, public chat, and website embed. A thumbs-down request may include an optional comment of up to 2000 characters. Authenticated callers set and clear feedback on a message:

text
PUT    /api/v1/answer-feedback/messages/{assistantMessageId}
DELETE /api/v1/answer-feedback/messages/{assistantMessageId}

Public chat and embed sessions use the token-scoped variants:

text
PUT    /api/v1/answer-feedback/public/chat/{token}/messages/{assistantMessageId}
DELETE /api/v1/answer-feedback/public/chat/{token}/messages/{assistantMessageId}

Feedback feeds the operator Quality queue, where a thumbs-down turn can be triaged, preserved as an Eval case, and rerun after the underlying fix.

Endpoint reference

text
GET  /api/v1/agents
POST /api/v1/agents
GET  /api/v1/agents/{agentId}
PUT  /api/v1/agents/{agentId}
POST /api/v1/agents/{agentId}/default
POST /api/v1/agents/{agentId}/chat
GET  /api/v1/agents/{agentId}/channel-credentials
POST /api/v1/agents/{agentId}/channel-credentials
POST /api/v1/agents/{agentId}/channel-credentials/{credentialId}/rotate
POST /api/v1/agents/{agentId}/channel-credentials/{credentialId}/revoke
PUT  /api/v1/answer-feedback/messages/{assistantMessageId}
DELETE /api/v1/answer-feedback/messages/{assistantMessageId}
GET  /api/v1/history
GET  /api/v1/history/chat
GET  /api/v1/history/chat/{conversationId}
GET  /api/v1/history/chat/{conversationId}/tail
GET  /api/v1/history/visitors/{visitorId}/conversations
GET  /api/v1/history/search
GET  /api/v1/history/search/{searchId}

Common failure modes

  • 400 usually means the request body is invalid.
  • 401 from agent chat means its REST-audience credential is missing, invalid, expired, or bound to a different agent.
  • 404 can mean the conversation id is not available in the current workspace context.
  • 204 is part of the route contract. Use the reference page for the exact no-body case.