API Chat

Envoyez des messages à vos minds et recevez des réponses générées par IA. L'API Chat prend en charge à la fois les complétions sans état et les conversations multi-tours avec état, incluant une gestion automatique de l'historique.

Chats avec état (recommandé)

Créez des conversations persistantes où le serveur gère automatiquement l'historique, la compression du contexte et les résumés glissants. Inutile d'envoyer l'historique complet des messages à chaque requête.

Créer un chat

Créez une nouvelle conversation avec état liée à un mind.

Endpoint : POST /api/v1/chats

Choisissez une seule sélection non vide : mindId, mindIds ou audienceIds. Mélanger les sélections renvoie 400 ; un tableau facultatif vide ne remplace pas un Mind unique. La casse des UUID est ignorée, tout comme les doublons. La création accepte au maximum 1 MiB de JSON, échappement compris ; au-delà, elle renvoie 413 avant tout accès à la base ou contrôle des droits du forfait. Les réponses sont privées et non mises en cache.

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête :

{
  "name": "My Conversation",
  "mindId": "your-mind-id"
}

Réponse (201) :

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "minds": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

Envoyer un message

Envoyez un message à un chat existant. Le serveur gère automatiquement l'historique de la conversation, la compression de la fenêtre de contexte et les résumés glissants.

Endpoint : POST /api/v1/chats/{chatId}/messages

Les chats avec un ou plusieurs Minds respectent la politique knowledge_only enregistrée de chaque Mind et les restrictions de recherche web de l’espace de travail. Un Mind restreint utilise la question actuelle, sa persona entraînée et les connaissances pertinentes récupérées pour ce Mind ; les outils internes et client, l’ancien contexte du chat et les sources copiées de Study sont exclus de son contexte de réponse. La réponse indique metadata.knowledgeRetrieval.status à grounded lorsque des éléments pertinents ont été récupérés, ou à fallback s’ils étaient indisponibles ou si la récupération a échoué. Avec plusieurs Minds, ce statut figure séparément dans les metadata de chaque élément de messages[].

L’autorisation de recherche web de l’espace de travail est distincte de knowledge_only : sa désactivation retire les outils de recherche web et d’analyse de liens, tout en conservant les documents fournis et l’historique pour les Minds utilisant auto. Le contexte de réponse restreint décrit ci-dessus concerne les Minds avec knowledge_only.

La mémoire glissante reprend après l’ID du dernier message couvert, plutôt qu’à une position susceptible de changer avec le contexte Study copié. Les lignes de résumé générées sont exclues des tours de conversation ; les notes système du propriétaire restent disponibles dans les chats v1. Un résultat en arrière-plan est écarté si une autre requête a modifié le résumé enregistré sur lequel il reposait.

Si le résumé glissant échoue ou ne renvoie aucun texte narratif, le mécanisme de secours conserve le résumé précédent et les faits enregistrés valides, puis ajoute une courte synthèse du nouveau segment. Le mécanisme de secours conserve des extraits de 30 nouveaux messages au maximum par actualisation et ne progresse que jusqu’à ceux-ci. Les autres restent à traiter lors d’une actualisation ultérieure. La compression utilise le message repère enregistré pour éviter de répéter les extraits déjà couverts, tout en conservant les messages récents, les éléments de preuve prioritaires et le contexte copié de Study.

Le modérateur identifie les participants par leur ID de Mind. Les Minds portant le même nom restent des candidats distincts ; les limites de tours et la prévention des interventions consécutives sont appliquées par ID. Le modérateur peut terminer la discussion avant que chaque Mind ait répondu.

Un échec inattendu de génération renvoie un 500 générique sans détails du fournisseur ; les réponses échouées déclenchent une demande de remboursement des unités réservées. Les réponses déjà générées et les messages enregistrés ne sont pas annulés. Un refus explicite lié aux capacités du modèle reste un 400 avec data.errorType: "unsupported_model_capability". Pour les chats multi-Mind, le résumé facultatif en arrière-plan ne retarde pas une réponse déjà enregistrée et ne la transforme pas en erreur.

Les messages ont aussi une limite JSON de 1 MiB ; un dépassement renvoie 413 avant tout accès à la base ou contrôle des droits du forfait. Les réponses sont privées et non mises en cache. Seul le propriétaire peut écrire. Les workspaces gérés revérifient à chaque requête le workspace actuel et les autorisations des Minds/Audiences associés ; un accès révoqué renvoie 404 avant enregistrement ou facturation.

