API v2 Agents and Settings

Use these endpoints to manage agents and their settings. Every endpoint on this page requires Authorization: Bearer YOUR_API_KEY. Agent-scoped routes return 404 AGENT_NOT_FOUND when the agent does not exist or is not owned by the API key's account.

Successful list responses use a data and pagination envelope. Agent detail and settings responses are bare objects without a data envelope. See the error catalog for shared authentication and validation errors.

Agent Object

{
  "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
  "name": "Support Agent",
  "url": "https://example.com",
  "createdAt": 1784332800,
  "settings": {
    "ai": {
      "model": "openai/gpt-6-luna",
      "instructionsPreset": "ai-chatbot",
      "instructionsPrompt": "Be helpful, accurate, and conversational."
    },
    "title": "AI Assistant",
    "branding": {
      "appearance": "Light",
      "bubbleColor": "#e9e9e7",
      "primaryColor": "#0a0a0a",
      "primaryColorHeader": false
    },
    "position": "bottom-right",
    "conversation": {
      "defaultPrompts": {
        "enabled": false,
        "prompts": [],
        "keepShowing": false
      },
      "initialMessages": ["Hey! What can I help with?"],
      "messagePlaceholder": "Ask our chatbot a question...",
      "showInitialMessageBubble": true
    },
    "features": {
      "attachments": true
    },
    "notification": {
      "dailyConversations": true,
      "dailyEmails": true,
      "quotaAlerts": true
    }
  }
}

List Agents

Path: /api/v2/agents

GET /api/v2/agents

Authentication: Bearer API key.

Success: 200 OK

curl 'https://your-domain.com/api/v2/agents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
      "name": "Support Agent",
      "url": "https://example.com/",
      "createdAt": 1784332800,
      "settings": {}
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Invalid limits or cursors return 400 VALIDATION_INVALID_BODY.

Create an Agent

POST /api/v2/agents

Authentication: Bearer API key.

curl -X POST 'https://your-domain.com/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Support Agent","url":"https://example.com"}'

Success: 201 Created, with a bare agent object.

An invalid body returns 400 VALIDATION_INVALID_BODY. Exceeding the workspace agent allowance returns 403 QUOTA_CHATBOT_LIMIT.

Get an Agent

Path: /api/v2/agents/{agentId}

GET /api/v2/agents/{agentId}

Authentication: Bearer API key with access to {agentId}.

Success: 200 OK, with a bare agent object.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Update an Agent

PATCH /api/v2/agents/{agentId}

Authentication: Bearer API key with access to {agentId}.

At least one field is required.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Customer Support"}'

Success: 200 OK, with the updated bare agent object. Invalid or empty bodies return 400 VALIDATION_INVALID_BODY.

Delete an Agent

DELETE /api/v2/agents/{agentId}

Authentication: Bearer API key with access to {agentId}.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Success: 200 OK

{
  "deleted": true
}

AI Settings Schema

Path: /api/v2/agents/{agentId}/settings/ai

AI settings updates require at least one field.

For backward compatibility, model also accepts the retired slugs openai/gpt-5.5, openai/gpt-5.4, openai/gpt-5.4-mini, openai/gpt-5.4-nano, anthropic/claude-opus-4.7, anthropic/claude-opus-4-6, anthropic/claude-sonnet-4-6, google/gemini-3-flash-preview, and google/gemini-3.6-flash. Existing agents may still store (and GET may still return) these values, so a GET→PATCH round trip always validates — but they are no longer offered in the dashboard model picker, and new integrations should use the current catalog above.

Get AI Settings

GET /api/v2/agents/{agentId}/settings/ai

Authentication: Bearer API key with access to {agentId}.

Success: 200 OK. The AI settings object is returned bare; unset AI settings produce {}.

{
  "model": "openai/gpt-6-luna",
  "instructionsPreset": "customer-support",
  "instructionsPrompt": "Answer using the support documentation."
}

Update AI Settings

PATCH /api/v2/agents/{agentId}/settings/ai

