API v2-agents en -instellingen

Gebruik deze endpoints om agents en hun instellingen te beheren. Elk endpoint op deze pagina vereist Authorization: Bearer YOUR_API_KEY. Routes die aan een agent zijn gekoppeld, geven 404 AGENT_NOT_FOUND terug als de agent niet bestaat of geen eigendom is van het account van de API-sleutel.

Geslaagde lijstresponses gebruiken een envelop met data en pagination. Responses met agentdetails en -instellingen zijn objecten zonder data-envelop. Zie de foutcatalogus voor gedeelde authenticatie- en validatiefouten.

Agentobject

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

Agents weergeven

Pad: /api/v2/agents

GET /api/v2/agents

Authenticatie: Bearer API-sleutel.

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

Ongeldige limieten of cursors geven 400 VALIDATION_INVALID_BODY terug.

Een agent aanmaken

POST /api/v2/agents

Authenticatie: Bearer API-sleutel.

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

Succes: 201 Created, met een agentobject zonder envelop.

Een ongeldige body geeft 400 VALIDATION_INVALID_BODY terug. Als het agenttegoed van de werkruimte wordt overschreden, geeft de aanvraag 403 QUOTA_CHATBOT_LIMIT terug.

Een agent ophalen

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

GET /api/v2/agents/{agentId}

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK, met een agentobject zonder envelop.

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

Een agent bijwerken

PATCH /api/v2/agents/{agentId}

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Er is minimaal één veld vereist.

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

Succes: 200 OK, met het bijgewerkte agentobject zonder envelop. Ongeldige of lege body's geven 400 VALIDATION_INVALID_BODY terug.

Een agent verwijderen

DELETE /api/v2/agents/{agentId}

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

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

Succes: 200 OK

{
  "deleted": true
}

Schema voor AI-instellingen

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

Voor het bijwerken van AI-instellingen is minimaal één veld vereist.

Voor achterwaartse compatibiliteit accepteert model ook de uitgefaseerde 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 en google/gemini-3.6-flash. Bestaande agents kunnen deze waarden nog steeds opgeslagen hebben (en GET kan ze nog steeds teruggeven), zodat een rondje GET→PATCH altijd geldig is — maar ze worden niet meer aangeboden in de modelkiezer van het dashboard, en nieuwe integraties moeten de huidige catalogus hierboven gebruiken.

AI-instellingen ophalen

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK. Het object met AI-instellingen wordt zonder envelop geretourneerd; niet-ingestelde AI-instellingen leveren {} op.

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

AI-instellingen bijwerken

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

Authenticatie: Bearer API-sleutel met toegang tot {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"}'

Succes: 200 OK, met het bijgewerkte object met AI-instellingen zonder envelop. Een niet-beschikbaar model geeft 403 CHAT_MODEL_NOT_ALLOWED terug; ongeldige of lege body's geven 400 VALIDATION_INVALID_BODY terug.

Schema voor ontwerpinstellingen

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

Voor het bijwerken van ontwerpinstellingen is minimaal één veld vereist.

Ontwerpinstellingen ophalen

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK. De response is een object zonder envelop met de huidige groepen title, language, position, branding en conversation. Niet-ingestelde optionele sleutels worden weggelaten.

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

Ontwerpinstellingen bijwerken

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

Authenticatie: Bearer API-sleutel met toegang tot {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"]}'

Succes: 200 OK. Anders dan bij de GET-response voor ontwerp geeft PATCH het volledige instellingenobject zonder envelop terug. Dit kan, indien ingesteld, de volgende velden en groepen op het hoogste niveau bevatten: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels, en identityVerification. Taalcode-aliassen worden in canonieke vorm teruggegeven en opgeslagen. Ongeldige of lege body's geven 400 VALIDATION_INVALID_BODY terug.

Schema voor beveiligingsinstellingen

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

Voor het bijwerken van beveiligingsinstellingen is minimaal één veld op het hoogste niveau vereist.

Beveiligingsinstellingen ophalen

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK. Het beveiligingsobject wordt zonder envelop geretourneerd; niet-ingestelde beveiligingsinstellingen leveren {} op.

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

Beveiligingsinstellingen bijwerken

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

Authenticatie: Bearer API-sleutel met toegang tot {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"]}}'

Succes: 200 OK, met het bijgewerkte beveiligingsobject zonder envelop. Ongeldige of lege body's geven 400 VALIDATION_INVALID_BODY terug.

Schema voor meldingsinstellingen

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

Er is minimaal één veld vereist.

dailyConversations gedraagt zich als false (uitgeschakeld) wanneer weggelaten; dailyEmails en quotaAlerts gedragen zich als true (ingeschakeld) wanneer weggelaten. Het GET-antwoord bevat alleen expliciet ingestelde velden.

Meldingsinstellingen ophalen

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK. Het meldingsobject wordt zonder envelop geretourneerd; niet-ingestelde meldingsinstellingen leveren {} op.

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

Meldingsinstellingen bijwerken

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

Authenticatie: Bearer API-sleutel met toegang tot {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}'

Succes: 200 OK, met het bijgewerkte meldingsobject zonder envelop. Ongeldige of lege body's geven 400 VALIDATION_INVALID_BODY terug.

Schema voor trainingsinstellingen

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

Trainingsinstellingen ophalen

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK. Het object met trainingsinstellingen wordt zonder envelop geretourneerd; niet-ingestelde trainingsinstellingen leveren {} op.

{
  "autoRetrainEnabled": true
}

Trainingsinstellingen bijwerken

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

Authenticatie: Bearer API-sleutel met toegang tot {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}'

Succes: 200 OK, met het bijgewerkte object met trainingsinstellingen zonder envelop. Automatisch opnieuw trainen inschakelen zonder toegang via het abonnement geeft 403 SUBSCRIPTION_API_RESTRICTED_PLAN terug; ongeldige body's geven 400 VALIDATION_INVALID_BODY terug.

Gerelateerde referentie

• API v2-overzicht
• API v2-foutcatalogus
• Bronnen en training