API des agents IA #

Un agent IA est le cerveau derrière votre bot : ses instructions, sa personnalité, sa langue, ses connaissances et ses outils. Vous créez un agent une fois, puis vous y dirigez le trafic. Ce guide couvre tout ce que vous pouvez faire avec un agent via l’API : le créer, le configurer, lui fournir des connaissances et des outils, examiner ses brouillons et lui acheminer des conversations.

• URL de base — https://api.youraiconnector.com/v1
• Authentification — votre clé API (voir Authentification)
• Erreurs et pagination — voir Erreurs et pagination

Tous les exemples ci-dessous utilisent le format de requête ?apiKey= en cURL et l’en-tête X-API-Key en JavaScript et Python — les deux fonctionnent sur chaque point de terminaison.

Si vous découvrez le concept d’agent, lisez d’abord Agents IA.

Comment un agent est structuré #

Quatre éléments sont gérés séparément, et il est utile de savoir de quoi il s’agit avant de commencer :

Un nouvel agent ne répond à personne tant que vous ne lui acheminez pas de trafic. Créer un agent ne l’ajoute pas à un canal. C’est l’étape que la plupart des intégrations oublient — voir Acheminer des conversations vers un agent à la fin de cette page.

L’objet Agent #

Un document d’agent complet est volumineux — plusieurs centaines de kilo-octets, principalement sa liste de FAQ, ses sources de connaissances et tout contenu de page lu sur votre site web. Pour cette raison, la liste renvoie une ligne de résumé courte par agent lorsque vous la demandez :

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Le document complet ajoute tout le reste : instructions, rules, personality, availability, follow_up_config, les listes de FAQ et de sources de connaissances liées, les blocs de texte générés et tout état d’exécution (tag_generation, optimize_run).

Certaines réponses contiennent également substrate_campaign_id. Il s’agit d’un enregistrement interne conservé sur les anciens comptes ; vous n’avez jamais besoin d’intervenir dessus, et sur les nouveaux comptes, il est null ou absent.

Lister les agents #

GET /agents — chaque agent du compte, du plus récent au plus ancien.

Ce point de terminaison n’est pas paginé. Par défaut, chaque Agent est renvoyé avec sa configuration complète, ce qui est lourd : un seul Agent peut atteindre 580 Ko et un compte de 64 Agents plus de 3 Mo. Passez view=summary pour obtenir une ligne courte par Agent à la place, puis lisez celui que vous souhaitez avec Obtenir un Agent.

