Sources et entraînement API v2

Répertoriez et créez des sources d’agent, envoyez des fichiers directement vers le stockage, supprimez des documents, consultez l’état de l’entraînement et démarrez le réentraînement des sources web.

Utilisez ces points de terminaison pour gérer les sources de texte, de Q&R, d’URL et de fichier, et pour réentraîner les sources web indexées. Chaque point de terminaison de cette page nécessite Authorization: Bearer YOUR_API_KEY et un accès à {agentId}.

Consultez le catalogue des erreurs pour connaître les erreurs d’authentification, de validation, de quota et de ressource communes.

Objet Source

Champ	Type	Remarques
`id`	chaîne	ID du document.
`title`	chaîne	Titre de la source.
`sourceType`	chaîne	Type de source stocké, notamment `web_crawl`, `file_upload`, `text_snippet`, ou `qna_entry`.
`createdAt`	entier ou null	Horodatage Unix en secondes.
`lastCrawledAt`	entier ou null	Horodatage Unix en secondes.
`sourceMetadata`	toute valeur JSON	Métadonnées de source stockées.

Lister les sources

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

GET /api/v2/agents/{agentId}/sources

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

Paramètre	Obligatoire	Contraintes
`limit`	Non	Entier de 1 à 100 ; 20 par défaut.
`cursor`	Non	Curseur opaque renvoyé par la page précédente. Réutilisez-le tel quel.
`sourceType`	Non	`web_crawl`, `file_upload`, `text_snippet`, ou `qna_entry`.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources?sourceType=text_snippet&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succès : 200 OK

{
  "data": [
    {
      "id": "41b4c1d3-887d-46a5-95ae-c761922c6bc7",
      "title": "Refund policy",
      "sourceType": "text_snippet",
      "createdAt": 1784332800,
      "lastCrawledAt": null,
      "sourceMetadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Une limite, un curseur, ou un type de source invalide renvoient 400 VALIDATION_INVALID_BODY.

Ajouter une source de texte

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

POST /api/v2/agents/{agentId}/sources/text

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

Champ du corps	Obligatoire	Type et contraintes
`title`	Oui	Chaîne de 1 à 200 caractères avant suppression des espaces superflus ; la valeur acceptée est nettoyée de ces espaces.
`content`	Oui	Chaîne non vide, d’au plus 262 144 octets UTF-8 (256 Ko), et ne comportant pas uniquement des espaces.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Refund policy","content":"Refunds are available within 30 days."}'

Succès : 201 Created

{
  "documentId": "41b4c1d3-887d-46a5-95ae-c761922c6bc7"
}

Une entrée invalide ou un échec de traitement non lié au stockage renvoie 400 VALIDATION_INVALID_BODY. Un échec de traitement dû à une limite de stockage renvoie 403 QUOTA_STORAGE_LIMIT.

Ajouter une source Q&R

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

POST /api/v2/agents/{agentId}/sources/qna

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

Champ du corps	Obligatoire	Type et contraintes
`title`	Oui	Chaîne de 1 à 200 caractères avant suppression des espaces superflus ; la valeur acceptée est nettoyée de ces espaces.
`questions`	Oui	Tableau d’au plus 10 chaînes, chacune d’au plus 500 caractères. Au moins une entrée doit contenir un caractère autre qu’un espace.
`answer`	Oui	Chaîne non vide, d’au plus 262 144 octets UTF-8 (256 Ko), et ne comportant pas uniquement des espaces.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/qna' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Shipping time","questions":["How long does shipping take?","When will my order arrive?"],"answer":"Standard shipping takes 3–5 business days."}'

Succès : 201 Created

{
  "documentId": "531a3fbe-40c2-4d22-a524-1f4a70f509f1"
}

Une entrée invalide ou un échec de traitement non lié au stockage renvoie 400 VALIDATION_INVALID_BODY. Un échec de traitement dû à une limite de stockage renvoie 403 QUOTA_STORAGE_LIMIT.

Ajouter ou réentraîner une source URL

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

POST /api/v2/agents/{agentId}/sources/url

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

Champ du corps	Obligatoire	Type et contraintes
`url`	Oui	URL HTTP ou HTTPS non vide, avec un domaine. Un protocole manquant est normalisé en `https://`. Les adresses IP de boucle locale, privées, link-local, unique-local, dans des plages réservées, les variantes de localhost, les TLD internes et les noms d’hôte à un seul label sont rejetés.

Soumettre une URL déjà indexée pour l’agent crée une tâche de réentraînement. Une nouvelle URL vérifie d’abord la capacité de stockage disponible. Les URL vidéo nécessitent en outre un accès au forfait permettant la transcription vidéo.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com/getting-started"}'

Succès : 202 Accepted

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "isRetrain": false
}

Une entrée invalide renvoie 400 VALIDATION_INVALID_BODY. L’absence d’accès à la transcription vidéo renvoie 403 SUBSCRIPTION_API_RESTRICTED_PLAN ; un échec de quota de stockage ou de file d’attente renvoie 403 QUOTA_STORAGE_LIMIT ; un échec de création de tâche non lié à un quota renvoie 500 INTERNAL_SERVER_ERROR.

Ajouter des sources de fichier avec des URL d’envoi signées

Les sources de fichier utilisent un flux API en deux étapes, afin que les octets du fichier transitent directement de votre client vers le stockage privé, sans passer par la route de l’API. Chaque fichier peut peser au plus 50 Mo, et une requête peut contenir au plus 20 fichiers. Les extensions prises en charge sont .pdf, .txt, .md, .docx, .xlsx, et .pptx.

1. Créer des URL d’envoi signées

Chemin : /api/v2/agents/{agentId}/sources/file/upload-url

POST /api/v2/agents/{agentId}/sources/file/upload-url

Envoyez les noms de fichiers d’origine :

{
  "files": [
    { "fileName": "product-guide.pdf" },
    { "fileName": "faq.md" }
  ]
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/file/upload-url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"fileName":"product-guide.pdf"},{"fileName":"faq.md"}]}'

