Widgets API

Programmatically manage the widgets in your organization — create new ones, update persona and theme, pause or resume, and fetch live state.

The widget object

{
  "id":            "wgt_abc123",
  "name":          "Northwind Catering",
  "status":        "active",
  "display_mode":  "fab",
  "position":      "bottom-right",
  "voice":         "Charon",
  "persona":       "You are Sam, the friendly catering concierge...",
  "theme": {
    "mode":    "dark",
    "primary": "#b83228",
    "radius":  16
  },
  "intro_title":       "Hi, I'm Sam",
  "intro_subtitle":    "Ask me about catering, menus, or events.",
  "suggested_prompts": ["Can you cater for 50?", "What's on the menu?"],
  "button_label":      "Talk to us",
  "show_label":        true,
  "domains":           ["northwindcatering.example"],
  "created_at":        "2026-04-09T14:12:00Z"
}

List widgets

GET /api/v1/widgets

Returns every widget in the authenticated organization. Supports pagination via ?limit= and ?cursor=.

Get one widget

GET /api/v1/widgets/:id

Create a widget

POST /api/v1/widgets
{
  "name":     "Northwind Catering",
  "site_url": "https://northwindcatering.example"
}

Kicks off a background crawl of your site. Returns immediately with a widget in status: draft. Poll the widget until status becomes active to know the crawl finished, or subscribe to the widget.ready webhook.

Update a widget

PATCH /api/v1/widgets/:id
{
  "persona": "New system prompt...",
  "voice":   "Aoede",
  "theme":   { "primary": "#ff6600" }
}

Any subset of fields is accepted. Updates take effect on new conversations immediately.

Pause / resume

POST /api/v1/widgets/:id/pause
POST /api/v1/widgets/:id/resume

Paused widgets load on your site but refuse to start conversations. Useful for temporarily disabling an agent without removing the script tag.

Delete a widget

DELETE /api/v1/widgets/:id

Cascading delete — removes the widget, its crawled pages, conversation history, domain allowlist, and tool definitions. This action can't be undone. Usage records are preserved for billing reconciliation.

Recrawl a site

POST /api/v1/widgets/:id/recrawl

Re-runs the site crawler to pick up content changes. The widget stays active throughout — visitors see the old index until the new one finishes building (typically 30–60 seconds).

Availability

The public REST API is currently in private beta. If you want access, reach out via Contact and tell us what you want to build. General availability is planned for Q3 2026.