Sparks API

Erstellen und verwalten Sie KI-Minds (Agenten) programmatisch. Minds sind anpassbare KI-Assistenten mit spezifischer Expertise, Persönlichkeit und Wissen.

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

Spark abrufen

Ruft einen einzelnen Mind mit allen Details ab, einschließlich System Prompt, Sharing-Einstellungen und Anzahl der Knowledge-Einträge.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "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
  }
}

Response-Felder

Beispiel-Request

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

Error Responses

400 Bad Request - Ungültiges Spark-ID-Format

401 Unauthorized - Ungültiger oder fehlender API key

403 Forbidden - Kein Zugriff auf diesen Mind

404 Not Found - Mind existiert nicht

Sparks auflisten

Ruft alle Minds des authentifizierten Nutzers ab.

Endpoint: GET /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key

Query-Parameter

Response

{
  "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
  }
}

Response-Felder

Beispiel-Request

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

Spark erstellen

Erstellt einen neuen KI-Mind mit individueller Konfiguration in verschiedenen Trainingsmodi.

Endpoint: POST /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

{
  "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"
}

Parameter

Werte für mode

Der Parameter mode bestimmt, wie Ihr Mind trainiert wird:

• keywords (Standard) - Trainieren Sie Ihren Mind über durch Komma getrennte Keywords. Die KI sammelt auf Basis dieser Keywords relevante Informationen aus verschiedenen Quellen, um die Wissensbasis des Minds aufzubauen.
  • Pflichtfeld: keywords - Array von Keywords/Themen
  • Am besten für: allgemeine Expertise zu bestimmten Themen oder Domänen
• clone - Klonen Sie den Stil und das Wissen einer Person, indem Sie ihren Namen und Kontext angeben. Die KI recherchiert und erstellt ein umfassendes Profil, das Expertise und Kommunikationsstil nachahmt.
  • Pflichtfeld: personaContext - Name und kurzer Kontext (z. B. "Ada Lovelace, pioneering computer scientist")
  • Am besten für: die Emulation bestimmter Personen, historischer Persönlichkeiten oder bekannter Expert:innen
• link - Trainieren Sie Ihren Mind mit Inhalten einer bestimmten URL. Geben Sie einen Link zu einem Profil, Portfolio oder einer Website an, und die KI analysiert und extrahiert relevante Informationen.
  • Pflichtfeld: contextLink - URL zur Inhaltsquelle
  • Am besten für: Training auf Basis spezifischer Websites, Portfolios oder Online-Profile
• manual - Erstellen Sie einen Mind ohne automatisches Training. Alle Einstellungen werden manuell konfiguriert; Wissen wird später über die Knowledge API ergänzt.
  • Keine zusätzlichen Felder erforderlich
  • Am besten für: individuelle Konfigurationen, bei denen Sie die volle Kontrolle über die Trainingsdaten haben möchten

Auto-Processing: Wenn Sie keywords, clone oder link verwenden, spiegelt das Backend das In-Product-Formular "Add Spark" — es leitet Entity-Keywords ab (KI-unterstützt bei clone/link) und trainiert den Mind asynchron. Verfolgen Sie dieses Training über den training-Block in der Erstellungsantwort und den dedizierten Endpunkt, der unter Mind-Trainingszyklus beschrieben wird. Der manual-Modus überspringt diese Automatisierung, sodass Sie den Mind später über die Knowledge API trainieren können.

Werte für type

• creative - Für Künstler:innen, Designer:innen, Autor:innen und Kreativschaffende
• expert - Für Spezialist:innen, Berater:innen und Domänenexpert:innen
• user - Für Nutzerpersonas, Kunden und Zielgruppen-Archetypen

Response

{
  "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
  }
}

Der training-Block meldet den Lebenszyklus des Minds bei der Erstellung. Die Modi keywords, clone und link starten mit queued und trainieren im Hintergrund; manual-Minds kommen mit completed und bereits auf true gesetztem readyToChat zurück. Die id eines Minds existiert, sobald dieser Aufruf zurückkehrt, aber der Mind kann erst antworten, wenn readyToChat true ist. Siehe Mind-Trainingszyklus unten für das Polling.

Beispiel: Mind im Keywords-Modus erstellen

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

Beispiel: Mind im Clone-Modus erstellen

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

Beispiel: Mind im Link-Modus erstellen

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

Beispiel: Mind im Manual-Modus erstellen

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

Mind-Trainingszyklus

