Aperçu de l'API

Bienvenue dans la documentation de l'API Minds. Notre API vous permet de créer et gérer des AI minds de manière programmatique, d'uploader des connaissances et d'interagir avec eux.

Démarrage

L'API Minds est organisée autour des principes REST. Notre API possède des URLs prévisibles orientées ressources, accepte des corps de requête encodés en JSON, renvoie des réponses encodées en JSON, et utilise les codes de réponse HTTP standards, l'authentification et les verbes HTTP classiques.

URL de base

Production : https://getminds.ai/api/v1 ou https://api.getminds.ai/v1

Développement local : http://localhost:3000/api/v1

Les deux URLs de base en production sont totalement équivalentes. Le sous-domaine api.getminds.ai est recommandé pour des URLs d'intégration plus propres.

Authentification

Tous les endpoints de l'API nécessitent une authentification via une API key. Vous pouvez générer et gérer vos API keys via Settings → API Keys.

Incluez votre API key dans l'en-tête Authorization :

Authorization: Bearer minds_your_api_key_here

Spécification OpenAPI

Une spécification OpenAPI 3.1.0 lisible par machine est publiée sur /_openapi.json. Utilisez la spécification pour générer des clients typés (TypeScript, Python, etc.) ou pour l'injecter dans un LLM afin d'obtenir du code d'intégration en une fois. Voir OpenAPI pour des exemples.

Content Type

Toutes les requêtes qui envoient des données doivent inclure l'en-tête Content-Type :

Content-Type: application/json

Pour les uploads de fichiers, utilisez :

Content-Type: multipart/form-data

Endpoints disponibles

Minds

Créez et gérez des AI minds (agents) avec des configurations personnalisées.

• GET /api/v1/minds - Lister tous les Minds
• GET /api/v1/minds/{mindId} - Obtenir les détails d'un Mind
• POST /api/v1/minds - Créer un nouveau Mind
• PUT /api/v1/minds/{mindId} - Mettre à jour un Mind
• DELETE /api/v1/minds/{mindId} - Supprimer un Mind
• POST /api/v1/minds/{mindId}/regenerate-prompt - Régénérer le system prompt à partir des connaissances

Knowledge

Gérez les connaissances de vos minds.

• GET /api/v1/minds/{mindId}/knowledge - Lister les éléments de connaissance
• POST /api/v1/minds/{mindId}/knowledge - Ajouter des connaissances (liens, fichiers ou recherche par mots-clés)
• PUT /api/v1/minds/{mindId}/knowledge/{itemId} - Mettre à jour un élément de connaissance
• DELETE /api/v1/minds/{mindId}/knowledge/{itemId} - Supprimer un élément de connaissance
• POST /api/v1/minds/{mindId}/knowledge/enrich - Enrichir via recherche par mots-clés (alias pratique)
• GET /api/v1/minds/{mindId}/knowledge/patterns - Obtenir les patterns de connaissance par framework

Chat

Interagissez avec vos minds via des chat completions.

• POST /api/v1/minds/{mindId}/completion - Envoyer des messages et recevoir des réponses

Studies

Créez et gérez des AI studies pour interroger des audiencees de minds.

• GET /api/v1/studies - Lister tous les studies
• POST /api/v1/studies - Créer un nouveau study
• GET /api/v1/studies/{studyId} - Obtenir les détails d'un study avec l'historique des messages
• POST /api/v1/studies/{studyId}/ask - Poser une question à tous les minds du study (flux SSE)
• POST /api/v1/studies/{studyId}/export - Exporter les résultats du study sous forme de rapport
• GET /api/v1/studies/{studyId}/export-status - Vérifier le statut du job d'export
• GET /api/v1/studies/{studyId}/export-download - Télécharger le PDF exporté

User

Endpoints liés à l'utilisateur.

• GET /api/v1/auth/me - Obtenir l'utilisateur actuellement authentifié
• GET /api/v1/user/shareable-sparks - Lister les minds disponibles au partage

API Keys

Gérez vos API keys pour l'authentification.

• GET /api/v1/api-keys - Lister vos API keys
• POST /api/v1/api-keys - Créer une nouvelle API key
• DELETE /api/v1/api-keys/{keyId} - Supprimer une API key

Exemple rapide

Voici un exemple rapide de création d'un mind puis d'une conversation avec lui :

# 1. Créer un mind (mode keywords)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Expert in digital marketing strategies",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["SEO", "content marketing", "social media", "analytics"]
  }'

# Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } }

