Agents et paramètres API v2

Utilisez ces points de terminaison pour gérer les agents et leurs paramètres. Chaque point de terminaison de cette page nécessite Authorization: Bearer YOUR_API_KEY. Les routes propres à un agent renvoient 404 AGENT_NOT_FOUND lorsque l’agent n’existe pas ou n’appartient pas au compte associé à la clé API.

Les réponses de liste réussies utilisent une enveloppe data et pagination. Les réponses de détail d’agent et de paramètres sont des objets nus, sans enveloppe data. Consultez le catalogue des erreurs pour connaître les erreurs d’authentification et de validation communes.

Objet Agent

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

Lister les agents

Chemin : /api/v2/agents

GET /api/v2/agents

Authentification : clé API Bearer.

Succès : 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
  }
}

Une limite ou un curseur invalide renvoie 400 VALIDATION_INVALID_BODY.

Créer un agent

POST /api/v2/agents

Authentification : clé API Bearer.

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

Succès : 201 Created, avec un objet agent nu.

Un corps invalide renvoie 400 VALIDATION_INVALID_BODY. Le dépassement du nombre d’agents autorisés pour l’espace de travail renvoie 403 QUOTA_CHATBOT_LIMIT.

Obtenir un agent

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

GET /api/v2/agents/{agentId}

Authentification : clé API Bearer ayant accès à {agentId}.

Succès : 200 OK, avec un objet agent nu.

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

Mettre à jour un agent

PATCH /api/v2/agents/{agentId}

Authentification : clé API Bearer ayant accès à {agentId}.

Au moins un champ est requis.

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

Succès : 200 OK, avec l’objet agent nu mis à jour. Un corps invalide ou vide renvoie 400 VALIDATION_INVALID_BODY.

Supprimer un agent

DELETE /api/v2/agents/{agentId}

Authentification : clé API Bearer ayant accès à {agentId}.

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

Succès : 200 OK

{
  "deleted": true
}

Schéma des paramètres d’IA

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

Les mises à jour des paramètres d’IA nécessitent au moins un champ.

Pour la rétrocompatibilité, model accepte aussi les identifiants retirés 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 et google/gemini-3.6-flash. Les agents existants peuvent encore stocker ces valeurs (et une requête GET peut encore les renvoyer), si bien qu’un aller-retour GET→PATCH est toujours valide — mais elles ne sont plus proposées dans le sélecteur de modèle du tableau de bord, et les nouvelles intégrations doivent utiliser le catalogue actuel ci-dessus.

Obtenir les paramètres d’IA

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

Authentification : clé API Bearer ayant accès à {agentId}.

Succès : 200 OK. L’objet des paramètres d’IA est renvoyé nu ; des paramètres d’IA non définis produisent {}.

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

Mettre à jour les paramètres d’IA

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

Authentification : clé API Bearer ayant accès à {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"}'

Succès : 200 OK, avec l’objet des paramètres d’IA mis à jour renvoyé nu. Un modèle indisponible renvoie 403 CHAT_MODEL_NOT_ALLOWED ; un corps invalide ou vide renvoie 400 VALIDATION_INVALID_BODY.

Schéma des paramètres de design

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

Les mises à jour des paramètres de design nécessitent au moins un champ.

Obtenir les paramètres de design

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

Authentification : clé API Bearer ayant accès à {agentId}.

Succès : 200 OK. La réponse est un objet nu contenant les groupes title, language, position, branding et conversation actuels. Les clés optionnelles non définies sont omises.

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

Mettre à jour les paramètres de design

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

Authentification : clé API Bearer ayant accès à {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"]}'

Succès : 200 OK. Contrairement à la réponse GET de design, la réponse PATCH renvoie l’objet complet des paramètres, nu. Il peut contenir les champs et groupes de premier niveau suivants lorsqu’ils sont définis : title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels et identityVerification. Les variantes de langue sont renvoyées et stockées sous leur forme canonique. Un corps invalide ou vide renvoie 400 VALIDATION_INVALID_BODY.

Schéma des paramètres de sécurité

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

Les mises à jour des paramètres de sécurité nécessitent au moins un champ de premier niveau.

Obtenir les paramètres de sécurité

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

Authentification : clé API Bearer ayant accès à {agentId}.

Succès : 200 OK. L’objet de sécurité est renvoyé nu ; des paramètres de sécurité non définis produisent {}.

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

Mettre à jour les paramètres de sécurité

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

Authentification : clé API Bearer ayant accès à {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"]}}'

Succès : 200 OK, avec l’objet des paramètres de sécurité mis à jour renvoyé nu. Un corps invalide ou vide renvoie 400 VALIDATION_INVALID_BODY.

Schéma des paramètres de notifications

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

Au moins un champ est requis.

dailyConversations se comporte comme false (désactivé) lorsqu'il est omis ; dailyEmails et quotaAlerts se comportent comme true (activé) lorsqu'ils sont omis. La réponse GET ne renvoie que les champs définis explicitement.

Obtenir les paramètres de notifications

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

Authentification : clé API Bearer ayant accès à {agentId}.

Succès : 200 OK. L’objet de notifications est renvoyé nu ; des paramètres de notifications non définis produisent {}.

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

Mettre à jour les paramètres de notifications

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

Authentification : clé API Bearer ayant accès à {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}'

Succès : 200 OK, avec l’objet des paramètres de notifications mis à jour renvoyé nu. Un corps invalide ou vide renvoie 400 VALIDATION_INVALID_BODY.

Schéma des paramètres d’entraînement

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

Obtenir les paramètres d’entraînement

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

Authentification : clé API Bearer ayant accès à {agentId}.

Succès : 200 OK. L’objet des paramètres d’entraînement est renvoyé nu ; des paramètres d’entraînement non définis produisent {}.

{
  "autoRetrainEnabled": true
}

Mettre à jour les paramètres d’entraînement

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

Authentification : clé API Bearer ayant accès à {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}'

Succès : 200 OK, avec l’objet des paramètres d’entraînement mis à jour renvoyé nu. Activer le réentraînement automatique sans accès au forfait requis renvoie 403 SUBSCRIPTION_API_RESTRICTED_PLAN ; un corps invalide renvoie 400 VALIDATION_INVALID_BODY.

Référence associée

• Présentation de l’API v2
• Catalogue des erreurs API v2
• Sources et entraînement