---
title: "API Chat"
description: "Interagissez avec vos minds via des complétions de chat et des conversations multi-tours."
---

# 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 :**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**Corps de la requête :**

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

<table>
<thead>
  <tr>
    <th>
      Paramètre
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Requis
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Nom d'affichage du chat (par défaut : "API Chat")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mindId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Un de ces champs
    </td>
    
    <td>
      UUID d’un Mind. Fournissez <code>
        mindId
      </code>
      
      , un tableau <code>
        mindIds
      </code>
      
       non vide ou un tableau <code>
        audienceIds
      </code>
      
       non vide ; sans ces trois champs, la réponse est <code>
        400
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mindIds
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      Un de ces champs
    </td>
    
    <td>
      UUID de plusieurs Minds.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audienceIds
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      Un de ces champs
    </td>
    
    <td>
      UUID des Audiences pour un chat Study. La réponse contient <code>
        type: "study"
      </code>
      
       et <code>
        audiences
      </code>
      
       au lieu de <code>
        minds
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        responseThread
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Objet facultatif <code>
        { studyId, messageId }
      </code>
      
       pour approfondir une réponse Study avec un Mind. Conserve le contexte et les fichiers sources autorisés. Renvoie <code>
        201
      </code>
      
       pour un nouveau fil ou <code>
        200
      </code>
      
       pour reprendre un fil existant.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Description optionnelle
    </td>
  </tr>
</tbody>
</table>

**Réponse (201) :**

```json
{
  "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 :**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**Corps de la requête :**

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

<table>
<thead>
  <tr>
    <th>
      Paramètre
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Requis
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      Le texte du message (vous pouvez également utiliser <code>
        message
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Remplace le modèle IA pour ce message. Doit être envoyé avec <code>
        provider
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Fournisseur IA pour la surcharge de modèle : <code>
        openai
      </code>
      
      , <code>
        anthropic
      </code>
      
       ou <code>
        google
      </code>
      
      . Doit être envoyé avec <code>
        model
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Nom d'affichage optionnel du véritable utilisateur final pour cette requête. S'il est omis, <code>
        null
      </code>
      
       ou vide, Minds s'adresse à l'utilisateur de façon neutre et n'infère aucun nom depuis le propriétaire de la clé API ou du compte. Alias : <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

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 :**

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

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      La réponse du mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Identifiant unique du message enregistré
    </td>
  </tr>
</tbody>
</table>

### Exemple multi-tours

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

```bash
# 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 :**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Corps de la requête

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

### Paramètres

<table>
<thead>
  <tr>
    <th>
      Paramètre
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Requis
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messages
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Tableau d'objets message (<code>
        system
      </code>
      
      , <code>
        user
      </code>
      
      , <code>
        assistant
      </code>
      
       ou <code>
        tool
      </code>
      
      ). S'il est omis ou vide, le mind renvoie un message d'accueil adapté à son persona.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      <code>
        system
      </code>
      
      , <code>
        user
      </code>
      
      , <code>
        assistant
      </code>
      
      , <code>
        tool
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].content
      </code>
    </td>
    
    <td>
      string|array
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      Une chaîne ou un tableau de parties de contenu structurées. Obligatoire pour chaque rôle. Les chaînes utilisateur doivent contenir du texte autre que des espaces. Pour un résultat d’outil, conservez <code>
        content
      </code>
      
       et indiquez un <code>
        tool_call_id
      </code>
      
       correspondant à un appel antérieur de l’assistant. Le rôle <code>
        system
      </code>
      
       accepte uniquement une chaîne comme contenu.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Remplace le modèle IA utilisé pour cette requête. Voir <a href="#model-override">
        model override
      </a>
      
       ci-dessous.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Fournisseur IA pour le remplacement de modèle : <code>
        openai
      </code>
      
      , <code>
        anthropic
      </code>
      
       ou <code>
        google
      </code>
      
      . Détecté automatiquement à partir du nom du modèle lorsque c'est possible.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        modelConnection
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      <code>
        { "id", "revision" }
      </code>
      
       d'une connexion de modèle d'équipe vérifiée : votre propre endpoint rédige la réponse. Incompatible avec <code>
        model
      </code>
      
      /<code>
        provider
      </code>
      
      . Voir <a href="#your-own-model">
        votre propre modèle
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Nom d'affichage optionnel du véritable utilisateur final pour cette requête. S'il est omis, <code>
        null
      </code>
      
       ou vide, Minds s'adresse à l'utilisateur de façon neutre et n'infère aucun nom depuis le propriétaire de la clé API ou du compte. Alias : <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Indication de la langue de réponse. Valeurs prises en charge : <code>
        en
      </code>
      
      , <code>
        de
      </code>
      
      , <code>
        es
      </code>
      
      , <code>
        fr
      </code>
      
      , <code>
        zh
      </code>
      
      , <code>
        tr
      </code>
      
      , <code>
        ar
      </code>
      
      , <code>
        ja
      </code>
      
      , <code>
        ko
      </code>
      
      . Les personas fortes (p. ex. clones de personnalités publiques avec une langue native fixe) peuvent continuer à répondre dans la langue de leur persona.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Si <code>
        true
      </code>
      
      , active la génération d'images par IA dans la réponse lorsque le contexte s'y prête
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        response_format
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Demande une sortie structurée. Voir <a href="#structured-output">
        structured output
      </a>
      
       ci-dessous.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tools
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Tableau de définitions d'outils définis par l'utilisateur. Voir <a href="#tool-calling">
        tool calling
      </a>
      
       ci-dessous.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_choice
      </code>
    </td>
    
    <td>
      string|object
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Contrôle le comportement d'appel d'outils. Voir <a href="#tool-choice-modes">
        tool choice modes
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parallel_tool_calls
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Autorise plusieurs appels d'outils par tour (par défaut : <code>
        true
      </code>
      
      ).
    </td>
  </tr>