L’exemple ci-dessous concerne un seul Mind. Les chats multi-Mind renvoient messages[], les chats Study outputData. Avec role: "system", une note de contexte est enregistrée sans génération ni consommation du quota de messages ; la réponse est { messageId, role: "system" }.

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête :

{
  "content": "What are the latest advancements in solar panel technology?"
}

La sélection de modèle pour le chat avec état suit cet ordre : surcharge par requête, puis fournisseur préféré de l'équipe s'il est configuré et éligible, puis valeur par défaut du produit. Sur cet endpoint, les surcharges partielles sont rejetées avec 400 Bad Request; envoyez model et provider ensemble ou omettez les deux.

Réponse :

{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}

Exemple multi-tours

Avec les chats à état, il suffit d'envoyer le nouveau message à chaque fois. Le serveur se souvient de tout :

# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "mindId": "your-mind-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'

Fonctionnement interne :

• Chaque message est persisté en base de données
• Dans les chats avec un seul Mind et un historique long, les 8 messages les plus récents restent en contexte complet
• Les échanges plus anciens utilisent un résumé enregistré lorsqu’il existe, complété par des extraits des messages non encore couverts
• Les résumés perdent des détails ; un historique très long ou des messages volumineux peuvent toujours atteindre les limites de contexte du modèle.

Supprimer un chat

DELETE /api/v1/chats/{chatId}

Seul le propriétaire peut supprimer définitivement un chat et ses messages. Les Minds et Audiences sont conservés. Le succès renvoie 204 sans corps : ne tentez pas de lire du JSON. Des identifiants absents ou invalides renvoient 401, un chat appartenant à autrui 403, et un chat absent 404, y compris s’il a été supprimé ou transféré avant l’écriture finale. Les réponses utilisent Cache-Control: private, no-store.

Complétions sans état

Pour des requêtes unitaires ou lorsque vous souhaitez gérer vous-même l'historique de la conversation.

Envoyer un message

Envoyez des messages à un mind et recevez des réponses.

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

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}

Paramètres

Réponse

{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}

Exemple de message unique

Poser une seule question :

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 3 marketing trends for 2025?"
      }
    ]
  }'

Conversation multi-tours

Maintenez le contexte conversationnel en incluant les messages précédents :

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 marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

Conseils pour les conversations multi-tours :

• Incluez l'historique complet de la conversation dans chaque requête
• L'ordre est important : les messages doivent être chronologiques
• Alternez entre les rôles user et assistant
• Le dernier message doit toujours provenir de user

Pièces jointes

Attachez des fichiers, documents, images et liens pour fournir du contexte à vos minds. Les minds reçoivent le contenu traité dans le cadre de la conversation.

Joindre des fichiers

Ajoutez des fichiers via le tableau metadata.attachedFiles dans votre message utilisateur :

Pour les complétions sans état, utilisez votre propre fichier, une URL de fichier de chat avec une signature valide ou un contexte partagé via la Study de la personne qui l’a importé. Un fichier de l’espace de travail sans autorisation renvoie 403 Upload access denied (un événement d’erreur en streaming). Les URL HTTP(S) externes conservent leur propre jeton d’accès ; un chemin de stockage arbitraire ne reçoit pas de nouvelle signature. Remplacez your-user-id par votre identifiant et utilisez le chemin renvoyé par l’endpoint d’import.

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": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "chat/your-user-id/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

Format de pièce jointe

Chaque objet de pièce jointe prend en charge :

Remarque : Fournissez soit url, soit path, mais pas les deux.

Types de fichiers pris en charge

Documents :

• PDF (.pdf) — Extraction de texte + OCR pour les pages numérisées
• Word (.docx) — Extraction de texte complète
• Texte (.txt, .md) — Contenu textuel direct
• CSV/Excel (.csv, .xlsx) — Extraction de tableaux

Images :

• PNG, JPG, WEBP — OCR + analyse visuelle
• Capacités de vision pour la compréhension d'images

URL externes :

