API Reference

The store / embed agent surface — the widget, its RPC actions, and how to call them.

This page covers the store / embed agent surface — the on-site chat widget (`ck_live_` site-keys) you add to a website or Shopify store. To drive your workspace and company brain programmatically — context search/write, agents, self-prompting — connect over MCP with a `ck_mcp_` token or use the BeeHaven CLI.

Authentication

Store-agent requests authenticate with a site key in the Authorization header:

`
Authorization: Bearer ck_live_your_site_key
`

Keys are managed in Dashboard → Embed & Keys. Use 11px] px-1.5 py-0.5 rounded bg-white/[0.06] text-amber-300 font-mono">ck_test_ keys for development. (Workspace/MCP access uses a separate ck_mcp_ token — see [MCP.)

The on-site widget

The browser widget is the primary store-agent surface. Drop one script tag and it connects to your agent over the Clearly relay — there is no API host you call yourself:

`html
src="https://relay.clearly.sh/clearly-embed.js"
data-site-key="ck_live_your_site_key"
async
>
`

See Custom Embed for all the 11px] px-1.5 py-0.5 rounded bg-white/[0.06] text-amber-300 font-mono">data-* options, and [Shopify Setup for the one-click Theme App Extension.

Agent RPC actions

Action	Description	Plan
chat-message	Send a message and get the agent response	All
sync-catalog	Bulk upsert products	All
record-add-to-cart	Track cart additions	All
record-conversion	Record order conversion	All
record-satisfaction	Submit thumbs up/down	All
get-agent-notes	Fetch auto-generated insights	Pro
update-note-status	Dismiss or action a note	Pro
get-analytics	Query daily analytics	Pro
update-agent-config	Change avatar, name, personality	All

Invoking actions programmatically

The widget invokes these actions for you. To call them from your own code, use the workspace tooling: 11px] px-1.5 py-0.5 rounded bg-white/[0.06] text-amber-300 font-mono">beehaven call {json} from the [CLI, or 11px] px-1.5 py-0.5 rounded bg-white/[0.06] text-amber-300 font-mono">clearly_workspace_invoke over [MCP. Both take the same { action, input } shape.

Example: sync a catalog from the CLI

bash

beehaven connect shopifyStore/your-store-id
beehaven call sync-catalog '{
  "products": [
    { "id": "prod-1", "title": "Blue Widget", "price": 29.99, "in_stock": 1, "inventory_qty": 50 }
  ]
}'

Example: send a chat message over MCP

json

// clearly_workspace_invoke
{
  "action": "chat-message",
  "input": {
    "conversationId": "conv-123",
    "visitorId": "visitor-456",
    "message": "What headphones do you recommend?"
  }
}

Rate limits: the on-site widget is rate-limited per visitor to keep costs bounded, and `ck_test_` keys are capped further (see Testing). Workspace/MCP tokens are rate-limited at 120 requests/minute (see MCP).

Webhooks (outgoing)

Clearly can send webhooks to your backend when store-agent events occur:

-conversation.completed — a conversation ended
-conversion.recorded — an agent-assisted order was placed
-note.created — a new agent insight was generated

Configure webhook endpoints in Dashboard → Embed & Keys → Webhooks.

Analytics & Notes Documentation