# 2. Créer un mind à partir d'un profil social (mode clone)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Clone",
    "description": "AI trained on influencer social presence",
    "mode": "clone",
    "type": "creative",
    "discipline": "Social Media Marketing",
    "personaContext": "https://twitter.com/username"
  }'

# 3. Discuter avec le mind
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top social media trends for 2025?"
      }
    ]
  }'

Étapes suivantes

• Découvrez l'Authentification
• Explorez les endpoints Minds
• Lisez la gestion des connaissances
• Comprenez les Chat completions
• Créez des Studies pour des enquêtes multi-minds
• Consultez Latency & Performance
• Connectez-vous via l'intégration MCP
• Consultez Errors & Limits

Limites selon l'offre

L'accès à l'API et à MCP est disponible avec les offres payantes prises en charge. Gérez les réponses structurées plan_limited et 429 au lieu de coder les limites en dur dans votre intégration. L'offre Starter apparaît comme "premium" dans les payloads API.

Les valeurs publiques par défaut ci-dessous sont générées à partir du même contrat de limites et d'accès aux fonctionnalités que le produit. Les ajustements propres au compte ou au contrat Enterprise affichés dans le produit prévalent.

Voir les offres

Besoin d'aide ?

Si vous avez des questions ou besoin d'aide avec l'API :

• Consultez notre Guide
• Contactez-nous via le formulaire de feedback
• Rejoignez nos discussions communautaires

Workflows n8n

Utilisez le nœud communautaire Minds pour n8n pour créer des Études, prévisualiser des plans de recherche, récupérer des Études et des résumés enregistrés, ou exposer une opération à un Agent IA. Installez n8n-nodes-minds sur n8n auto-hébergé et connectez une clé API Minds. Le package est publié sur npm ; la vérification n8n est en cours d'examen, il n'est donc pas encore disponible sur n8n Cloud. Examinez et démarrez la recherche séparément dans Minds.

Facturation Stripe pour les agents

Utilisez le catalogue de facturation authentifié avant de proposer un achat de crédits de réponse. Les nouveaux clients utilisent le paiement à l'usage ; les nouveaux abonnements et essais Starter sont retirés. La gestion des abonnements existants reste dans les paramètres de facturation Minds. Demandez à l'acheteur d'approuver le pack de réponses sélectionné et le montant final du paiement Stripe.

Pour un nouvel espace de travail en paiement à l'usage, indiquez le pays de facturation de l'acheteur lors de la lecture du catalogue et du lancement du paiement afin que les prix proviennent du bon compte Stripe. Les nombres de réponses restent l'unité d'achat ; chaque pack a le même prix unitaire. Relisez le catalogue si le pays change.

Lancez le paiement avec une clé Idempotency-Key stable de 1 à 128 lettres, chiffres, tirets bas ou traits d'union. Conservez la même clé et le même corps après un délai d'expiration ; toute modification de l'achat sous cette clé est rejetée. Renvoyez data.url textuellement à l'acheteur. Une URL de paiement ne prouve pas le paiement : l'exécution Stripe signée met à jour le solde de réponses partagé.

{
  "kind": "response_credits",
  "amountMinor": 10000,
  "priceId": "price_from_customTopUp",
  "billingCountry": "DE"
}

MPP et x402 concernent les factures appartenant au compte, ouvertes en mode send_invoice, en USD ou EUR, avec au moins 50 unités mineures dues. Le prélèvement automatique reste sur la page Stripe de la facture. Le défi indique le solde réel, taxes et remises comprises. MPP exige un profil professionnel sur le compte Stripe propriétaire. x402 exige aussi l’éligibilité crypto et un facilitateur configuré ; il utilise Base USDC pour les factures USD et exige l’extension mppx de liaison à la route, absente de certains clients de portefeuille.

Conservez Authorization: Bearer pour l’identité Minds et envoyez les justificatifs MPP dans Payment-Authorization, ou x402 dans PAYMENT-SIGNATURE. Les clients MPP natifs peuvent utiliser Authorization: Payment avec le bearer Minds dans Minds-Authorization, uniquement sur cette route. N’insérez jamais de justificatifs de paiement dans les arguments MCP visibles du modèle. Réessayez un paiement incertain avec son justificatif original ; un autre ne doit pas créer un second débit. Stripe et le webhook signé déterminent la fourniture du service.

Les offres sont décrites dans /openapi.json ; la réponse 402 chiffre les montants dynamiques. /.well-known/acp.json annonce l’adaptateur sous /api/acp, version 2026-04-17. Créez une session avec un prix Stripe dans line_items, sa currency et capabilities: {} ; placez billingCountry, le nombre de places quantity et legalAcceptance dans metadata. Lecture, mise à jour, finalisation et annulation utilisent /checkout_sessions/{id} et /complete ou /cancel. Les POST exigent une clé d’idempotence. Mise à jour et finalisation acceptent un corps vide : transmettez continue_url si l’acheteur doit agir, et ne confirmez la fin qu’après Stripe.