Das Erstellen eines Minds erfolgt asynchron. POST /v1/sparks liefert sofort eine id zurück, aber bei den Modi keywords, clone und link wird der Mind im Hintergrund noch trainiert. Eine vorhandene id bedeutet nicht, dass der Mind bereit ist — der Mind kann erst antworten, wenn readyToChat true ist. Die einzige Ausnahme ist der manual-Modus: solche Minds überspringen die Datensammlung und sind completed, sobald sie erstellt wurden.

Fragen Sie den dedizierten Trainings-Endpunkt ab, bis der Mind bereit ist:

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
}

Statuswerte

GET /v1/sparks/{id} liefert ebenfalls readyToChat (und trainingStatus) zusammen mit dem restlichen Mind zurück, sodass ein einziger Aufruf Ihnen sowohl sagt, wer der Mind ist, als auch ob er schon antworten kann.

Wenn das Training fehlschlägt

Wenn status failed ist, enthält die Antwort ein error-Objekt mit einem code und einem retryable-Flag:

Neutraining

Wenn ein Mind mit failed endet (oder Sie einen completed Mind einfach neu aufbauen möchten), trainieren Sie ihn neu:

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

Dadurch wird der Mind erneut in die Warteschlange gestellt und ein frischer training-Block mit status auf queued zurückgegeben. Neutraining funktioniert nur bei Minds, die fertig sind: Ein Mind, der noch queued oder running ist, gibt 409 Conflict zurück, weil bereits ein Trainingslauf läuft. Fragen Sie nach dem Neutraining erneut GET /v1/sparks/{id}/training ab, bis readyToChat true ist.

Profilbilder

Wenn Sie eine profileImageUrl angeben:

1. Das Bild wird von der externen URL heruntergeladen
2. In sicheren Speicher hochgeladen
3. Die gespeicherte URL wird in der Response zurückgegeben

Unterstützte Formate: JPG, PNG, GIF, WEBP

So funktioniert das Training

Das System generiert automatisch einen intelligenten System Prompt auf Basis des gewählten Modus, Typs und der Discipline:

• Keywords-Modus: Erzeugt Expertise rund um Ihre angegebenen Keywords
• Clone-Modus: Baut ein Profil auf, das Stil und Wissen der angegebenen Person emuliert
• Link-Modus: Extrahiert Wissen aus der angegebenen URL
• Manual-Modus: Erzeugt einen Basis-Assistenten, den Sie mit eigenem Wissen trainieren

Sie können Ihren Mind weiter optimieren, indem Sie nach der Erstellung Wissen hochladen.

Plan-Limits

Verschiedene Pläne haben unterschiedliche Limits für die Erstellung von Minds:

Beim Erreichen des Limits erhalten Sie einen 403 Forbidden-Fehler:

{
  "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
  }
}

Error Responses

400 Bad Request

Fehlende oder ungültige Parameter.

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

401 Unauthorized

Ungültiger oder fehlender API key.

403 Forbidden

Plan-Limit erreicht.

500 Internal Server Error

Serverseitiger Fehler (selten).

Spark aktualisieren

Aktualisiert die Konfiguration eines bestehenden Minds, darunter Name, Beschreibung, System Prompt und weitere Einstellungen.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

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

Parameter

System Prompt

Über das Feld systemPrompt können Sie anpassen, wie Ihr Mind sich verhält und antwortet. Das ist nützlich für:

• Persona-Anpassung: Legen Sie konkrete Persönlichkeitsmerkmale, Kommunikationsstil oder Expertisebereiche fest
• Antwortformatierung: Weisen Sie den Mind an, in bestimmten Formaten zu antworten (z. B. Bulletpoints, nummerierte Listen)
• Domänen-Beschränkungen: Begrenzen Sie Antworten auf bestimmte Themen oder Perspektiven
• Sprache/Tonalität: Legen Sie Sprache, Formalitätsgrad oder Tonalität der Antworten fest

Beispiel-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.

Response

{
  "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"
  }
}

Beispiel: System Prompt aktualisieren

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."
  }'

Beispiel: Mehrere Felder aktualisieren

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

Error Responses

400 Bad Request - Keine gültigen Felder zum Aktualisieren oder ungültige Feldwerte

401 Unauthorized - Ungültiger oder fehlender API key

403 Forbidden - Keine Berechtigung, diesen Mind zu aktualisieren (Sie müssen der Owner sein)

404 Not Found - Mind existiert nicht

Spark-Knowledge-Patterns abrufen

