API Knowledge

Ajoutez des connaissances à vos minds via trois méthodes : Fichier, Mot-clé ou Lien. Les connaissances sont traitées, embarquées et récupérées automatiquement pendant les conversations.

Remarque : Les opérations de liste, d'ajout et de suppression sont disponibles via l'API v1. L'enrichissement de connaissances via recherche par mots-clés est également pris en charge via le même endpoint d'ajout.

Les réponses de liste et de statut Knowledge sont privées (Cache-Control: private, no-store). GET /api/v1/minds/{mindId}/knowledge/{itemId}/status renvoie les identifiants de référence mindId et itemId, les champs publics de traitement, les nombres d’embeddings et de patterns, ainsi que readyForRetrieval. Les diagnostics du worker et les métadonnées arbitraires sont omis ; un échec utilise le message générique Knowledge processing failed. Un état enregistré incorrect devient unknown. Pour les anciens éléments sans métadonnées de traitement, des embeddings existants impliquent completed, sinon unknown. Des identifiants absents ou bloqués donnent 401, des Minds ou éléments inaccessibles 404, et une erreur de stockage inattendue un 500 générique.

Lister les éléments de connaissance

Récupère une page des éléments de connaissance d’un Mind.

Utilisez limit (1–100, 100 par défaut) et offset (entier positif ou nul, 0 par défaut). Les éléments sont triés par createdAt décroissant, puis par ID décroissant. data.total compte tous les éléments ; data.pagination contient limit, offset et hasMore. Tant que hasMore est vrai, demandez la page suivante avec offset + items.length. Les pages ne constituent pas un instantané : des ajouts ou suppressions entre les requêtes peuvent décaler les résultats. Des valeurs de pagination invalides ou répétées renvoient 400.

Endpoint : GET /api/v1/minds/{mindId}/knowledge

En-têtes :

Authorization: Bearer minds_your_api_key

Exemple :

curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge?limit=100&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Réponse :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "description": "Company Employee Handbook 2025",
        "link": null,
        "filePath": "portfolio/user-id/1234567890_handbook.pdf",
        "isWatched": false,
        "createdAt": "2025-12-10T12:00:00.000Z",
        "updatedAt": "2025-12-10T12:00:00.000Z"
      }
    ],
    "total": 1,
    "pagination": { "limit": 100, "offset": 0, "hasMore": false }
  }
}

Téléversement de fichiers

Téléversez des documents ou des images directement vers un mind.

Endpoint : POST /api/v1/minds/{mindId}/knowledge

Content-Type : multipart/form-data

Formats pris en charge :

• Documents : PDF, DOCX, DOC, TXT, MD, RTF, CSV, JSON, XML
• Images : JPG, JPEG, PNG, GIF, WEBP

Exemple :

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"

L’accès à un fichier de l’espace de travail est indépendant du droit de modifier le Mind : utilisez votre propre fichier, une URL de fichier de chat avec une signature valide ou un fichier de contexte partagé via la Study de la personne qui l’a importé. Sinon, la requête renvoie 403 Upload access denied. Connaître le chemin de l’objet ne donne aucun droit d’accès.

Réponse : 201 Created

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Company Employee Handbook 2025",
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}

Recherche par mots-clés

Ajoutez des connaissances en recherchant des mots-clés sur le web. Interroge Exa et YouTube, extrait le contenu et l'ajoute à la base de connaissances du mind.

Endpoint : POST /api/v1/minds/{mindId}/knowledge

Content-Type : application/json

Envoyez un corps JSON avec un tableau keywords (au lieu de link/file) pour déclencher l'enrichissement par recherche web.

Exemple :

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'

Réponse : 202 Accepted

{
  "success": true,
  "data": {
    "sparkId": "660e8400-e29b-41d4-a716-446655440000",
    "keywords": ["solar panel efficiency", "photovoltaic trends"],
    "queued": true,
    "regeneratePrompt": true,
    "message": "Knowledge enrichment queued with 2 keyword(s)."
  }
}

Remarque : Opération asynchrone. Le traitement s'exécute en arrière-plan et peut prendre plusieurs minutes.

Lien

Ajoutez des connaissances depuis une URL. Prend en charge les pages web, les vidéos YouTube et les articles de recherche.

Endpoint : POST /api/v1/minds/{mindId}/knowledge

Content-Type : application/json

Exemple :

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://example.com/article", "description": "Industry trends article"}'

Réponse : 201 Created

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "link": "https://example.com/article",
    "description": "Industry trends article",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}

Types de liens pris en charge :

• Pages web (contenu extrait via scraping)
• Vidéos YouTube (transcriptions extraites automatiquement)
• Articles de recherche (arxiv, etc.)

Watch (mise à jour automatique)

Les éléments de connaissance de type lien peuvent être « watched » pour vérifier automatiquement les mises à jour de contenu sur un cycle hebdomadaire. Lorsque des changements sont détectés, les connaissances sont retraitées et re-embarquées.

Le Watch est géré via l'interface produit. Le statut Watch est visible lorsque vous listez les éléments de connaissance via l'API (champ isWatched).

Remarque : Le Watch n'est disponible que pour les connaissances de type lien, pas pour les fichiers ni les recherches par mots-clés.

Mettre à jour un élément de connaissance

Met à jour la description d'un élément de connaissance existant.

Endpoint : PUT /api/v1/minds/{mindId}/knowledge/{itemId}

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête :

{
  "description": "Updated description for this knowledge item"
}

Exemple :

curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated handbook description"}'

Réponse :

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Updated handbook description",
    "link": null,
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "isWatched": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T08:30:00.000Z"
  }
}

Réponses d'erreur

400 Bad Request — Aucun champ valide à mettre à jour ou description vide

401 Unauthorized — Clé API invalide ou manquante

404 Not Found — Élément de connaissance ou mind non trouvé

Enrichir via des mots-clés (convenance)

Alias pratique pour l'enrichissement de connaissances par mots-clés.

Endpoint : POST /api/v1/minds/{mindId}/knowledge/enrich

Équivaut à POST /api/v1/minds/{mindId}/knowledge avec un corps keywords. Voir Recherche par mots-clés pour tous les détails.

Exemple :

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge/enrich" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'

Supprimer un élément de connaissance

Supprime définitivement un élément de connaissance et toutes les données associées (embeddings, patterns, fichiers).

Endpoint : DELETE /api/v1/minds/{mindId}/knowledge/{itemId}

En-têtes :

Authorization: Bearer minds_your_api_key

Exemple :

curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key"

Réponse : 204 No Content (corps vide en cas de succès)

Ce qui est supprimé

• L'enregistrement de l'élément de connaissance
• Tous les embeddings vectoriels associés
• Tous les patterns associés
• Le fichier téléversé depuis le stockage (si basé sur un fichier)

Avertissement : Cette action est irréversible.

Fonctionnement du traitement

1. Upload — Le contenu est stocké et l'API renvoie un succès
2. Extraction — Un traitement en arrière-plan extrait le texte (scraping, transcriptions, OCR, vision)
3. Embedding — Le contenu est converti en embeddings vectoriels
4. Retrieval — Pendant le chat, les connaissances pertinentes sont récupérées automatiquement par recherche sémantique

Erreurs

Étapes suivantes

• Converser avec votre mind
• Créer des minds
• Erreurs et limites de l'API