La découverte UCP est disponible à /.well-known/ucp, version 2026-08-25, avec le checkout REST sous /api/ucp et les mêmes sessions Stripe que MCP et l’API de facturation. Publiez un profil de plateforme compatible et utilisez un client OAuth Minds avec document de métadonnées sur la même origine HTTPS. Une clé API personnelle ne peut pas revendiquer un profil de plateforme arbitraire. Envoyez UCP-Agent: profile="https://your-platform.example/.well-known/ucp" à chaque requête et un Idempotency-Key lors des écritures. Les gestionnaires de paiement sont vides, car l’acheteur paie dans Stripe Checkout.

Abonnements webhook de disponibilité

Utilisez la même clé API ou connexion OAuth authentifiée que pour la ressource. GET /api/v1/events renvoie les événements autorisés et leurs schémas exacts. POST /api/v1/events/subscribe crée ou renouvelle un abonnement déterministe ; POST /api/v1/events/unsubscribe l’arrête avec l’événement, les arguments et l’URL d’origine sans annuler la recherche. Une Audience exige operationId ; une Étude studyId et runId. Les méthodes MCP sont events/list, events/subscribe et events/unsubscribe, découvertes par server/discover avec le protocole 2026-07-28.

{
  "name": "study.run.finished",
  "arguments": {
    "studyId": "163bcb31-6ca7-4fef-91bd-9b963a9dd39f",
    "runId": "663bcb31-6ca7-4fef-91bd-9b963a9dd39f"
  },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example/mcp-events",
    "secret": "whsec_<base64-encoded-signing-key>"
  },
  "cursor": null
}

Le rappel HTTPS doit renvoyer le défi de la requête de vérification signée. Les en-têtes Standard Webhooks sont webhook-id, webhook-timestamp, webhook-signature et X-MCP-Subscription-Id. La clé whsec_ doit représenter 24–64 octets. Adresses privées, redirections et identifiants dans l’URL sont refusés. Un échec renvoie MCP -32015 avec un motif et n’active rien. HTTP 2xx confirme réception ; les erreurs transitoires entraînent des tentatives limitées à délai exponentiel et ID stable ; 410 et 413 arrêtent la livraison. Dédupliquez les ID avant toute action.

La réponse contient id, refreshBefore, cursor:null et truncated:false. ttlMs peut demander moins ; absent ou null accorde la durée finie par défaut, plafonnée à 86400000 ms. Les mêmes principal, rappel, événement et arguments renouvellent le même ID. La rotation signe brièvement avec les deux clés. Expiration ou révocation arrête la livraison. Les données n’incluent ni jeton Bearer ni réponses de recherche.

Recharges de réponses personnalisées

Saisissez un budget dans la devise de facturation et consultez le nombre entier de réponses et le montant exact avant de payer, au même tarif et minimum que le plus petit pack. Les réponses achetées alimentent le solde existant et peuvent être sélectionnées pour les recharges automatiques expressément autorisées.

responseCredits.customTopUp.priceId → priceId; amountMinor = EUR/USD × 100.

Contrôles de recharge automatique

Le catalogue indique prepaid pour l’espace par défaut avant même le premier paiement. L’usage inclus est nul ; une commande payée crédite les unités achetées. La résiliation se confirme dans les paramètres de facturation et prend effet à la fin de la période payée.

Consultez le catalogue de facturation actuel avant de demander une recharge automatique. Utilisez kind: auto_recharge et le prix de base de responseCredits.customTopUp ; transmettez budget, seuil et plafond mensuel en unités monétaires mineures entières. Envoyez Idempotency-Key pour retrouver la même session lors des nouvelles tentatives. La réponse contient une URL de configuration Stripe : le responsable de facturation doit terminer cette session pour activer les prélèvements. Un changement de devise peut provoquer un conflit si un paiement automatique reste réservé.

{
  "kind": "auto_recharge",
  "priceId": "price_from_customTopUp",
  "amountMinor": 10000,
  "thresholdAmountMinor": 500,
  "monthlyAmountLimit": 19992
}

responseCredits.customTopUp.priceId → priceId; amountMinor, thresholdAmountMinor, monthlyAmountLimit = EUR/USD × 100; monthlyAmountLimit: "none".

POST /api/v1/billing/checkout + Idempotency-Key / start_billing_checkout + idempotencyKey → Stripe Checkout mode=setup.