• Pages web récupérées avec Firecrawl (rendu JS + captures d'écran)
• Conversion automatique en markdown

Traitement

Les fichiers sont automatiquement traités avant d'être transmis au mind :

1. Téléchargement — Fichiers récupérés depuis une URL ou depuis le stockage Supabase
2. Extraction — Contenu extrait (texte depuis les PDF, OCR depuis les images, etc.)
3. Injection — Contenu traité ajouté au contexte de la conversation
4. Réponse — Le mind voit à la fois votre message et le contenu du fichier

Limites de traitement :

• Timeout : 30 secondes par fichier
• Traitement des fichiers en parallèle
• Les fichiers en échec affichent des messages de repli explicites

Exemple avec plusieurs fichiers

{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "chat/your-user-id/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

Pièces jointes dans l'historique de conversation

Lorsque vous poursuivez une conversation avec des pièces jointes, incluez le message original avec les pièces jointes dans l'historique :

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}

Remarque : Les fichiers ne sont traités qu'une seule fois lors de la première pièce jointe. Les messages suivants dans la même conversation font référence au contenu déjà traité.

Liens web

Pour les pages web et le contenu externe, utilisez le champ url :

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}

Pour les pages web spécifiquement :

• Les sites riches en JavaScript sont rendus avec Firecrawl
• Des captures d'écran sont prises pour le contexte visuel
• Le contenu est converti en markdown propre

Gestion des erreurs

Si le traitement d'un fichier échoue :

• Le mind reçoit un message de repli indiquant que le fichier était joint mais que le traitement a échoué
• La conversation continue normalement
• Les erreurs de timeout affichent [Processing timeout - file may be too large]
• Les autres erreurs affichent [Processing failed - file uploaded but analysis unavailable]

Cela garantit que les minds sont informés des tentatives de pièces jointes même en cas d'échec du traitement.

Message initial (salutation)

Si vous envoyez un tableau messages vide ou aucun message, le mind se présentera :

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": []
  }'

Réponse :

{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}

Model Override

Vous pouvez éventuellement remplacer le modèle IA utilisé pour une requête de complétion sans état en passant le paramètre model. Cela est utile pour le benchmarking, l'optimisation des coûts ou pour tester différents comportements de modèles. Les endpoints de chat avec état et de panel appliquent une validation plus stricte : envoyez model et provider ensemble.

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 your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-6-luna"
  }'

Lorsqu'aucun model n'est précisé, le modèle par défaut du serveur est utilisé.

Fournisseurs

Passez l'un des modèles listés ci-dessus. Les identifiants retirés sont redirigés (voir ci-dessous) ; tout autre modèle renvoie 400 Bad Request. Le fournisseur est détecté automatiquement à partir des préfixes courants de noms de modèles (claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI).

Your own model

Pour utiliser un modèle fine-tuné ou auto-hébergé, un administrateur de l'équipe l'ajoute comme connexion de modèle d'équipe (protocole OpenAI Chat Completions, OpenAI Responses ou Anthropic Messages) et la vérifie. Envoyez ensuite l'ID de la connexion et sa révision actuelle à la place de model et provider :

{
  "messages": [...],
  "modelConnection": { "id": "3f6c1e2a-5b7d-4c1e-9a0f-2d8e4b6a1c90", "revision": 3 }
}

GET /api/v1/model-connections liste les connexions de votre équipe avec leurs révisions et leurs capacités vérifiées. La connexion doit prendre en charge le texte et le streaming, ainsi que la sortie structurée lorsque vous envoyez response_format et l'appel d'outils lorsque la requête utilise des outils. Si votre endpoint échoue, la requête échoue : Minds ne bascule jamais vers l'un de ses propres modèles. Les images et autres médias sont rejetés avec MODEL_CONNECTION_MEDIA_UNVERIFIED. Les messages de chat avec état (/chats/{chatId}/messages) n'acceptent pas de connexion.

Structured Output

Demandez des réponses JSON garanties conformes à un schéma spécifique à l'aide du paramètre response_format. Cela suit le modèle de sortie structurée de style OpenAI et s'avère utile pour extraire des données structurées depuis les conversations.

Mode JSON Schema

Force le modèle à produire un JSON valide correspondant à votre schéma :

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": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

Réponse :

{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}

Mode JSON Object

Force une sortie JSON sans validation de schéma :

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": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

Types de response format

Champs JSON Schema

Fonctionnalités de schéma prises en charge

Les fonctionnalités JSON Schema suivantes sont prises en charge :

• Types : string, number, integer, boolean, array, object, null
• Contraintes : enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• Structure : properties, required, items, additionalProperties
• Métadonnées : description (utilisée pour guider le modèle)

Notes