Succès : 200 OK

{
  "files": [
    {
      "fileName": "product-guide.pdf",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    },
    {
      "fileName": "faq.md",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    }
  ]
}

2. Envoyer les octets du fichier

Envoyez chaque fichier directement à son uploadUrl avec PUT :

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
});

Si vous utilisez le client JavaScript Supabase, transmettez le chemin et le jeton correspondants obtenus à l’étape 1 :

await supabase.storage
  .from('training_files')
  .uploadToSignedUrl(storagePath, token, file);

Ne modifiez ni ne construisez vous-même les chemins de stockage. L’enregistrement n’accepte que les chemins renvoyés pour cet agent à l’étape 1.

3. Enregistrer les fichiers envoyés

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

POST /api/v2/agents/{agentId}/sources/file

Une fois chaque envoi direct terminé, enregistrez les chemins renvoyés avec leurs noms de fichiers d’origine :

{
  "files": [
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "fileName": "product-guide.pdf"
    },
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "fileName": "faq.md"
    }
  ]
}

Succès : 202 Accepted

{
  "jobId": 321,
  "fileCount": 2
}

L’enregistrement vérifie que chaque objet existe, n’est pas vide, ne dépasse pas 50 Mo, et appartient à l’agent demandé, avant de démarrer la tâche de traitement. Un envoi invalide ou manquant renvoie 400 VALIDATION_INVALID_BODY ; un refus de quota de stockage renvoie 403 QUOTA_STORAGE_LIMIT ; un échec de stockage ou de file d’attente renvoie 500 INTERNAL_SERVER_ERROR.

Supprimer une source

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

DELETE /api/v2/agents/{agentId}/sources/{documentId}

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

{documentId} doit être un UUID renvoyé par une réponse de création ou de liste de sources.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/41b4c1d3-887d-46a5-95ae-c761922c6bc7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succès : 200 OK

{
  "deleted": true
}

Un UUID invalide renvoie 400 VALIDATION_INVALID_BODY. Un UUID valide qui n’identifie aucun document pour l’agent renvoie 404 RESOURCE_DOCUMENT_NOT_FOUND.

Obtenir l’état de l’entraînement

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

GET /api/v2/agents/{agentId}/train

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

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

Champ	Type	Remarques
`status`	chaîne	`training` lorsqu’une tâche en attente ou en cours existe, sinon `trained` lorsqu’un horodatage de dernier entraînement existe, sinon `idle`.
`documentCount`	entier	Nombre de documents source pour l’agent.
`lastTrainedAt`	entier ou null	Horodatage Unix en secondes.
`activeJob`	objet ou null	Tâche en attente ou en cours la plus récente.
`activeJob.id`	chaîne	ID de la tâche.
`activeJob.status`	chaîne	Statut de tâche stocké.
`activeJob.tasksCount`	entier	Nombre total de sous-tâches.
`activeJob.tasksCompletedCount`	entier	Nombre de sous-tâches terminées.
`activeJob.createdAt`	entier ou null	Horodatage Unix en secondes.

{
  "status": "training",
  "documentCount": 12,
  "lastTrainedAt": 1784246400,
  "activeJob": {
    "id": "c3c61f67-70fe-42da-a843-24112ded8aeb",
    "status": "running",
    "tasksCount": 8,
    "tasksCompletedCount": 3,
    "createdAt": 1784332800
  }
}

Démarrer le réentraînement des sources web

POST /api/v2/agents/{agentId}/train

Authentification : clé API Bearer ayant accès à {agentId}. Ce point de terminaison ne prend aucun corps de requête.

Le point de terminaison réentraîne les URL web indexées, et non les sources de texte, de Q&R, ou de fichier envoyé.

Lorsqu’au moins une URL indexée existe, le succès correspond à 202 Accepted :

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "count": 8,
  "message": "Retraining started for 8 URLs"
}

Lorsqu’aucune URL indexée n’existe, le succès correspond à 200 OK et aucune tâche n’est créée :

{
  "jobId": null,
  "count": 0,
  "message": "No web sources to retrain"
}

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

Sources et entraînement API v2

Répertoriez et créez des sources d’agent, envoyez des fichiers directement vers le stockage, supprimez des documents, consultez l’état de l’entraînement et démarrez le réentraînement des sources web.

Objet Source

Lister les sources

Ajouter une source de texte

Ajouter une source Q&R

Ajouter ou réentraîner une source URL

Ajouter des sources de fichier avec des URL d’envoi signées

1. Créer des URL d’envoi signées

2. Envoyer les octets du fichier

3. Enregistrer les fichiers envoyés

Supprimer une source

Obtenir l’état de l’entraînement

Démarrer le réentraînement des sources web

Référence associée