Paramètres de requête

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Réponse (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Créer un Agent #

POST /agents — seul name est réellement nécessaire ; envoyez toute configuration que vous connaissez déjà en complément. Un nouvel Agent est actif par défaut.

Champs de requête (tous facultatifs sauf name)

Construire un Agent à partir de votre site web. Incluez scrape_urls et la plateforme lira ces pages pour rédiger les instructions à votre place. La réponse vous indique si cette génération a démarré, afin que vous sachiez si vous devez interroger l’Agent pour suivre la progression.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Réponse (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued est true lorsque la plateforme a commencé à rédiger les instructions à partir des pages que vous avez fournies.

Une 400 signifie que le corps n’était pas un objet JSON, qu’un champ a été rejeté ou que l’Agent dépasse la taille de configuration autorisée par votre forfait. Une 403 signifie que le compte n’est pas autorisé à utiliser l’un des paramètres que vous avez envoyés — par exemple un niveau d’IA que son fournisseur de compte n’a pas accordé.

Obtenir un Agent #

GET /agents/{agentId}

Passez fields avec une liste séparée par des virgules pour ne récupérer que ce dont vous avez besoin, par exemple fields=name,active,goal. Le id est toujours inclus, et les noms qui n’existent pas sur l’Agent sont ignorés plutôt que rejetés. Omettez-le pour obtenir le document complet.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Un Agent qui n’existe pas sur votre compte renvoie 404.

Mettre à jour un Agent #

PUT /agents/{agentId} — envoyez uniquement les champs que vous souhaitez modifier ; tout le reste est laissé intact.

Les paramètres imbriqués peuvent être adressés feuille par feuille avec une clé pointée, ainsi "availability.monday" ne modifie que le lundi et laisse le reste de la semaine inchangé.

Remarques

• Pour modifier le type d’événement réservable dans lequel l’Agent effectue des réservations, envoyez event_id (l’identifiant de l’événement, ou null pour le supprimer). Envoyez event_ids avec un tableau pour en lier plusieurs à la fois — le premier devient le principal et [] dissocie tout. event_id et event_ids sont mutuellement exclusifs, et le champ event lui-même ne peut pas être écrit directement.
• enable_bookings doit être un booléen réel, et booking_provider doit être l’un des éléments suivants : default, zenchef, formitable.
• Les champs de propriété et d’identité sont ignorés, tout comme l’état d’exécution interne (progression de la génération et de l’optimisation).
• Le routage n’est pas défini ici. Utilisez PUT /entry-points/channel-defaults pour faire de l’Agent le répondant d’un canal, POST /agents/{agentId}/entry-points pour les règles de mots-clés et de commentaires, et PATCH /agents/{agentId}/active pour le mettre en pause ou le reprendre.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Un corps vide renvoie 400 avec "No fields to update".

Mettre à jour les paramètres du bot #

PUT /agents/{agentId}/bot-config — la méthode ciblée pour modifier uniquement les paramètres de conversation.

Un Agent ne possède pas de section bot distincte : ses paramètres se trouvent directement sur l’Agent, les noms des champs ici sont donc les mêmes que ceux que vous enverriez à PUT /agents/{agentId}. Ce point de terminaison existe en tant que moyen sûr et ciblé pour en modifier quelques-uns. Au moins un champ est requis.

Les noms des champs doivent être des noms simples ici — lettres, chiffres, traits de soulignement et tirets. Les chemins pointés ne sont pas acceptés sur ce point de terminaison (contrairement à PUT /agents/{agentId}), donc bot.goal est rejeté avec une 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Un texte long est comptabilisé dans la taille de configuration autorisée par votre forfait, un ensemble d’instructions très volumineux peut donc être refusé avec une 400.

Définir les heures d’activité #

PUT /agents/{agentId}/active-hours — les heures pendant lesquelles l’Agent répond automatiquement. En dehors de ces fenêtres, il reste silencieux.

Envoyez un objet availability indexé par jour de la semaine (monday à sunday). Chaque jour prend une seule fenêtre horaire ou une liste de fenêtres, au format HH:MM 24 heures. Les jours que vous omettez conservent leurs paramètres actuels, et toute clé qui n’est pas un jour de la semaine est rejetée — ainsi, une faute de frappe ne peut pas rester sans effet.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Une clé de jour de la semaine incorrecte renvoie 400 : "Invalid availability keys: funday. Allowed keys: monday through sunday."

Mettre en pause ou reprendre un Agent #

PATCH /agents/{agentId}/active — active ou désactive l’Agent. Un Agent en pause conserve toute sa configuration mais cesse de répondre immédiatement ; la reprise prend effet instantanément.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active doit être un booléen valide — toute autre valeur renvoie 400 avec "active (boolean) is required".

Dupliquer un Agent #

POST /agents/{agentId}/duplicate — crée une copie avec sa configuration préservée. La copie n’envoie rien tant que vous ne lui avez pas assigné un canal ou un point d’entrée.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Réponse (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Un doublon est comptabilisé dans le quota d’Agents de votre forfait exactement comme la création d’un nouvel Agent ; il est donc refusé avec 403 lorsque le compte a atteint sa limite.

Supprimer un Agent #

DELETE /agents/{agentId}

La suppression est refusée tant que l’Agent est encore attaché à un élément qui cesserait de fonctionner sans lui — une diffusion, un point d’entrée ou (sur les anciens comptes) une campagne. La réponse liste ce qui le retient afin que vous puissiez d’abord les détacher et réessayer.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Bloqué (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Brouillons : examinez les modifications avant leur mise en ligne #

Les modifications effectuées dans l’éditeur, ainsi que toute réécriture produite par Optimiser avec l’IA, sont conservées en tant que brouillon non publié jusqu’à ce que vous les publiiez. L’Agent en ligne continue de répondre avec sa configuration actuelle jusque-là.

Publier le brouillon #

POST /agents/{agentId}/publish-draft — déplace le brouillon vers la configuration en ligne et efface le brouillon en une seule étape.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys liste les paramètres qui ont été transférés du brouillon vers l’Agent en ligne, afin que vous puissiez voir ce qui a changé.

Vérifiez qu’un brouillon existe avant d’appeler cette fonction. Publier un Agent qui n’a pas de brouillon n’est pas un appel pris en charge et renvoie actuellement un 500 avec un message générique, et non spécifique. Pour supprimer un brouillon à la place, utilisez l’option d’abandon ci-dessous.

Ignorer le brouillon #

POST /agents/{agentId}/discard-draft — supprime le brouillon et laisse la configuration active telle quelle. Peut être appelé en toute sécurité lorsqu’il n’y a pas de brouillon ; rien ne se passe.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Optimiser un Agent avec l’IA #

POST /agents/{agentId}/optimize — réécrit la configuration de l’Agent à partir de vos commentaires (« il continue d’offrir des remises », « les réponses sont trop longues ») et enregistre la réécriture en tant que brouillon plutôt que de la mettre en ligne.

Envoyez soit user_feedback (une instruction simple), soit, lors d’une réaction à une mauvaise réponse spécifique, thumbs_down_feedback accompagné du thumbs_down_message incriminé. Au moins l’un des deux doit contenir du texte.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Réponse (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Le travail s’exécute en arrière-plan et l’appel renvoie immédiatement. Lisez l’Agent avec GET /agents/{agentId} et surveillez optimize_run.status ; une fois revenu à Draft, la réécriture attend en tant que brouillon de l’Agent. Examinez-la, puis publiez-la ou ignorez-la.

Une seule exécution à la fois par Agent — un second appel alors qu’une exécution est en cours renvoie 409. Cela utilise des crédits IA.

Règles de marquage #

Une règle de marquage est un tag accompagné d’une description du moment où il s’applique. Au cours d’une conversation, l’Agent lit cette description et marque le contact lorsqu’elle correspond, ce qui permet de déclencher les automatisations basées sur les tags.

L’objet règle

Ajouter une règle de marquage #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Remplacer une règle de marquage #

PUT /agents/{agentId}/tags/{tagId} — la règle est trouvée par l’identifiant de balise dans le chemin et remplacée intégralement, et non fusionnée. Envoyez donc la règle complète plutôt que seulement la partie que vous modifiez. La balise vers laquelle elle pointe est préservée même si vous omettez tag_id, une modification ne peut donc pas détacher la règle de sa balise.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Supprimer une règle de balisage #

DELETE /agents/{agentId}/tags/{tagId} — l’Agent cesse d’appliquer cette balise. La balise elle-même, ainsi que tous les contacts qui en sont déjà porteurs, restent inchangés.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Les deux points de terminaison renvoient 404 lorsque l’Agent n’existe pas ou lorsqu’il n’a aucune règle pour cette balise.

Générer un ensemble de balises avec l’IA #

POST /agents/{agentId}/tags/generate — conçoit un ensemble complet de règles (les noms des balises et la formulation « appliquer quand… » derrière chacune) en lisant les instructions et l’objectif propres à l’Agent.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Réponse (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

Le travail s’exécute en arrière-plan. Lisez l’Agent et surveillez tag_generation.status ; les règles elles-mêmes atterrissent dans le champ tags de l’Agent. Une seule exécution à la fois par Agent (409 sinon), et cela utilise des crédits d’IA.

Sources de connaissances #

Les sources de connaissances sont les pages et les documents que la plateforme a lus pour vous. En attacher une à un Agent lui permet de répondre à partir de ce contenu.

D’où proviennent les identifiants de source. Ajoutez du contenu avec les points de terminaison de la base de connaissances — POST /kb-sources/url pour une page, POST /kb-sources/file pour un document, POST /kb-sources/bulk-import pour un site entier. Ceux-ci renvoient un source_id que vous interrogez avec GET /kb-sources/{sourceId} jusqu’à ce qu’il soit prêt. POST /kb-sources/url accepte également autoLinkToAgentId, qui attache la source à un Agent dès que l’importation est terminée, vous permettant ainsi de sauter l’appel d’attachement ci-dessous.

Attacher des sources de connaissances #

POST /agents/{agentId}/kb-sources — envoyez kb_source_ids avec une liste pour attacher un ensemble complet en un seul appel (ce que vous voulez après avoir exploré un site), ou kb_source_id pour une seule source. Envoyez l’un ou l’autre. Attacher quelque chose qui l’est déjà ne change rien.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Réponse (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Détacher des sources de connaissances #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} pour un seul, ou POST /agents/{agentId}/kb-sources/bulk-remove avec kb_source_ids pour plusieurs. La suppression en masse est une POST car la liste des identifiants est transmise dans le corps de la requête.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Les sources elles-mêmes ne sont pas supprimées et restent disponibles pour vos autres Agents. Détacher un élément qui n’est pas attaché ne change rien.

FAQ #

Les FAQ sont gérées sur leurs propres points de terminaison et liées à un Agent à partir de là : POST /faqs/{faqId}/link avec { "agent_id": "ag7HkQ2ZpLxR3mNb" }, et POST /faqs/{faqId}/unlink pour le retirer à nouveau. Une FAQ peut être partagée par n’importe quel nombre d’Agents. Voir l’API FAQ.

Une FAQ n’est utilisée que par les Agents auxquels elle est liée — en créer une ne suffit pas en soi.

Outils #

Fonctions personnalisées #

POST /agents/{agentId}/custom-functions permet à l’Agent d’appeler l’une de vos fonctions personnalisées pendant les conversations. Seules les fonctions appartenant au même compte peuvent être attachées, et en attacher une qui l’est déjà ne change rien.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} la détache. La fonction elle-même n’est pas supprimée et reste disponible pour vos autres Agents.

Gérez les fonctions elles-mêmes sur /custom-functions — voir Fonctions personnalisées pour savoir ce qu’elles sont.

Serveurs MCP #

Un serveur MCP est un ensemble d’outils prêts à l’emploi que votre Agent peut découvrir et appeler de lui-même — voir Connecter des serveurs MCP à votre bot. Les serveurs sont enregistrés une fois sur le compte, puis attachés aux Agents qui doivent les utiliser.

Les serveurs MCP nécessitent la fonctionnalité fonctions personnalisées sur votre forfait. Sans cela, les points de terminaison /mcp-servers au niveau du compte renvoient 403. L’attachement d’un serveur déjà enregistré à un Agent n’est pas restreint.

Enregistrer un serveur #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Réponse (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Lors de l’enregistrement, la plateforme se connecte au serveur et met en cache la liste des outils qu’il propose. Un serveur injoignable est tout de même enregistré, avec le motif dans last_error et une liste d’outils vide — vous pouvez donc l’enregistrer d’abord et résoudre les problèmes de connectivité ensuite.

Un auth_type de oauth2 enregistre l’inscription avec oauth_connected: false et aucun outil : il n’y a pas encore de jeton. L’autorisation d’un serveur OAuth nécessite une connexion via navigateur et s’effectue depuis le tableau de bord, et non via l’API.

Lister, mettre à jour et supprimer des serveurs #

• GET /mcp-servers — tous les serveurs enregistrés, du plus récent au plus ancien, sous servers.
• PUT /mcp-servers/{serverId} — envoyez uniquement ce que vous souhaitez modifier. La modification de l’URL ou des champs d’authentification relance le test de connexion et actualise la liste des outils en cache.
• DELETE /mcp-servers/{serverId} — supprime l’enregistrement et le dissocie de chaque Agent et campagne pour lesquels il était activé.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Les secrets ne sont jamais renvoyés. Les réponses contiennent auth_header_value_set (un indicateur true/false signalant qu’une valeur est stockée) au lieu de l’identifiant, et les jetons OAuth ainsi que les secrets client restent côté serveur. Tout le reste est renvoyé : name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Tester une connexion #

POST /mcp-servers/test-connection — se connecte à un serveur et liste ses outils. Deux façons de l’appeler :

• avec server_id — teste la configuration enregistrée et actualise sa liste d’outils en cache ;
• avec un url en ligne (plus auth_header_name / auth_header_value) — un test avant enregistrement qui ne stocke rien.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Réponse (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Un échec de connexion n’est pas une erreur HTTP — vous obtenez un 200 avec success: false et un error décrivant ce qui a échoué, afin que vous puissiez l’afficher à côté du champ que l’opérateur est en train de modifier.

Attacher un serveur à un Agent #

L’enregistrement d’un serveur ne donne accès à aucun Agent. Attachez-le :

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Réponse (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} le détache à nouveau. Le serveur lui-même n’est pas supprimé et reste disponible pour vos autres Agents. Attacher ou détacher quelque chose qui est déjà dans cet état ne change rien.

Bibliothèque multimédia #

La bibliothèque multimédia contient les fichiers qu’un Agent peut envoyer au cours d’une conversation — un menu, une liste de prix, une photo de produit. Un Agent peut contenir au maximum 50 éléments.

Lister les médias #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Réponse (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Les éléments stockés sur l’Agent apparaissent en premier, suivis des éléments plus anciens toujours stockés sur la campagne à partir de laquelle l’Agent a été créé ; media_home (agent ou campaign) indique de quel type il s’agit. Au sein de chaque groupe, le plus récent est affiché en premier.

media_url expire après 7 jours. Il s’agit du lien de téléchargement créé lors du chargement du fichier — considérez un ancien lien comme obsolète plutôt que rompu, et relisez la liste pour obtenir un lien actualisé.

Charger un média #

POST /agents/{agentId}/media-library — le fichier est chargé en ligne au format base64, jusqu’à 10 Mo. L’appel renvoie une réponse une fois le fichier stocké, prévoyez donc un délai légèrement plus long que pour une requête normale. Notez que ce corps utilise des noms de champs en camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Deux choses se produisent automatiquement : un GIF animé est converti en vidéo afin qu’il puisse être lu sur tous les canaux, et la plateforme rédige un court résumé du contenu réel du fichier afin que l’Agent sache quand il est approprié de l’utiliser.

Une erreur 400 couvre les champs manquants, un type de fichier non pris en charge, un fichier vide ou trop volumineux, et l’atteinte de la limite de 50 éléments. Une erreur 403 signifie que la bibliothèque multimédia est désactivée pour le compte.

Mettre à jour un élément multimédia #

PATCH /agents/{agentId}/media-library/{itemId} — métadonnées uniquement. Le fichier lui-même ne peut pas être remplacé ; chargez un nouvel élément et supprimez l’ancien. Ce corps utilise le format snake_case : title, description, send_message, max_sends_per_conversation (un nombre entier non négatif, ou null pour supprimer la limite).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Réponse (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Supprimer un élément multimédia #

DELETE /agents/{agentId}/media-library/{itemId} — supprime l’élément et son fichier stocké. La suppression d’un élément déjà disparu réussit et renvoie deleted: false, l’appel peut donc être relancé en toute sécurité.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Générer des messages de suivi #

POST /agents/{agentId}/template-generation — rédige pour vous les messages de suivi de l’Agent (les relances envoyées lorsqu’une conversation s’essouffle), en fonction de l’objectif de l’Agent.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Il existe deux façons d’obtenir ce résultat, et le champ target vous indique laquelle :

• target: "agent" avec un 200 — les messages ont été écrits pendant l’appel et le résultat se trouve dans data. Relisez-les depuis le follow_up_config de l’Agent. C’est le cas habituel.
• target: "campaign" avec un 202 — le travail a été mis en file d’attente pour la campagne nommée dans campaign_id. Surveillez le template_generation_status de cette campagne jusqu’à ce qu’elle se termine.

cold_only nécessite une campagne sortante et est refusé avec 409 (reason: "cold_only_requires_campaign") sur un Agent qui n’en a aucune. Un 403 signifie que les suivis automatiques ne sont pas activés pour le compte. Cela utilise des crédits IA, et un 400 avec "Insufficient credits." signifie que le compte est à court de crédits.

Acheminement des conversations vers un Agent #

Un Agent ne répond qu’aux conversations qu’un Point d’entrée lui envoie. Tant qu’un canal n’en possède pas, un premier message provenant d’une personne à qui vous n’avez jamais parlé est bien stocké, mais rien ne le récupère et aucun assistant ne répond.

Lister les points d’entrée d’un Agent #

GET /agents/{agentId}/entry-points — les règles d’acheminement qui envoient des conversations à cet Agent, de la plus récente à la plus ancienne. Les règles actuelles et retirées sont renvoyées ; une règle retirée possède enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Pour les paramètres par défaut des canaux de l’ensemble du compte, y compris un canal délibérément défini sur personne, lisez plutôt GET /entry-points/channel-defaults.

Créer un point d’entrée #

POST /agents/{agentId}/entry-points — l’Agent dans le chemin est toujours prioritaire, donc une règle ne peut jamais être créée pour un Agent différent de celui présent dans l’URL.

channels est requis et indique quels canaux la règle couvre — par exemple whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget ou custom_channel. Les nouvelles règles sont activées sauf indication contraire de votre part.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Réponse (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Quelle règle l’emporte lorsque plusieurs sont applicables : une conversation en cours ou une attribution manuelle conserve l’Agent qu’elle a déjà ; sinon, les règles de mots-clés l’emportent sur les règles de commentaires, qui l’emportent sur les règles d’abonnés, et un défaut de canal est le dernier recours. Le fait que ces règles décident de quelque chose sur un compte est rapporté par GET /entry-points/routing-status.

Ceci est la version courte. Le guide de l’API Points d’entrée couvre l’intégralité des règles concernant les échelles, les commentaires et les abonnés, la limite d’un agent par numéro WhatsApp, ainsi que la modification ou la suppression d’une règle. Consultez Points d’entrée pour le concept, et l’API Canaux pour connecter le canal lui-même.

Erreurs de l’API des agents IA #

Les points de terminaison des agents renvoient l’enveloppe d’erreur standard :

{
  "success": false,
  "error": "Agent not found"
}

Les codes partagés que chaque point de terminaison peut renvoyer — 401, 403 (votre forfait n’inclut pas l’accès à l’API), 429 (limite de débit) et 500 — sont répertoriés avec des conseils de nouvelle tentative dans Erreurs et pagination.

Une note sur l’explorateur. Les points de terminaison /agents figurent dans la spécification OpenAPI publiée, vous pouvez donc parcourir leurs champs exacts et exécuter des requêtes en direct dans la Référence de l’API. Les points de terminaison /mcp-servers au niveau du compte figurent également dans la spécification, vous pouvez donc les y explorer aussi.

Connexe #

• Agents IA — ce qu’est un agent, en langage simple.
• Points d’entrée — comment les conversations sont acheminées vers un agent.
• API FAQ — créez et liez les connaissances auxquelles votre agent répond.
• API Canaux — connectez les canaux sur lesquels un agent répond.
• Connecter des serveurs MCP à votre bot · Fonctions personnalisées
• Référence de l’API — l’explorateur complet et interactif des points de terminaison.