API v2 Agenten und Einstellungen

Verwenden Sie diese Endpunkte, um Agenten und ihre Einstellungen zu verwalten. Jeder Endpunkt auf dieser Seite erfordert Authorization: Bearer YOUR_API_KEY. Agentenbezogene Routen geben 404 AGENT_NOT_FOUND zurück, wenn der Agent nicht existiert oder nicht dem Konto des API-Schlüssels gehört.

Erfolgreiche Listenantworten verwenden einen data- und pagination-Umschlag. Antworten mit Agentendetails und -einstellungen sind reine Objekte ohne data-Umschlag. Gemeinsame Authentifizierungs- und Validierungsfehler finden Sie im Fehlerkatalog.

Agentenobjekt

{
  "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
  "name": "Support Agent",
  "url": "https://example.com",
  "createdAt": 1784332800,
  "settings": {
    "ai": {
      "model": "openai/gpt-5.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
    }
  }
}

Agenten auflisten

Path: /api/v2/agents

GET /api/v2/agents

Authentifizierung: Bearer-API-Schlüssel.

Erfolg: 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
  }
}

Ungültige Limits oder Cursor führen zu 400 VALIDATION_INVALID_BODY.

Einen Agenten erstellen

POST /api/v2/agents

Authentifizierung: Bearer-API-Schlüssel.

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"}'

Erfolg: 201 Created, mit einem reinen Agentenobjekt.

Ein ungültiger Body führt zu 400 VALIDATION_INVALID_BODY. Wird das Agenten-Kontingent des Workspace überschritten, wird 403 QUOTA_CHATBOT_LIMIT zurückgegeben.

Einen Agenten abrufen

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

GET /api/v2/agents/{agentId}

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK, mit einem reinen Agentenobjekt.

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

Einen Agenten aktualisieren

PATCH /api/v2/agents/{agentId}

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Mindestens ein Feld ist erforderlich.

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"}'

Erfolg: 200 OK, mit dem aktualisierten reinen Agentenobjekt. Ungültige oder leere Bodys führen zu 400 VALIDATION_INVALID_BODY.

Einen Agenten löschen

DELETE /api/v2/agents/{agentId}

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

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

Erfolg: 200 OK

{
  "deleted": true
}

KI-Einstellungsschema

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

Für Aktualisierungen der KI-Einstellungen ist mindestens ein Feld erforderlich.

Aus Gründen der Abwärtskompatibilität akzeptiert model außerdem die eingestellten 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 und google/gemini-3.6-flash. Bestehende Agenten können diese Werte weiterhin gespeichert haben (und GET kann sie weiterhin zurückgeben), sodass ein GET→PATCH-Zyklus stets valide bleibt – sie werden jedoch in der Dashboard-Modellauswahl nicht mehr angeboten, und neue Integrationen sollten den aktuellen Katalog oben verwenden.

KI-Einstellungen abrufen

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK. Das KI-Einstellungsobjekt wird als reines Objekt zurückgegeben; nicht gesetzte KI-Einstellungen ergeben {}.

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

KI-Einstellungen aktualisieren

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {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-5.6-luna","instructionsPreset":"customer-support"}'

Erfolg: 200 OK, mit dem aktualisierten KI-Einstellungsobjekt als reinem Objekt. Ein nicht verfügbares Modell führt zu 403 CHAT_MODEL_NOT_ALLOWED; ungültige oder leere Bodys führen zu 400 VALIDATION_INVALID_BODY.

Design-Einstellungsschema

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

Für Aktualisierungen der Design-Einstellungen ist mindestens ein Feld erforderlich.

Design-Einstellungen abrufen

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK. Die Antwort ist ein reines Objekt mit den aktuellen Gruppen title, language, position, branding und conversation. Nicht gesetzte optionale Schlüssel werden weggelassen.

{
  "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
  }
}

Design-Einstellungen aktualisieren

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {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"]}'

Erfolg: 200 OK. Anders als die GET-Antwort für Design gibt PATCH das vollständige Einstellungsobjekt als reines Objekt zurück. Es kann, wenn gesetzt, diese Felder und Gruppen der obersten Ebene enthalten: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels und identityVerification. Sprachcode-Aliase werden in kanonischer Form zurückgegeben und gespeichert. Ungültige oder leere Bodys führen zu 400 VALIDATION_INVALID_BODY.

Sicherheitseinstellungsschema

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

Für Aktualisierungen der Sicherheitseinstellungen ist mindestens ein Feld der obersten Ebene erforderlich.

Sicherheitseinstellungen abrufen

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK. Das Sicherheitsobjekt wird als reines Objekt zurückgegeben; nicht gesetzte Sicherheitseinstellungen ergeben {}.

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

Sicherheitseinstellungen aktualisieren

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {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"]}}'

Erfolg: 200 OK, mit dem aktualisierten Sicherheitseinstellungsobjekt als reinem Objekt. Ungültige oder leere Bodys führen zu 400 VALIDATION_INVALID_BODY.

Benachrichtigungseinstellungsschema

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

Mindestens ein Feld ist erforderlich.

dailyConversations verhält sich ohne Wert wie false (deaktiviert); dailyEmails und quotaAlerts verhalten sich ohne Wert wie true (aktiviert). Die GET-Antwort enthält nur explizit gesetzte Felder.

Benachrichtigungseinstellungen abrufen

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK. Das Benachrichtigungsobjekt wird als reines Objekt zurückgegeben; nicht gesetzte Benachrichtigungseinstellungen ergeben {}.

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

Benachrichtigungseinstellungen aktualisieren

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {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}'

Erfolg: 200 OK, mit dem aktualisierten Benachrichtigungseinstellungsobjekt als reinem Objekt. Ungültige oder leere Bodys führen zu 400 VALIDATION_INVALID_BODY.

Trainingseinstellungsschema

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

Trainingseinstellungen abrufen

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK. Das Trainingseinstellungsobjekt wird als reines Objekt zurückgegeben; nicht gesetzte Trainingseinstellungen ergeben {}.

{
  "autoRetrainEnabled": true
}

Trainingseinstellungen aktualisieren

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {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}'

Erfolg: 200 OK, mit dem aktualisierten Trainingseinstellungsobjekt als reinem Objekt. Wird automatisches erneutes Trainieren ohne entsprechenden Tarifzugriff aktiviert, wird 403 SUBSCRIPTION_API_RESTRICTED_PLAN zurückgegeben; ungültige Bodys führen zu 400 VALIDATION_INVALID_BODY.

Referenz

• API-v2-Übersicht
• API-v2-Fehlerkatalog
• Quellen und Training