Authentication: Bearer API key with access to {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/ai' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai/gpt-6-luna","instructionsPreset":"customer-support"}'

Success: 200 OK, with the updated AI settings object returned bare. An unavailable model returns 403 CHAT_MODEL_NOT_ALLOWED; invalid or empty bodies return 400 VALIDATION_INVALID_BODY.

Design Settings Schema

Path: /api/v2/agents/{agentId}/settings/design

Design settings updates require at least one field.

Get Design Settings

GET /api/v2/agents/{agentId}/settings/design

Authentication: Bearer API key with access to {agentId}.

Success: 200 OK. The response is a bare object containing the current title, language, position, branding, and conversation groups. Unset optional keys are omitted.

{
  "title": "AI Assistant",
  "language": "en",
  "position": "bottom-right",
  "branding": {
    "appearance": "Light",
    "bubbleColor": "#e9e9e7",
    "primaryColor": "#0a0a0a",
    "primaryColorHeader": false
  },
  "conversation": {
    "defaultPrompts": {
      "enabled": false,
      "prompts": [],
      "keepShowing": false
    },
    "initialMessages": ["Hey! What can I help with?"],
    "messagePlaceholder": "Ask our chatbot a question...",
    "showInitialMessageBubble": true
  }
}

Update Design Settings

PATCH /api/v2/agents/{agentId}/settings/design

Authentication: Bearer API key with access to {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/design' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Support","language":"en-US","appearance":"Dark","prompts":["Track my order"]}'

Success: 200 OK. Unlike the design GET response, PATCH returns the full settings object bare. It can contain these top-level fields and groups when set: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels, and identityVerification. Locale aliases are returned and stored in canonical form. Invalid or empty bodies return 400 VALIDATION_INVALID_BODY.

Security Settings Schema

Path: /api/v2/agents/{agentId}/settings/security

Security settings updates require at least one top-level field.

Get Security Settings

GET /api/v2/agents/{agentId}/settings/security

Authentication: Bearer API key with access to {agentId}.

Success: 200 OK. The security object is returned bare; unset security settings produce {}.

{
  "isPrivate": false,
  "rateLimit": {
    "maxMessages": 20,
    "windowSeconds": 240,
    "limitMessage": "Too many messages in a row"
  },
  "allowedDomains": {
    "enabled": true,
    "domains": ["https://example.com"]
  }
}

Update Security Settings

PATCH /api/v2/agents/{agentId}/settings/security

Authentication: Bearer API key with access to {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/security' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"allowedDomains":{"enabled":true,"domains":["https://example.com"]}}'

Success: 200 OK, with the updated security settings object returned bare. Invalid or empty bodies return 400 VALIDATION_INVALID_BODY.

Notification Settings Schema

Path: /api/v2/agents/{agentId}/settings/notifications

At least one field is required.

dailyConversations behaves as false (disabled) when omitted; dailyEmails and quotaAlerts behave as true (enabled) when omitted. The GET response returns only fields that have been explicitly set.

Get Notification Settings

GET /api/v2/agents/{agentId}/settings/notifications

Authentication: Bearer API key with access to {agentId}.

Success: 200 OK. The notification object is returned bare; unset notification settings produce {}.

{
  "dailyConversations": true,
  "dailyEmails": true,
  "quotaAlerts": true
}

Update Notification Settings

PATCH /api/v2/agents/{agentId}/settings/notifications

Authentication: Bearer API key with access to {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dailyConversations":false}'

Success: 200 OK, with the updated notification settings object returned bare. Invalid or empty bodies return 400 VALIDATION_INVALID_BODY.

Training Settings Schema

Path: /api/v2/agents/{agentId}/settings/training

Get Training Settings

GET /api/v2/agents/{agentId}/settings/training

Authentication: Bearer API key with access to {agentId}.

Success: 200 OK. The training settings object is returned bare; unset training settings produce {}.

{
  "autoRetrainEnabled": true
}

Update Training Settings

PATCH /api/v2/agents/{agentId}/settings/training

Authentication: Bearer API key with access to {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/training' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"autoRetrainEnabled":true}'

Success: 200 OK, with the updated training settings object returned bare. Enabling auto-retrain without plan access returns 403 SUBSCRIPTION_API_RESTRICTED_PLAN; invalid bodies return 400 VALIDATION_INVALID_BODY.

Related Reference

• API v2 overview
• API v2 error catalog
• Sources and training