Skip to main content
← All docs
UUsable
    usable/chat

    Chat REST API

    Updated 2026-07-08

    |Open in||History

    Usable Chat REST API

    Release: v1.173.0

    This reference covers public-facing REST surfaces in Usable Chat. Examples use placeholders and omit private deployment details.

    Authentication

    OpenAI-compatible /api/v1/*

    Use bearer auth:

    Authorization: Bearer TOKEN_PLACEHOLDER

    Embed-facing /api/v2/embed/*

    Embed endpoints require an embed key token query parameter:

    /api/v2/embed/chat?EMBED_KEY_QUERY

    User auth is then resolved through a bearer JWT supplied by the host page or a configured scoped PAT on the embed key.

    Management APIs

    Config/expert/key/vault/project/file/sandbox routes require normal authenticated user/session/PAT access.

    Error format

    OpenAI-compatible endpoints return OpenAI-shaped errors:

    {
  "error": {
    "message": "Model \"bad-model\" was not found",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}
    StatusMeaning
    401Missing/expired auth.
    403Permission gate; web search requires paid access.
    404Missing resource or hidden existence.
    400Validation failure.
    429Rate limit.
    502Upstream provider failure (model/search/image).

    OpenAI-compatible endpoints

    GET /api/v1/models

    Lists chat and image models available to API clients.

    {
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-haiku-4.5",
      "object": "model",
      "owned_by": "anthropic",
      "display_name": "Claude Haiku 4.5",
      "modality": "chat",
      "capabilities": {
        "vision": true,
        "reasoning": false,
        "max_output_tokens": 8192,
        "context_length": 200000
      }
    }
  ]
}

    Use this endpoint to discover available model IDs. Do not hard-code model IDs; availability varies by deployment.

    POST /api/v1/chat/completions

    Stateless OpenAI-compatible chat completions.

    • Supports messages with system, user, assistant, tool roles.
    • User content can be text or an array of text and image_url parts.
    • Supports tools, tool_choice, stream, temperature, max_tokens.
    • Does not automatically use Usable custom experts, Usable context, or Usable server-side tools.
    curl https://YOUR_USABLE_HOST/api/v1/chat/completions \
  -H 'Authorization: Bearer TOKEN_PLACEHOLDER' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "messages": [
      { "role": "system", "content": "You are concise." },
      { "role": "user", "content": "Summarize staged data analysis." }
    ],
    "temperature": 0.2,
    "max_tokens": 500
  }'

    Vision example:

    {
  "model": "anthropic/claude-haiku-4.5",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What is in this image?" },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
    ]
  }]
}

    Function tool example:

    {
  "model": "anthropic/claude-haiku-4.5",
  "messages": [{ "role": "user", "content": "Find order A123" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "lookup_order",
      "description": "Look up an order by order number.",
      "parameters": {
        "type": "object",
        "properties": { "orderNumber": { "type": "string" } },
        "required": ["orderNumber"]
      }
    }
  }],
  "tool_choice": "auto"
}

    Unsupported parameters (will be rejected): parallel_tool_calls, legacy functions/function_call, logprobs, seed, response_format, frequency_penalty, presence_penalty, logit_bias.

    POST /api/v1/images/generations

    OpenAI-compatible image generation.

    curl https://YOUR_USABLE_HOST/api/v1/images/generations \
  -H 'Authorization: Bearer TOKEN_PLACEHOLDER' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A clean product illustration of a green notebook",
    "model": "google/gemini-3-pro-image-preview",
    "size": "1024x1024",
    "response_format": "url"
  }'

    Fields: prompt (1–4000 chars), model, n (must be 1), size, response_format (b64_json or url), quality, style.

    POST /api/v1/web/search

    Neural/keyword/auto web search. Requires paid web-search access.

    {
  "query": "latest Model Context Protocol streamable HTTP info",
  "num_results": 5,
  "type": "neural",
  "include_text": false
}

    GET /api/v1/openapi.json

    Returns the generated OpenAPI 3.1 document for the OpenAI-compatible API.

    Embed-facing endpoints

    POST /api/v2/embed/chat?EMBED_KEY_QUERY

    Submits an embed chat turn and returns a stream.

    {
  "messages": [{ "role": "user", "content": "Help me troubleshoot my order." }],
  "conversationId": "optional-session-id",
  "model": "anthropic/claude-haiku-4.5",
  "contextItems": [{ "contextType": "workspace", "contextId": "workspace-uuid" }]
}

    The route applies embed configuration rules: locked/default model, feature toggles, main-agent expert, stateless mode, system prompt, default context, and auth resolution.

    The response includes X-Embed-Session-Id for stateless sessions. Pass it back as conversationId on follow-up turns.

    POST /api/v2/embed/answer?EMBED_KEY_QUERY

    Resumes a paused structured question:

    {
  "resumeToken": "resume-token-uuid",
  "answers": [{
    "question": "Which product line to analyze?",
    "selected": ["Enterprise"],
    "other": "optional free text"
  }]
}

    POST /api/v2/embed/feedback?EMBED_KEY_QUERY

    Submits feedback when configured for usable-fragment mode:

    {
  "rating": "positive",
  "messageId": "message-id",
  "embedConfigId": "config-uuid",
  "comment": "Very helpful!"
}

    For host-event mode, listen to EVENT / FEEDBACK postMessage instead.

    Embed configuration management

    MethodEndpointPurpose
    GET/api/v2/configsList embed configs (filter by workspaceId, status, limit, offset).
    POST/api/v2/configsCreate an embed configuration.
    GET/PATCH/DELETE/api/v2/configs/{configId}Fetch, update, or archive a config.
    GET/api/v2/configs/{configId}/keysList keys (metadata only; no raw PAT).
    POST/api/v2/configs/{configId}/keysCreate a domain-scoped key (token returned once).
    PATCH/DELETE/api/v2/configs/{configId}/keys/{keyId}Update or revoke a key.

    Create key example:

    {
  "label": "Production",
  "allowedDomains": ["https://www.example.com"],
  "public": false,
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

    Non-public keys require at least one allowed domain. Treat key responses as sensitive.

    Custom expert endpoints

    MethodEndpointPurpose
    GET/api/v2/expertsList custom experts.
    POST/api/v2/expertsCreate a custom expert.
    GET/PATCH/DELETE/api/v2/experts/{id}Fetch, update, or archive an expert.
    GET/api/v2/experts/toolsDiscover tools assignable to experts.

    Create expert example:

    {
  "name": "Support Expert",
  "workspaceId": "workspace-uuid",
  "expertConfig": {
    "systemPrompt": "You are a careful support expert.",
    "enabledTools": ["agentic-search-fragments"],
    "routing": { "keywords": ["order", "return"] },
    "modelPreference": "quick-thinking"
  }
}

    Vault secret endpoints

    MethodEndpointPurpose
    GET/api/v1/vault/secretsList secret metadata (raw values never returned).
    POST/api/v1/vault/secretsCreate a secret.
    GET/PATCH/DELETE/api/v1/vault/secrets/{id}Read metadata, update, or delete.

    Create secret example:

    {
  "name": "EXAMPLE_API_KEY",
  "type": "api-key",
  "provider": "example",
  "value": "secret-value",
  "description": "Used by my custom tool"
}

    Supported types: generic, env-var, api-key, git-github-oauth, git-ssh.

    Workspace file byte proxy (embed parents)

    Read a workspace file

    GET /api/workspace-files/{fileId}/bytes
Authorization: Bearer ***
    • 401: no auth.
    • 403: no upstream access token.
    • 413: file exceeds 50 MiB cap.

    Upload parent-owned bytes

    POST /api/workspace-files/bytes
Content-Type: application/json
    {
  "workspaceId": "workspace_uuid",
  "fileName": "input.csv",
  "mimeType": "text/csv",
  "base64": "c2t1LHByaWNlCkEtMSw0Mg=="
}

    Accepts raw base64 or a data:*;base64,... data URL. Returns { ok: true, fileId, status? }. These routes are used by chat.workspaceFiles.readBytes() and chat.workspaceFiles.putBytes() after features.workspaceFiles.exposeToParent is enabled.

    Beta feature settings

    GET /api/user/beta-features

    Returns the authenticated user's beta-feature grants.

    PATCH /api/user/beta-features

    { "featureKey": "beta-features", "enabled": true }

    MCP endpoint

    /api/mcp is the streamable HTTP MCP endpoint for managing experts and embed configurations from AI clients. See Chat MCP Server for client configuration and tool reference.

    OAuth/OIDC discovery

    EndpointPurpose
    GET /.well-known/openid-configurationOIDC discovery.
    GET /.well-known/oauth-authorization-serverOAuth authorization server metadata.
    GET /.well-known/oauth-protected-resourceProtected-resource metadata; advertises /api/mcp as the MCP resource.