Ruft Denkmuster und Wissen, nach Framework organisiert, für einen bestimmten Mind ab.

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

Headers:

Authorization: Bearer minds_your_api_key

Response-Struktur

Der Endpoint gibt Patterns zurück, die nach Frameworks gruppiert sind (z. B. AOX Internal, OCEAN, DISC usw.), mit Methoden und Kompetenzen inklusive Vorkommen und Belegen.

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

Verständnis der Response

• frameworks: Array von Frameworks, die die Patterns des Sparks enthalten
  • totalOccurrences: Gesamtzahl der Patterns in diesem Framework
  • methods: Erkannte Denkmethoden oder Ansätze
    • occurrences: Anzahl, wie oft diese Methode auftaucht
    • competencies: Spezifische Fähigkeiten oder Unterbereiche innerhalb der Methode
      • occurrences: Anzahl Patterns für diese Kompetenz
      • evidence: Array von Zitaten/Belegen, die dieses Pattern demonstrieren
        • spark: Das eigentliche Zitat oder der Insight aus dem Inhalt
        • portfolioItemId: Referenz auf das Quellmaterial
        • createdAt: Wann dieses Pattern identifiziert wurde

Beispiel-Request

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

Anwendungsfälle

• Expertise eines Minds verstehen: Sehen Sie, welche Methoden und Kompetenzen Ihr Mind gelernt hat
• Qualitätssicherung: Prüfen Sie, ob Patterns korrekt aus den Trainingsdaten extrahiert werden
• Wissenslücken: Erkennen Sie Bereiche, in denen mehr Trainingsdaten benötigt werden
• Framework-Vergleich: Vergleichen Sie, wie ein Mind über verschiedene Frameworks hinweg performt

Error Responses

401 Unauthorized - Ungültiger oder fehlender API key

403 Forbidden - Kein Zugriff auf diesen Mind

404 Not Found - Mind existiert nicht

System Prompt neu generieren

Generieren Sie alle System-Prompt-Komponenten für einen Spark neu auf Basis seiner bestehenden Wissensbasis. Hierzu wird dieselbe KI-gestützte Generierung wie beim "Generate All"-Button in der UI verwendet.

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

Headers:

Authorization: Bearer minds_your_api_key

Funktionsweise

Der Endpoint analysiert die Wissensbasis des Minds (Portfolio-Items, Patterns, Embeddings) und generiert alle Prompt-Komponenten:

Für Sparks vom Typ user:

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

Für Sparks vom Typ expert:

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

Für Sparks vom Typ creative:

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

Response

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

Beispiel-Request

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

Anwendungsfälle

• Nach dem Hinzufügen von Wissen: Prompt neu generieren, um neu hinzugefügte Knowledge-Einträge einzubeziehen
• Persona-Feintuning: Neu generieren, um die Persona basierend auf aktuellen Wissensmustern zu aktualisieren
• Anpassungen zurücksetzen: Manuelle Änderungen verwerfen und aus der Wissensbasis frische Prompts neu erzeugen

Error Responses

401 Unauthorized - Ungültiger oder fehlender API key

403 Forbidden - Keine Berechtigung, diesen Mind zu verändern (Sie müssen der Owner sein)

404 Not Found - Mind existiert nicht

500 Internal Server Error - Prompt konnte nicht generiert werden (z. B. wegen unzureichendem Wissen)

Spark löschen

Löscht einen Mind und alle zugehörigen Daten dauerhaft, einschließlich Wissen, Portfolio-Items und Dateien.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

Bei Erfolg wird 204 No Content mit leerem Body zurückgegeben.

Beispiel-Request

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

Was wird gelöscht

Wenn Sie einen Mind löschen, wird Folgendes dauerhaft entfernt:

• Der Mind selbst und seine gesamte Konfiguration
• Alle Knowledge- und Trainingsdaten
• Alle Portfolio-Items und zugehörigen Dateien
• Der gesamte Chatverlauf und alle Nachrichten
• Profilbilder und hochgeladene Dateien

Warnung: Diese Aktion kann nicht rückgängig gemacht werden.

Error Responses

400 Bad Request - Ungültiges Spark-ID-Format

401 Unauthorized - Ungültiger oder fehlender API key

403 Forbidden - Keine Berechtigung, diesen Mind zu löschen (Sie müssen der Owner sein)

404 Not Found - Mind existiert nicht

Nächste Schritte

• Wissen für Ihren Mind hochladen
• Mit Ihrem Mind chatten
• Mehr über Errors und Limits erfahren