• Les outils (RAG, recherche web, etc.) fonctionnent avec la sortie structurée — le mind peut toujours consulter sa base de connaissances avant de générer la réponse structurée
• Le champ parsed contient l'objet JSON analysé pour plus de commodité ; content contient la chaîne JSON brute
• Tous les grands fournisseurs (OpenAI, Anthropic, Google) prennent en charge la sortie structurée
• Pour les schémas complexes, pensez à ajouter des champs description pour guider la sortie du modèle

Tool Calling

Permettez aux minds d'appeler vos fonctions personnalisées pendant les conversations. Ce mécanisme suit le modèle d'appel de fonction compatible OpenAI et vous permet d'étendre les capacités des minds avec des outils et des APIs externes.

Fonctionnement

1. Définir les outils : Passez des définitions d'outils avec noms, descriptions et paramètres au format JSON Schema
2. Le mind décide : Le mind détermine quand appeler vos outils en fonction de la conversation (ou vous le forcez avec tool_choice)
3. L'API renvoie les tool calls : La réponse inclut tool_calls avec le nom de l'outil et les arguments générés
4. Exécuter les outils : Vous exécutez les outils dans votre application et en obtenez les résultats
5. Renvoyer les résultats : Incluez les résultats des outils dans le message suivant avec role: "tool"
6. Le mind répond : Le mind intègre les résultats des outils dans sa réponse finale

Exemple de base

Requête avec outils :

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 is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

Réponse :

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}

Exécutez l'outil et renvoyez les résultats :

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 is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

Réponse finale :

{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}

Schéma de définition d'outil

Chaque outil doit respecter cette structure :

{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}

Champs requis :

Champs optionnels :

Tool Choice Modes

Contrôlez quand et comment le mind appelle les outils via le paramètre tool_choice :

Exemples :

// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

Appels d'outils parallèles

Par défaut, les minds peuvent appeler plusieurs outils en un seul tour pour plus d'efficacité :

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}

Pour désactiver les appels parallèles et forcer une exécution séquentielle :

{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}

Format du message Tool

Lors du renvoi des résultats d'outil, utilisez le rôle tool :

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}

Les résultats d’outils suivent le message correspondant de l’assistant, avec ses tool_calls. Reprenez l’identifiant et le nom de l’appel renvoyés et envoyez chaque résultat une seule fois. Les arguments mal formés, identifiants inconnus, noms d’outils incompatibles résultats en double et résultats client manquants entraînent une réponse 400 avant la génération.

Outils internes vs outils utilisateur

Minds dispose d'outils serveur intégrés qui s'exécutent automatiquement :

Différences clés :

• Outils internes : Exécutés côté serveur, résultats inclus dans content et metadata. Jamais renvoyés dans tool_calls.
• Outils utilisateur : Renvoyés dans tool_calls pour que vous les exécutiez. Les résultats doivent être renvoyés sous forme de messages tool.

Vous ne pouvez ni remplacer ni désactiver les outils internes. Les outils utilisateur sont additifs — ils étendent les capacités du mind.

Exemple complet multi-outils

Un mind assistant juridique avec plusieurs outils personnalisés :

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": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

Réponse avec appels d'outils parallèles :

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}

Bonnes pratiques

1. Rédigez des descriptions claires : Le champ description est crucial. Soyez précis sur quand et pourquoi utiliser chaque outil.

   ❌ "description": "Search database"
   ✅ "description": "Search the legal precedents database for similar cases based on keywords and practice area"
   

2. Utilisez des descriptions de paramètres : Aidez le mind à comprendre ce que fait chaque paramètre.

   "case_id": {
     "type": "string",
     "description": "Unique case identifier in format CASE-YYYY-NNNN"
   }
   

3. Tirez parti des enums pour les valeurs contraintes :

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. Définissez des contraintes de validation :

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "Priority level (1=lowest, 5=highest)"
   }
   

5. Activez le mode strict : Conservez strict: true (par défaut) pour garantir que le mind génère des arguments valides.
6. Retournez des résultats d'outil structurés : Utilisez JSON pour les résultats d'outils afin de faciliter leur analyse :

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
   }
   

7. Gérez les erreurs proprement : Renvoyez les détails d'erreur dans le résultat de l'outil :

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": false, \"error\": \"Case already exists\", \"error_code\": \"DUPLICATE_CASE\"}"
   }
   

Limites

