Référence API

L'API publique Humind vous permet de pousser votre catalogue dans Humind depuis n'importe quelle stack. Authentification par clé API unique par environnement, JSON sur HTTPS, JSON en retour. Aucun SDK à installer, pas de Shopify requis. Des webhooks optionnels pushent les notifications jusqu'à vous au lieu de poller.

C'est la voie d'intégration si vous n'êtes pas sur Shopify. Si vous y êtes, installez plutôt l'app Humind sur le Shopify App Store : tout se synchronise automatiquement et vous pouvez ignorer cette section.

Ce que vous pouvez faire

• Products : créer, mettre à jour, lister, archiver vos produits et leurs variants. Voir Products.
• Groupes de produits : relier les produits d'une même famille grâce à des axes d'options stables. Voir Groupes de produits.
• Collections : regrouper des produits en collections pour que l'assistant affine ses recommandations. Voir Collections.
• Knowledge : pousser FAQ, guides de tailles, politiques de retour et autre contenu free-form sur lequel l'assistant peut s'appuyer. Voir Knowledge.
• Translations : patcher titres, descriptions et handles par langue, une locale à la fois, comme sub-resource sur les produits, collections et entrées knowledge. Voir Products / Translations, Collections / Translations, Knowledge / Translations.
• Variants : gérer un seul variant produit sans renvoyer le produit complet. Voir Products / Variants.
• Imports : uploads NDJSON bulk pour le sync initial de gros catalogues. Voir Imports.
• Webhooks : s'abonner aux events imports (import.completed, import.failed). Voir Webhooks.
• Conversations : exporter les transcriptions de conversations, les tags et les événements d'interaction (ajout au panier, clics) pour l'analytics ou votre data warehouse. Voir Conversations.
• Settings : lire et mettre à jour les settings marchand de votre boutique (widget, comportement IA, modération, et plus). Voir Settings.
• Analytics : récupérer les KPIs et les top questions groupées, les mêmes chiffres que votre dashboard. Voir Analytics.
• Serveur MCP : connecter Claude ou tout agent IA compatible MCP directement à votre boutique. Voir Serveur MCP.

Base URL

https://api.thehumind.com/public/v1

Tous les endpoints sont versionnés sous /public/v1. Les breaking changes sortent sous un nouveau préfixe (/public/v2) et la version précédente reste vivante pendant la fenêtre de migration. Voir Versioning.

Quick start

Vous avez déjà une clé ? Poussez votre premier produit :

curl -X POST https://api.thehumind.com/public/v1/products \
  -H "Authorization: Bearer hmd_live_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "SKU-123",
    "title": "Crème hydratante",
    "handle": "creme-hydratante",
    "status": "active",
    "default_language": "fr",
    "variants": [
      { "external_id": "SKU-123-50ML", "title": "50 ml", "price": 29.90, "currency": "EUR" }
    ]
  }'

Vous récupérez 201 Created pour les nouveaux produits, 200 OK quand vous mettez à jour un existant (matché par external_id). La réponse contient l'objet produit complet, incluant le humind_id qu'Humind a assigné.

Sandbox : utilisez une clé API hmd_test_* depuis votre dashboard pour développer sur des données de test sans toucher à votre catalogue live. Voir Authentication.

Pas encore de clé ? Voir Authentication pour en générer une depuis votre dashboard.

Spécification OpenAPI

La spec complète machine-readable est téléchargeable ici :

• openapi.yaml

Importez-la dans Postman, Insomnia, Bruno ou n'importe quel client OpenAPI 3.0 pour obtenir une collection pré-construite de tous les endpoints avec exemples de payloads.

Vue d'ensemble des routes

Tous les paths sont relatifs à https://api.thehumind.com/public/v1. Chaque requête d'écriture nécessite un header Idempotency-Key. Voir les pages par ressource pour les schémas complets, les exemples et les tables d'erreurs.