</tbody>
</table>

### Réponse

```json
{
  "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
      }
    ]
  }
}
```

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Identifiant de message unique pour le suivi
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Le texte de la réponse du mind (chaîne JSON en cas de sortie structurée)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parsed
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Objet JSON analysé (présent uniquement lors de l'utilisation de <code>
        response_format
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_calls
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Tableau de demandes d'appel d'outils (présent uniquement lorsque des outils définis par l'utilisateur sont appelés). Chaque élément contient : <code>
        id
      </code>
      
      , <code>
        name
      </code>
      
      , <code>
        arguments
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Métadonnées optionnelles (citations, images)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.ragCitations
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Sources de connaissance et résultats de recherche web utilisés dans la réponse
    </td>
  </tr>
</tbody>
</table>

## Exemple de message unique

Poser une seule question :

```bash
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 :

```bash
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.

```bash
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 :

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Requis
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non*
    </td>
    
    <td>
      URL externe vers le fichier (HTTP/HTTPS)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non*
    </td>
    
    <td>
      Chemin de stockage Supabase (signé automatiquement)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Nom d'affichage du fichier
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Type MIME (p. ex. <code>
        application/pdf
      </code>
      
      , <code>
        image/png
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Description optionnelle
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcription
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Contenu audio/vidéo pré-transcrit
    </td>
  </tr>
</tbody>
</table>

**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

```json
{
  "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 :

```json
{
  "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` :

```json
{
  "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 :

```bash
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 :

```json
{
  "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.

```bash
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

<table>
<thead>
  <tr>
    <th>
      Fournisseur
    </th>
    
    <th>
      Valeur
    </th>
    
    <th>
      Exemples de modèles
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      OpenAI
    </td>
    
    <td>
      <code>
        openai
      </code>
    </td>
    
    <td>
      <code>
        gpt-6-astra
      </code>
      
      , <code>
        gpt-6.1-sol
      </code>
      
      , <code>
        gpt-6-luna
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Anthropic
    </td>
    
    <td>
      <code>
        anthropic
      </code>
    </td>
    
    <td>
      <code>
        claude-fable-5-1
      </code>
      
      , <code>
        claude-opus-5-5
      </code>
      
      , <code>
        claude-sonnet-5-5
      </code>
      
      , <code>
        claude-haiku-4-5-20251001
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Google
    </td>
    
    <td>
      <code>
        google
      </code>
    </td>
    
    <td>
      <code>
        gemini-3.8-flash
      </code>
      
      , <code>
        gemini-3.5-flash-lite
      </code>
    </td>
  </tr>
</tbody>
</table>

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](/guide/team-model-connections) (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` :

```json
{
  "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 :

```bash
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 :

```json
{
  "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 :

```bash
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

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      Sortie texte par défaut (comportement actuel)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_object
      </code>
    </td>
    
    <td>
      Force une sortie JSON valide sans validation de schéma
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_schema
      </code>
    </td>
    
    <td>
      Force une sortie JSON correspondant au schéma fourni
    </td>
  </tr>
</tbody>
</table>

### Champs JSON Schema

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Requis
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      Identifiant du schéma
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Description de ce que représente le schéma
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      Définition JSON Schema
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Non
    </td>
    
    <td>
      Applique strictement le schéma (par défaut : <code>
        true
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 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 :**

```bash
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 :**

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

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

```bash
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 :**

```json
{
  "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 :

```json
{
  "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 :**

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nom de la fonction. Doit être unique et ne peut pas entrer en conflit avec les outils internes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Description claire de ce que fait l'outil et de quand l'utiliser. Elle guide la sélection d'outils par le mind.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parameters
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Schéma JSON définissant les arguments de la fonction.
    </td>
  </tr>
</tbody>
</table>

**Champs optionnels :**

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Défaut
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Applique strictement la validation du schéma pour les arguments.
    </td>
  </tr>
</tbody>
</table>

### Tool Choice Modes

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

<table>
<thead>
  <tr>
    <th>
      Valeur
    </th>
    
    <th>
      Comportement
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        "auto"
      </code>
    </td>
    
    <td>
      Le mind décide s'il faut appeler des outils (par défaut)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "required"
      </code>
    </td>
    
    <td>
      Le mind doit appeler au moins un outil avant de répondre
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "none"
      </code>
    </td>
    
    <td>
      Désactive l'appel d'outils pour ce tour
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {"name": "tool_name"}
      </code>
    </td>
    
    <td>
      Force le mind à appeler un outil spécifique
    </td>
  </tr>
</tbody>
</table>

**Exemples :**

```json
// 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é :

```json
{
  "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 :

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

### Format du message Tool

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

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

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Requis
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      Doit être <code>
        "tool"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_call_id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      L'<code>
        id
      </code>
      
       du tool call dans la réponse de l'assistant
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Oui
      </strong>
    </td>
    
    <td>
      Résultat d'exécution de l'outil (généralement une chaîne JSON)
    </td>
  </tr>
</tbody>
</table>

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 :

<table>
<thead>
  <tr>
    <th>
      Outil interne
    </th>
    
    <th>
      Objectif
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET_SPARK_RAG
      </code>
    </td>
    
    <td>
      Rechercher dans la base de connaissances du mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WEB_SEARCH
      </code>
    </td>
    
    <td>
      Rechercher sur le web
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GENERATE_IMAGE
      </code>
    </td>
    
    <td>
      Générer des images avec l'IA
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DISPLAY_IMAGE
      </code>
    </td>
    
    <td>
      Afficher des images depuis la mémoire du mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DOCUMENT_PROCESSING
      </code>
    </td>
    
    <td>
      Analyser les fichiers téléversés
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ANALYZE_LINK
      </code>
    </td>
    
    <td>
      Récupérer et analyser des URL web
    </td>
  </tr>
</tbody>
</table>

**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 :

```bash
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 :**

```json
{
  "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.```json
❌ "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.```json
"case_id": {
  "type": "string",
  "description": "Unique case identifier in format CASE-YYYY-NNNN"
}
```
3. **Tirez parti des enums pour les valeurs contraintes** :```json
"status": {
  "type": "string",
  "enum": ["pending", "active", "closed", "archived"]
}
```
4. **Définissez des contraintes de validation** :```json
"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 :```json
{
  "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 :```json
{
  "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 :**

```json
{
  "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 :

```json
{
  "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 :

```json
{
  "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 :

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

## Formats de réponse

### Réponse texte

La plupart des réponses sont en texte brut :

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

### Réponse structurée

Certains minds peuvent renvoyer du contenu structuré :

```json
{
  "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) :

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

## Bonnes pratiques

### Soyez précis

```text
❌ "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

```text
✅ "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 :

```text
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 :

```text
✅ "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 :

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

Fournisseur non pris en charge :

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

Nom de modèle ambigu sans fournisseur :

```json
{
  "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 :

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

### 404 Not Found

Le Mind n'existe pas :

```json
{
  "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](/docs/api/latency)
- En savoir plus sur [errors and rate limits](/docs/api/errors)
- Créer votre premier [mind](/docs/api/minds)
- Téléverser des [connaissances](/docs/api/knowledge) pour enrichir les réponses
- Lire l'[aperçu de l'API](/docs/api/overview)