Sparks API

Créez et gérez des AI minds (agents) de manière programmatique. Les minds sont des assistants IA personnalisables avec une expertise, une personnalité et des connaissances spécifiques.

Base URL : https://getminds.ai/api/v1 ou https://api.getminds.ai/v1

Obtenir un spark

Récupérez un mind unique avec tous ses détails, y compris le system prompt, les paramètres de partage et le nombre d'éléments de connaissance.

Endpoint : GET /api/v1/sparks/{sparkId}

Headers :

Authorization: Bearer minds_your_api_key

Réponse

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}

Champs de réponse

Exemple de requête

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Réponses d'erreur

400 Bad Request — Format d'ID de spark invalide

401 Unauthorized — API key invalide ou manquante

403 Forbidden — Pas d'accès à ce mind

404 Not Found — Le mind n'existe pas

Lister les sparks

Récupérez tous les minds appartenant à l'utilisateur authentifié.

Endpoint : GET /api/v1/sparks

Headers :

Authorization: Bearer minds_your_api_key

Paramètres de requête

Réponse

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}

Champs de réponse

Exemple de requête

curl -X GET "https://getminds.ai/api/v1/sparks?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Créer un spark

Créez un nouveau AI mind avec une configuration personnalisée en utilisant différents modes d'entraînement.

Endpoint : POST /api/v1/sparks

Headers :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}

Paramètres

Valeurs de mode

Le paramètre mode détermine comment votre mind sera entraîné :

• keywords (par défaut) — Entraînez votre mind avec des mots-clés séparés par des virgules. L'IA rassemblera les informations pertinentes depuis différentes sources sur la base de ces mots-clés pour construire la base de connaissances du mind.
  • Champ requis : keywords — Tableau de mots-clés/sujets
  • Idéal pour : Expertise générale sur des sujets ou domaines spécifiques
• clone — Clonez le style et les connaissances d'une personne en fournissant son nom et son contexte. L'IA fera des recherches et construira un profil complet imitant son expertise et son style de communication.
  • Champ requis : personaContext — Nom et bref contexte (par ex. « Ada Lovelace, pioneering computer scientist »)
  • Idéal pour : Émuler des individus spécifiques, des personnages historiques ou des experts reconnus
• link — Entraînez votre mind avec le contenu d'une URL spécifique. Fournissez un lien vers un profil, portfolio ou site web, et l'IA analysera et extraira les informations pertinentes.
  • Champ requis : contextLink — URL vers la source de contenu
  • Idéal pour : Entraîner sur des sites web, portfolios ou profils en ligne spécifiques
• manual — Créez un mind sans entraînement automatique. Vous configurerez manuellement tous les paramètres et ajouterez des connaissances plus tard via l'API Knowledge.
  • Aucun champ supplémentaire requis
  • Idéal pour : Des configurations personnalisées où vous voulez un contrôle total sur les données d'entraînement

Traitement automatique : Quand vous utilisez keywords, clone ou link, le backend reproduit le formulaire Add Spark in-product — il dérive les mots-clés d'entités (assistés par IA pour clone/link) et entraîne le mind de façon asynchrone. Suivez cet entraînement via le bloc training de la réponse de création et le endpoint dédié décrit dans Cycle de vie de l'entraînement du mind ci-dessous. Le mode manual ignore cette automatisation pour que vous puissiez entraîner le mind plus tard via l'API Knowledge.

Valeurs de type

• creative — Pour les artistes, designers, écrivains et professionnels créatifs
• expert — Pour les spécialistes, consultants et experts d'un domaine
• user — Pour les personas utilisateurs, clients et archétypes d'audience cible

Réponse

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}

Le bloc training indique le cycle de vie du mind au moment de la création. Les modes keywords, clone et link démarrent en queued et s'entraînent en arrière-plan ; les minds manual reviennent en completed avec readyToChat déjà à true. L'id d'un mind existe dès que cet appel se termine, mais le mind ne peut répondre que lorsque readyToChat vaut true. Voir Cycle de vie de l'entraînement du mind ci-dessous pour le polling.

Exemple : Créer un mind en mode keywords

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'

Exemple : Créer un mind en mode clone

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'

Exemple : Créer un mind en mode link

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'

Exemple : Créer un mind en mode manual

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'

Cycle de vie de l'entraînement du mind

