Usable Chat overview

Usable Chat is an authenticated AI chat product built around Usable workspaces and knowledge fragments. It provides:

• First-party web conversations with streaming responses, context, experts, artifacts, images, and sandbox-backed code/data workflows.
• Iframe embeds and whitelabel widgets that host pages control through an SDK/postMessage bridge.
• Public OpenAI-compatible REST endpoints for chat completions, model listing, and image generation, plus a public web-search endpoint.
• Authenticated REST management APIs for embed configurations, embed keys, custom experts, vault secrets, files, applets, projects, shares, conversations, and MCP server profiles.
• A streamable HTTP MCP server at /api/mcp for build-plane operations around experts and embed configurations.

Core concepts

Conversations and messages

A conversation is a sequence of user and assistant turns. The web app persists conversations for authenticated users unless a flow is explicitly temporary or stateless. Embeds can run persistent conversations when a signed-in user token is supplied, or stateless sessions when configured with an embed PAT.

Context

Context may include workspaces, collections, fragments, project context, selected files, current-turn images, and runtime context entries injected by an embed host. Context controls what the assistant can inspect and also influences skill/expert discovery.

The first-party chat route accepts context via URL parameters:

/chat?workspaces=<workspace-id>
/chat?fragments=<fragment-id-1>,<fragment-id-2>
/chat?workspaces=<workspace-id>&collections=<collection-id>&fragments=<fragment-id>

After the first turn, consumed parameters are stripped from the browser URL.

Experts

Experts are reusable assistant configurations: prompt, model preference, enabled tools, optional parent tools for embeds, routing hints, and UI metadata. Experts can be used as subagents or as the main agent for a configured embed.

Embeds

An embed is an iframe rendered from /embed?token=<uc_...>. The token resolves a domain-scoped embed key and configuration. Host pages use a copied SDK to set auth, add context, register parent tools, push images/prompts, receive events, and customize theming.

OpenAI-compatible API

The /api/v1/* APIs are stateless developer endpoints. They are intentionally separate from the first-party web-app agentic chat endpoint: /api/v1/chat/completions accepts OpenAI-shaped messages and function-tool definitions, but does not automatically apply Usable experts, Usable context, or Usable server-side tools.

MCP server

The Chat MCP endpoint exposes management tools for custom experts and embed configurations over streamable HTTP. It is authenticated per request and uses normal product permissions. See the Chat MCP Server guide.

Which guide to read

Public safety notes

• Treat embed keys and bearer tokens as sensitive. Use allowed domains wherever possible.
• Store PATs and vault secret values securely. API responses do not return raw vault secret values after creation.
• Prefer exact iframeOrigin values in SDK instances. Do not use * unless intentional.
• Do not expose internal admin-only tools through parent tools.
• Keep custom HTML/CSS public-safe. Released validation reduces risk but does not replace your own review.