Agents API

Programmatically manage the AI agents in your organization — create them, update persona, voice, and appearance, change status, and fetch live state. Gated on the agents.read / agents.write permission.

The agent object

{
  "id":          "uuid",
  "public_key":  "wgt_abc123",
  "name":        "Northwind Catering",
  "status":      "active",
  "voice":       "Charon",
  "persona":     "You are Sam, the friendly catering concierge…",
  "created_at":  "2026-04-09T14:12:00Z"
}

public_key is the value used in the embed snippet and per-agent public endpoints — it keeps the historical wgt_ prefix.

List agents

GET /api/v1/rest/agents   ?status= &limit= &offset=

Get one agent

GET /api/v1/rest/agents/:id

Create an agent

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

Supplying site_url kicks off a background crawl. The agent is returned immediately in status: draft; poll it (or watch the widget.crawl_completed webhook) until status is active.

Update an agent

The complete writable-field schema is in the OpenAPI reference and is shared with the MCP update_agent tool. Newer fields include config_variables, live_chat_alerts and live_chat_alert_scope. Config variable names must be identifiers; agent_name is reserved.

REST PATCH applies immediately. Dashboard configuration edits usually stage a draft; use the draft endpoints to inspect, publish or discard it. Agent moves, checklist attestations and name propagation are documented under Dashboard operations.

PATCH /api/v1/rest/agents/:id
{
  "persona": "New system prompt…",
  "voice":   "Aoede",
  "status":  "paused"
}

Any subset of fields is accepted, and PATCH lets you configure an agent end-to-end without touching the dashboard. Beyond the basics above, the writable fields include:

  • Persona & voice — persona, guardrails, greeting, interruptions (allow|wait), responsiveness (patient|normal|quick), voice_profile_id, default_language, additional_languages, timezone, prompt_modules.
  • Goals & evaluation — goals, data_schema, acceptance_criteria, tracking_rules.
  • Appearance & distribution — theme, position, display_mode, intro_title, intro_subtitle, suggested_prompts, localized_copy (the same three fields per page language, keyed en / fr; merged per language, null removes one), button_label, show_label, logo_url, launcher_icon_url, launcher_icon_kind, domains (replace-set of allowed embed hosts), mcp_pill_enabled, mcp_ui_cards_enabled.
  • Channels & phone — cross_channel_memory, notification_email, notification_phone, voicemail_behavior, and phone_settings (a JSON object — provided keys are merged into the existing object, so a one-key update never wipes the rest).

Set status to paused to stop the agent taking conversations without removing the embed, or active to resume — the transition fires the matching widget.activated / widget.paused webhook. logo_url and launcher_icon_url accept any https URL (dashboard uploads to a hosted asset; the API points at one).

Live config vs. drafts

Dashboard edits stage in a draft until an operator hits Publish; PATCH writes the live config directly (and prunes any overlapping keys from a pending draft so a later publish can't silently revert your write). GET returns has_pending_draft so you can detect a draft that would otherwise change config on publish; read, publish, or discard it via GET/POST/DELETE /api/v1/rest/agents/:id/draft.

Delete an agent

DELETE /api/v1/rest/agents/:id            # keep the agent's knowledge bases
DELETE /api/v1/rest/agents/:id?delete_kbs=true   # also delete KBs exclusive to this agent

Cascading delete — removes the agent and its conversations, crawled pages, and analytics. This cannot be undone. Pass ?delete_kbs=true (needs knowledge.write) to also delete any knowledge bases used only by this agent; KBs shared with another agent are never touched.

Clone, promote, export/import

Duplicate an agent (POST /api/v1/rest/agents/:id/clone), promote its configuration onto a sibling agent (POST .../promote), or move it between workspaces as a portable manifest (GET .../export then POST /api/v1/rest/agents/import). Connect or re-point its website with POST /api/v1/rest/agents/:id/site, and attach data tables, tracking suggestions, training notes, and integration recommendations through their sub-resources.

Warm-transfer routing for an agent is managed through the Transfer rules API. Every one of these fields and sub-resources is also reachable as an MCP tool — see MCP. Full schemas are in the OpenAPI reference.