Ressource	Méthode	Path	Scope	Rôle
Products	POST	/products	catalog:write	Créer ou upserter un produit
Products	POST	/products/batch	catalog:write	Upserter jusqu'à 500 produits
Products	GET	/products	catalog:read	Lister les produits
Products	GET	/products/{id}	catalog:read	Récupérer un produit
Products	PUT	/products/{id}	catalog:write	Remplacer un produit
Products	PATCH	/products/{id}	catalog:write	Mettre à jour partiellement un produit
Products	DELETE	/products/{id}	catalog:write	Archiver ou hard-delete un produit
Products	PUT	/products/{id}/variants/{external_id}	catalog:write	Upserter un variant
Products	DELETE	/products/{id}/variants/{external_id}	catalog:write	Supprimer un variant
Products	PUT	/products/{id}/translations/{lang}	catalog:write	Upserter une traduction
Products	DELETE	/products/{id}/translations/{lang}	catalog:write	Supprimer une traduction
Groupes de produits	POST	/product-groups	catalog:write	Créer ou upserter un groupe de produits
Groupes de produits	POST	/product-groups/batch	catalog:write	Upserter jusqu'à 500 groupes
Groupes de produits	GET	/product-groups	catalog:read	Lister les groupes
Groupes de produits	GET	/product-groups/{id}	catalog:read	Récupérer un groupe
Groupes de produits	PUT	/product-groups/{id}	catalog:write	Remplacer un groupe
Groupes de produits	PATCH	/product-groups/{id}	catalog:write	Mettre à jour partiellement un groupe
Groupes de produits	DELETE	/product-groups/{id}	catalog:write	Supprimer un groupe et ses appartenances
Collections	POST	/collections	catalog:write	Créer ou upserter une collection
Collections	POST	/collections/batch	catalog:write	Upserter jusqu'à 500 collections
Collections	GET	/collections	catalog:read	Lister les collections
Collections	GET	/collections/{id}	catalog:read	Récupérer une collection
Collections	PUT	/collections/{id}	catalog:write	Remplacer une collection
Collections	PATCH	/collections/{id}	catalog:write	Mettre à jour partiellement une collection
Collections	DELETE	/collections/{id}	catalog:write	Archiver ou hard-delete une collection
Collections	PUT	/collections/{id}/translations/{lang}	catalog:write	Upserter une traduction
Collections	DELETE	/collections/{id}/translations/{lang}	catalog:write	Supprimer une traduction
Knowledge	POST	/knowledge	knowledge:write	Créer ou upserter une entrée knowledge
Knowledge	POST	/knowledge/batch	knowledge:write	Upserter jusqu'à 500 entrées
Knowledge	GET	/knowledge	knowledge:read	Lister les entrées knowledge
Knowledge	GET	/knowledge/{id}	knowledge:read	Récupérer une entrée
Knowledge	PUT	/knowledge/{id}	knowledge:write	Remplacer une entrée
Knowledge	PATCH	/knowledge/{id}	knowledge:write	Mettre à jour partiellement une entrée
Knowledge	DELETE	/knowledge/{id}	knowledge:write	Archiver ou hard-delete une entrée
Knowledge	PUT	/knowledge/{id}/translations/{lang}	knowledge:write	Upserter une traduction
Knowledge	DELETE	/knowledge/{id}/translations/{lang}	knowledge:write	Supprimer une traduction
Knowledge	POST	/knowledge/{id}/file-upload-url	knowledge:write	Générer une URL SAS pour upload
Knowledge	POST	/knowledge/{id}/file-upload-completed	knowledge:write	Finaliser l'upload d'un fichier
Imports	POST	/imports	imports:write	Créer un import + récupérer l'URL d'upload
Imports	GET	/imports/{sync_id}	imports:write	Poller le status d'un import
Imports	POST	/imports/{sync_id}/start	imports:write	Démarrer le traitement d'un import uploadé
Imports	POST	/imports/{sync_id}/cancel	imports:write	Annuler un import pending ou en cours
Webhooks	POST	/webhooks/endpoints	webhooks:manage	Enregistrer un endpoint
Webhooks	GET	/webhooks/endpoints	webhooks:manage	Lister les endpoints
Webhooks	GET	/webhooks/endpoints/{id}	webhooks:manage	Récupérer un endpoint
Webhooks	PATCH	/webhooks/endpoints/{id}	webhooks:manage	Mettre à jour un endpoint
Webhooks	DELETE	/webhooks/endpoints/{id}	webhooks:manage	Supprimer un endpoint
Webhooks	POST	/webhooks/endpoints/{id}/rotate-secret	webhooks:manage	Faire tourner le secret de signature
Webhooks	GET	/webhooks/deliveries	webhooks:manage	Lister les deliveries récentes
Webhooks	GET	/webhooks/deliveries/{id}	webhooks:manage	Inspecter une delivery
Conversations	GET	/conversations	conversations:read	Lister les conversations
Conversations	GET	/conversations/{id}	conversations:read	Récupérer une conversation
Settings	GET	/settings	settings:read	Lire tous les settings
Settings	GET	/settings/schema	settings:read	Lire le schéma des settings
Settings	PATCH	/settings	settings:write	Mettre à jour un ou plusieurs settings
Analytics	GET	/analytics/kpis	analytics:read	Récupérer les KPIs
Analytics	GET	/analytics/top-questions	analytics:read	Récupérer les top questions groupées

SDKs

Aucun aujourd'hui. L'API est conçue pour être suffisamment plate pour que n'importe quel client HTTP fonctionne :

• cURL pour les one-shots et scripts shell
• fetch dans Node, navigateurs, Deno, Bun
• requests en Python
• http.Client en Go
• N'importe quel autre client JSON-over-HTTPS

Si vous aimeriez un SDK typé dans votre langage préféré, contactez le support. Dites-nous quel langage compte le plus pour vous.

Statut & changelog

• Statut du service : thehumind.com/status
• Les changements de l'API publique sont consignés dans le changelog.

Pour aller plus loin

• Authentication : générer, utiliser et faire tourner les clés.
• Conventions : format des requêtes, identifiants, idempotency, versioning.
• Errors : format d'erreur, codes HTTP, codes d'erreur Humind.
• Rate limits : limites par clé actuelles, la réponse 429, backoff.
• Products : pousser votre catalogue.
• Groupes de produits : relier les alternatives d'une même famille produit.
• Collections : grouper les produits pour des recommandations plus fines.
• Knowledge : pousser le contenu sur lequel l'assistant ancre ses réponses.
• Imports : ingestion NDJSON async pour gros catalogues.
• Webhooks : recevez des deliveries signées d'events au lieu de poller.
• Conversations : exportez les transcriptions de conversations et les événements d'interaction.
• Settings : lisez et mettez à jour la configuration de votre boutique.
• Analytics : récupérez les KPIs et les top questions groupées.
• Serveur MCP : connectez un agent IA directement à votre boutique.