La création d'un mind est asynchrone. POST /v1/sparks renvoie immédiatement un id, mais pour les modes keywords, clone et link, le mind est encore en cours d'entraînement en arrière-plan. L'existence de l'id d'un mind ne signifie pas que le mind est prêt — le mind ne peut répondre que lorsque readyToChat vaut true. La seule exception est le mode manual : ces minds sautent la collecte de données et sont completed dès leur création.

Interrogez le endpoint d'entraînement dédié jusqu'à ce que le mind soit prêt :

curl "https://getminds.ai/api/v1/sparks/{sparkId}/training" \
  -H "Authorization: Bearer minds_your_api_key"

{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}

Valeurs de statut

GET /v1/sparks/{id} renvoie aussi readyToChat (et trainingStatus) avec le reste du mind, de sorte qu'une seule lecture vous indique à la fois qui est le mind et s'il peut déjà répondre.

En cas d'échec de l'entraînement

Quand status vaut failed, la réponse inclut un objet error avec un code et un indicateur retryable :

Relancer l'entraînement

Si un mind se termine en failed (ou si vous voulez simplement reconstruire un mind completed), relancez son entraînement :

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"

Cela remet le mind en file d'attente et renvoie un nouveau bloc training avec status défini sur queued. La relance ne fonctionne que sur les minds terminés : un mind encore en queued ou running renvoie 409 Conflict car un entraînement est déjà en cours. Après la relance, interrogez de nouveau GET /v1/sparks/{id}/training jusqu'à ce que readyToChat vaille true.

Images de profil

Quand vous fournissez un profileImageUrl :

1. L'image est téléchargée depuis l'URL externe
2. Uploadée dans un storage sécurisé
3. L'URL stockée est renvoyée dans la réponse

Formats pris en charge : JPG, PNG, GIF, WEBP

Fonctionnement de l'entraînement

Le système génère automatiquement un system prompt intelligent basé sur votre mode, type et discipline choisis :

• Mode keywords : Crée une expertise autour de vos mots-clés spécifiés
• Mode clone : Construit un profil émulant le style et les connaissances de la personne spécifiée
• Mode link : Extrait les connaissances depuis l'URL fournie
• Mode manual : Crée un assistant basique que vous entraînerez avec des connaissances personnalisées

Vous pouvez enrichir davantage votre mind en uploadant des connaissances après la création.

Limites selon l'offre

Les différents plans ont des limites de création de minds différentes :

Quand vous atteignez votre limite, vous recevrez une erreur 403 Forbidden :

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Réponses d'erreur

400 Bad Request

Paramètres manquants ou invalides.

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

401 Unauthorized

API key invalide ou manquante.

403 Forbidden

Limite de l'offre atteinte.

500 Internal Server Error

Erreur côté serveur (rare).

Mettre à jour un spark

Mettez à jour la configuration d'un mind existant, y compris le nom, la description, le system prompt et d'autres paramètres.

Endpoint : PUT /api/v1/sparks/{sparkId}

Headers :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}

Paramètres

System prompt

Le champ systemPrompt vous permet de personnaliser comment votre mind se comporte et répond. C'est utile pour :

• Personnalisation de persona : Définir des traits de personnalité spécifiques, un style de communication ou des domaines d'expertise
• Formatage des réponses : Instruire le mind à répondre dans des formats spécifiques (par ex. listes à puces, listes numérotées)
• Contraintes de domaine : Limiter les réponses à des sujets ou perspectives spécifiques
• Langue/ton : Définir la langue, le niveau de formalité ou le ton des réponses

Exemples de system prompts :

# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.

# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.

Réponse

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}

Exemple : Mettre à jour le system prompt

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'

Exemple : Mettre à jour plusieurs champs

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'

Réponses d'erreur

400 Bad Request — Aucun champ valide à mettre à jour ou valeurs de champ invalides

401 Unauthorized — API key invalide ou manquante

403 Forbidden — Pas la permission de mettre à jour ce mind (vous devez en être le propriétaire)

404 Not Found — Le mind n'existe pas

Obtenir les patterns de connaissance d'un spark

Récupérez les patterns de pensée et les connaissances organisées par framework pour un mind spécifique.

Endpoint : GET /api/v1/sparks/{sparkId}/knowledge/patterns

Headers :

Authorization: Bearer minds_your_api_key

Structure de la réponse

L'endpoint renvoie les patterns groupés par frameworks (par ex. AOX Internal, OCEAN, DISC, etc.), avec des méthodes et des compétences montrant les occurrences et les preuves.