• Maximum 128 outils par requête
• Les noms d'outils doivent être uniques et ne peuvent pas entrer en conflit avec les noms d'outils internes
• L'exécution des outils se fait côté client — vous êtes responsable de l'exécution et de la sécurisation de vos outils
• Les résultats des outils doivent être renvoyés dans l'historique de la conversation pour que le mind puisse répondre

Prise en charge de JSON Schema

Le champ parameters prend en charge les fonctionnalités standard de JSON Schema :

Types :

• string, number, integer, boolean, array, object, null

Validation :

• enum — Restreint à des valeurs spécifiques
• minimum, maximum — Bornes numériques
• minLength, maxLength — Longueur des chaînes
• minItems, maxItems — Taille de tableau
• pattern — Validation par regex
• format — Formats de chaîne (p. ex. "date-time", "email", "uri")

Structure :

• properties — Propriétés d'objet
• required — Champs requis
• items — Schéma des éléments de tableau
• additionalProperties — Autorise/interdit les propriétés supplémentaires

Exemple avec validation avancée :

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}

Fonctionnement

1. Chargement du contexte

Lorsque vous envoyez un message, le mind :

• Charge son system prompt et sa configuration
• Recherche automatiquement dans sa base de connaissances les informations pertinentes
• Prend en compte l'historique de la conversation

2. Traitement

Le mind :

• Analyse votre message dans son contexte
• Fonde les réponses sur les connaissances récupérées avec citations
• Accède à des outils supplémentaires (recherche web, génération d'images, etc.) si nécessaire
• Formule une réponse alignée sur sa personnalité

3. Génération de la réponse

Le mind :

• Génère une réponse qui reflète son expertise
• Inclut des citations lors de l'utilisation de la base de connaissances ou de sources web
• Renvoie le message avec des métadonnées optionnelles (citations, images, etc.)

Métadonnées

Les réponses peuvent inclure des métadonnées supplémentaires :

Images

Lorsqu'un mind génère ou affiche des images :

{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}

Citations de connaissance

Lorsqu'un mind récupère des informations depuis sa base de connaissances ou via la recherche web :

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Mind knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}

Champs de citation :

• id - Identifiant unique de la source
• displaySource - Nom de source lisible ou URL
• similarity - Score de pertinence (0-1) indiquant à quel point la source correspond à la requête

Les minds recherchent automatiquement dans leur base de connaissances avant de répondre et incluent des citations lorsqu'ils ancrent leurs réponses dans des sources spécifiques.

Contrôle d'accès

Vous pouvez converser avec les minds que vous :

• Possédez — Minds que vous avez créés
• Avez accès à — Minds partagés avec vous par des membres de l'équipe
• Êtes membre de — Minds dans des espaces de travail d'équipe auxquels vous appartenez
• Minds publics — Minds accessibles publiquement

Toute tentative d'accès à des minds non autorisés renvoie :

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

Formats de réponse

Réponse texte

La plupart des réponses sont en texte brut :

{
  "content": "Based on current trends, I recommend focusing on..."
}

Réponse structurée

Certains minds peuvent renvoyer du contenu structuré :

{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}

Réponse vide avec métadonnées

Parfois, seules des métadonnées sont renvoyées (p. ex. pour la génération d'images) :

{
  "content": "",
  "metadata": {
    "images": [...]
  }
}

Bonnes pratiques

Soyez précis

❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"

Fournissez du contexte

✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"

Utilisez les relances

Tirez parti de la mémoire conversationnelle :

User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."

Référencez les connaissances

Si vous avez téléversé des connaissances, faites-y référence :

✅ "Based on our brand guidelines, what tone should we use for this campaign?"

Réponses d'erreur

400 Bad Request

ID de Mind manquant ou invalide :

{
  "statusCode": 400,
  "statusMessage": "Mind ID is required"
}

Fournisseur non pris en charge :

{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}

Nom de modèle ambigu sans fournisseur :

{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}

401 Unauthorized

Clé API invalide.

403 Forbidden

Accès refusé au Mind :

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

Le Mind n'existe pas :

{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}

Notes d'utilisation

• L'API v1 applique une limite configurable par compte authentifié (300 requêtes par minute par défaut)
• Lisez RateLimit-Limit et RateLimit-Remaining, puis respectez Retry-After après un 429
• Limitez les completions parallèles, car la génération consomme beaucoup de ressources

Étapes suivantes

• Comprendre la latence et les performances
• En savoir plus sur errors and rate limits
• Créer votre premier mind
• Téléverser des connaissances pour enrichir les réponses
• Lire l'aperçu de l'API