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

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête :

{
  "name": "My Conversation",
  "sparkId": "your-spark-id"
}

Réponse (201) :

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "sparks": [
      {
        "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

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", "sparkId": "your-spark-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
• Les 8 derniers messages sont transmis en contexte complet
• Les messages plus anciens sont compressés dans un résumé LLM glissant
• Les conversations peuvent durer des semaines ou des mois sans atteindre les limites de contexte

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/sparks/{sparkId}/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": "Spark knowledge",
        "similarity": 0.89
      }
    ]
  }
}

Exemple de message unique

Poser une seule question :

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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/sparks/spark-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 :

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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": "uploads/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": "uploads/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/sparks/spark-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/sparks/spark-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-4o-mini"
  }'

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

Fournisseurs

Vous pouvez passer n'importe quelle chaîne de modèle prise en charge par le fournisseur. 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).

Pour les modèles aux noms ambigus, spécifiez explicitement le provider :

{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}

Si le fournisseur ne peut pas être déterminé, l'API renvoie une erreur 400 Bad Request vous demandant de le spécifier.

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/sparks/spark-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/sparks/spark-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/sparks/spark-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/sparks/spark-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\": {...}}"
}

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/sparks/spark-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": "Spark 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 spark manquant ou invalide :

{
  "statusCode": 400,
  "statusMessage": "Spark 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 spark :

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

404 Not Found

Le spark n'existe pas :

{
  "statusCode": 404,
  "statusMessage": "Spark 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