{
  "success": true,
  "data": {
    "sparkId": "550e8400-e29b-41d4-a716-446655440000",
    "sparkName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "spark": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "spark": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Comprendre la réponse

• frameworks : Tableau de frameworks contenant les patterns du spark
  • totalOccurrences : Nombre total de patterns dans ce framework
  • methods : Méthodes ou approches de pensée détectées
    • occurrences : Nombre de fois où cette méthode apparaît
    • competencies : Compétences ou sous-domaines spécifiques au sein de la méthode
      • occurrences : Nombre de patterns pour cette compétence
      • evidence : Tableau de citations démontrant ce pattern
        • spark : La citation réelle ou l'insight issu du contenu
        • portfolioItemId : Référence au matériel source
        • createdAt : Date d'identification du pattern

Exemple de requête

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

Cas d'usage

• Comprendre l'expertise d'un mind : Voyez quelles méthodes et compétences votre mind a apprises
• Assurance qualité : Vérifiez que les patterns sont correctement extraits des données d'entraînement
• Lacunes de connaissance : Identifiez les domaines où davantage de données d'entraînement sont nécessaires
• Comparaison de frameworks : Comparez la performance d'un mind à travers différents frameworks

Réponses d'erreur

401 Unauthorized — API key invalide ou manquante

403 Forbidden — Pas d'accès à ce mind

404 Not Found — Le mind n'existe pas

Régénérer le system prompt

Régénérez tous les composants du system prompt d'un spark en utilisant sa base de connaissances existante. Utilise la même génération assistée par IA que le bouton « Generate All » de l'UI.

Endpoint : POST /api/v1/sparks/{sparkId}/regenerate-prompt

Headers :

Authorization: Bearer minds_your_api_key

Fonctionnement

L'endpoint analyse la base de connaissances du mind (portfolio items, patterns, embeddings) et génère tous les composants du prompt :

Pour les sparks de type user :

• Core Identity & Demographics
• Needs & Motivations
• Pain Points & Challenges
• Tone & Communication Style
• Goals & Desires
• Behavioral Patterns

Pour les sparks de type expert :

• Core Identity & Personality
• Professional Expertise & Credentials
• Tone & Communication Style
• Professional Approach & Methods
• Domain Knowledge

Pour les sparks de type creative :

• Core Identity & Personality
• Creative Philosophy & Values
• Tone & Communication Style
• Creative Approach & Methods
• Domain Expertise

Réponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Spark",
    "systemPrompt": "## Core Identity & Demographics\n\n...",
    "promptLength": 2847
  }
}

Exemple de requête

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"

Cas d'usage

• Après ajout de connaissances : Régénérez le prompt pour intégrer les éléments de connaissance récemment ajoutés
• Affinage de persona : Régénérez pour mettre à jour la persona en fonction des patterns de connaissance actuels
• Réinitialiser les personnalisations : Effacez les modifications manuelles et régénérez des prompts frais depuis la base de connaissances

Réponses d'erreur

401 Unauthorized — API key invalide ou manquante

403 Forbidden — Pas la permission de modifier ce mind (vous devez en être le propriétaire)

404 Not Found — Le mind n'existe pas

500 Internal Server Error — Échec de la génération du prompt (par ex. connaissances insuffisantes)

Supprimer un spark

Supprimez définitivement un mind et toutes les données associées, y compris les connaissances, portfolio items et fichiers.

Endpoint : DELETE /api/v1/sparks/{sparkId}

Headers :

Authorization: Bearer minds_your_api_key

Réponse

Renvoie 204 No Content avec un corps vide en cas de succès.

Exemple de requête

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Ce qui est supprimé

Quand vous supprimez un mind, les éléments suivants sont définitivement supprimés :

• Le mind lui-même et toute sa configuration
• Toutes les connaissances et données d'entraînement
• Tous les portfolio items et fichiers associés
• Tout l'historique de chat et les messages
• Les images de profil et fichiers uploadés

Attention : Cette action est irréversible.

Réponses d'erreur

400 Bad Request — Format d'ID de spark invalide

401 Unauthorized — API key invalide ou manquante

403 Forbidden — Pas la permission de supprimer ce mind (vous devez en être le propriétaire)

404 Not Found — Le mind n'existe pas

Étapes suivantes

• Uploader des connaissances vers votre mind
• Discuter avec votre mind
• Découvrez errors and limits