Chat API

Senden Sie Nachrichten an Ihre Minds und erhalten Sie KI-generierte Antworten. Die Chat API unterstützt sowohl stateless Completions als auch stateful Multi-Turn-Konversationen mit automatischem History-Management.

Stateful Chats (empfohlen)

Erstellen Sie persistente Konversationen, bei denen der Server History, Context-Kompression und rollende Zusammenfassungen automatisch verwaltet. Es ist nicht nötig, mit jedem Request den kompletten Nachrichtenverlauf mitzusenden.

Chat erstellen

Erstellt eine neue stateful Konversation, die mit einem Mind verknüpft ist.

Endpoint: POST /api/v1/chats

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

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

Response (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"
      }
    ]
  }
}

Nachricht senden

Senden Sie eine Nachricht an einen bestehenden Chat. Der Server übernimmt automatisch Konversationsverlauf, Context-Window-Kompression und rollende Zusammenfassungen.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

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

Die Modellauswahl für stateful Chat folgt dieser Reihenfolge: Per-Request-Override, dann die bevorzugte Provider-Einstellung des Teams, wenn sie konfiguriert und berechtigt ist, danach der Produktstandard. Bei diesem Endpoint werden partielle Overrides mit 400 Bad Request abgelehnt; sende entweder sowohl model als auch provider oder keinen der beiden Werte.

Response:

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

Multi-Turn-Beispiel

Bei stateful Chats senden Sie jedes Mal einfach die neue Nachricht. Der Server merkt sich alles:

# Schritt 1: Einen Chat erstellen
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')

# Schritt 2: Nachrichten senden (Server verwaltet History automatisch)
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?" }'

# Schritt 3: Nachfassen (der Mind erinnert sich an den vorherigen Austausch)
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?" }'

So funktioniert es unter der Haube:

• Jede Nachricht wird in der Datenbank persistiert
• Die letzten 8 Nachrichten werden vollständig in den Kontext übernommen
• Ältere Nachrichten werden zu einer rollenden LLM-Zusammenfassung komprimiert
• Konversationen können über Wochen/Monate laufen, ohne Context-Limits zu erreichen

Stateless Completions

Für Einzelanfragen oder wenn Sie den Konversationsverlauf selbst verwalten möchten.

Nachricht senden

Senden Sie Nachrichten an einen Mind und erhalten Sie Antworten.

Endpoint: POST /api/v1/sparks/{sparkId}/completion

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

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

Parameter

Response

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

Beispiel für eine einzelne Nachricht

Stellen Sie eine einzelne Frage:

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

Multi-Turn-Konversation

Erhalten Sie den Konversationskontext, indem Sie vorherige Nachrichten mitsenden:

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

Tipps für Multi-Turn-Konversationen:

• Fügen Sie in jedem Request den vollständigen Konversationsverlauf ein
• Reihenfolge ist wichtig: Nachrichten müssen chronologisch sortiert sein
• Wechseln Sie zwischen den Rollen user und assistant
• Die letzte Nachricht sollte immer von user stammen

Datei-Anhänge

Hängen Sie Dateien, Dokumente, Bilder und Links an, um Ihren Minds Kontext zu geben. Minds erhalten den verarbeiteten Inhalt als Teil der Konversation.

Dateien anhängen

Fügen Sie Dateien über das Array metadata.attachedFiles in Ihrer User-Nachricht hinzu:

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

Anhang-Format

Jedes Attachment-Objekt unterstützt:

Hinweis: Geben Sie entweder url ODER path an, nicht beides.

Unterstützte Dateitypen

Dokumente:

• PDF (.pdf) - Textextraktion + OCR für gescannte Seiten
• Word (.docx) - Vollständige Textextraktion
• Text (.txt, .md) - Direkter Textinhalt
• CSV/Excel (.csv, .xlsx) - Tabellen-Extraktion

Bilder:

• PNG, JPG, WEBP - OCR + visuelle Analyse
• Vision-Fähigkeiten für Bildverständnis

Externe URLs:

• Webseiten werden mit Firecrawl geladen (JS-Rendering + Screenshots)
• Automatische Markdown-Konvertierung

Verarbeitung

Dateien werden automatisch verarbeitet, bevor sie an den Mind gesendet werden:

1. Download - Dateien werden von URL oder Supabase Storage geladen
2. Extraktion - Inhalt wird extrahiert (Text aus PDFs, OCR aus Bildern usw.)
3. Injection - Verarbeiteter Inhalt wird dem Konversationskontext hinzugefügt
4. Response - Mind sieht sowohl Ihre Nachricht als auch den Dateiinhalt

Verarbeitungs-Limits:

• Timeout: 30 Sekunden pro Datei
• Dateien werden parallel verarbeitet
• Fehlgeschlagene Dateien zeigen freundliche Fallback-Nachrichten

Beispiel mit mehreren Dateien

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

Datei-Anhänge im Konversationsverlauf

Wenn Sie eine Konversation mit Datei-Anhängen fortsetzen, fügen Sie die ursprüngliche Nachricht samt Anhängen in die History ein:

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

Hinweis: Dateien werden nur einmal beim ersten Anhängen verarbeitet. Folgende Nachrichten in derselben Konversation beziehen sich auf den bereits verarbeiteten Inhalt.

Web-Links

Für Webseiten und externe Inhalte verwenden Sie das url-Feld:

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

Speziell für Webseiten:

• JavaScript-lastige Sites werden mit Firecrawl gerendert
• Screenshots werden für visuellen Kontext erfasst
• Inhalt wird in sauberes Markdown konvertiert

Error Handling

Wenn die Dateiverarbeitung fehlschlägt:

• Der Mind erhält eine Fallback-Nachricht, die anzeigt, dass die Datei angehängt wurde, aber die Verarbeitung fehlschlug
• Die Konversation läuft normal weiter
• Timeout-Fehler zeigen [Processing timeout - file may be too large]
• Andere Fehler zeigen [Processing failed - file uploaded but analysis unavailable]

So wissen Minds auch bei fehlgeschlagener Verarbeitung, dass ein Anhang versucht wurde.

Initiale Nachricht (Begrüßung)

Wenn Sie ein leeres Messages-Array oder keine Nachrichten senden, stellt sich der Mind selbst vor:

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

Response:

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

Sie können das für einen stateless Completion-Request verwendete KI-Modell optional durch den Parameter model überschreiben. Das ist nützlich für Benchmarking, Kostenoptimierung oder das Testen unterschiedlicher Modellverhalten. Stateful Chat- und Panel-Endpoints validieren Overrides strenger: model und provider müssen zusammen gesendet werden.

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

Wenn kein model angegeben ist, wird der Server-Standard verwendet.

Provider

Sie können jeden vom Provider unterstützten Modell-String übergeben. Der Provider wird aus gängigen Modellnamen-Präfixen automatisch erkannt (claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI).

Bei Modellen mit mehrdeutigen Namen geben Sie provider explizit an:

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

Kann der Provider nicht ermittelt werden, liefert die API einen 400 Bad Request-Fehler mit der Aufforderung, ihn anzugeben.

Strukturierte Ausgabe

Fordern Sie garantierte JSON-Antworten an, die einem bestimmten Schema entsprechen, mit dem Parameter response_format. Dies folgt dem OpenAI-Stil für strukturierte Ausgaben und ist nützlich, um strukturierte Daten aus Konversationen zu extrahieren.

JSON-Schema-Modus

Erzwingt, dass das Modell gültiges JSON passend zu Ihrem Schema ausgibt:

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

Response:

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

JSON-Object-Modus

Erzwingt JSON-Ausgabe ohne Schema-Validierung:

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

Response-Format-Typen

JSON-Schema-Felder

Unterstützte Schema-Features

Die folgenden JSON-Schema-Features werden unterstützt:

• Typen: string, number, integer, boolean, array, object, null
• Constraints: enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• Struktur: properties, required, items, additionalProperties
• Metadaten: description (wird zur Steuerung des Modells genutzt)

Hinweise

• Tools (RAG, Web Search usw.) funktionieren mit strukturierten Ausgaben — der Mind kann vor dem Generieren der strukturierten Antwort weiterhin seine Wissensbasis durchsuchen
• Das Feld parsed enthält aus Bequemlichkeit das geparste JSON-Objekt; content enthält den rohen JSON-String
• Alle großen Provider (OpenAI, Anthropic, Google) unterstützen strukturierte Ausgabe
• Bei komplexen Schemas sollten description-Felder hinzugefügt werden, um die Modellausgabe zu steuern

Tool Calling

Ermöglichen Sie Minds, während Konversationen Ihre eigenen Funktionen aufzurufen. Dies folgt dem OpenAI-kompatiblen Function-Calling-Pattern und erlaubt es, die Fähigkeiten von Minds mit externen Tools und APIs zu erweitern.

So funktioniert es

1. Tools definieren: Übergeben Sie Tool-Definitionen mit Namen, Beschreibungen und JSON-Schema-Parametern
2. Mind entscheidet: Der Mind entscheidet anhand der Konversation, wann Ihre Tools aufgerufen werden (oder Sie erzwingen es per tool_choice)
3. API liefert Tool Calls: Die Response enthält tool_calls mit Toolname und generierten Argumenten
4. Tools ausführen: Sie führen die Tools in Ihrer Anwendung aus und erhalten die Ergebnisse
5. Ergebnisse zurücksenden: Nehmen Sie Tool-Ergebnisse in die nächste Nachricht mit role: "tool" auf
6. Mind antwortet: Der Mind integriert die Tool-Ergebnisse in seine finale Antwort

Grundlegendes Beispiel

Request mit Tools:

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

Response:

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

Tool ausführen und Ergebnisse zurücksenden:

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

Finale Response:

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

Tool-Definition-Schema

Jedes Tool muss diese Struktur aufweisen:

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

Pflichtfelder:

Optionale Felder:

Tool-Choice-Modi

Steuern Sie über den Parameter tool_choice, wann und wie der Mind Tools aufruft:

Beispiele:

// Mind entscheiden lassen
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Ein bestimmtes Tool erzwingen
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Mindestens einen Tool Call erfordern
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

Parallele Tool Calls

Standardmäßig können Minds mehrere Tools in einem Turn aufrufen, um effizienter zu sein:

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

Um parallele Calls zu deaktivieren und sequenzielle Ausführung zu erzwingen:

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

Format für Tool-Nachrichten

Beim Zurücksenden von Tool-Ergebnissen verwenden Sie die Rolle tool:

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

Interne vs. User Tools

Minds hat eingebaute serverseitige Tools, die automatisch ausgeführt werden:

Zentrale Unterschiede:

• Interne Tools: Laufen serverseitig, Ergebnisse sind in content und metadata enthalten. Werden nie in tool_calls zurückgegeben.
• User Tools: Werden in tool_calls zurückgegeben, damit Sie sie ausführen. Ergebnisse müssen als tool-Nachrichten zurückgesendet werden.

Interne Tools können nicht überschrieben oder deaktiviert werden. User Tools sind additiv — sie erweitern die Fähigkeiten des Minds.

Vollständiges Multi-Tool-Beispiel

Ein juristischer Assistent-Mind mit mehreren benutzerdefinierten Tools:

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

Response mit parallelen Tool Calls:

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

Best Practices

1. Klare Beschreibungen schreiben: Das Feld description ist entscheidend. Seien Sie konkret dazu, wann und warum jedes Tool eingesetzt werden soll.

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

2. Parameterbeschreibungen nutzen: Helfen Sie dem Mind zu verstehen, was jeder Parameter bewirkt.

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

3. Enums für eingeschränkte Werte verwenden:

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

4. Validierungs-Constraints setzen:

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

5. Strict-Modus aktivieren: Belassen Sie strict: true (Standard), damit der Mind gültige Argumente erzeugt.
6. Strukturierte Tool-Ergebnisse zurückgeben: Verwenden Sie JSON für Tool-Ergebnisse, damit sie leicht zu parsen sind:

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

7. Fehler sauber behandeln: Liefern Sie Fehlerdetails im Tool-Ergebnis zurück:

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

Limitierungen

• Maximal 128 Tools pro Request
• Toolnamen müssen eindeutig sein und dürfen nicht mit internen Toolnamen kollidieren
• Tool-Ausführung geschieht client-seitig — Sie sind dafür verantwortlich, Ihre Tools sicher auszuführen
• Tool-Ergebnisse müssen im Konversationsverlauf zurückgesendet werden, damit der Mind antworten kann

JSON-Schema-Unterstützung

Das Feld parameters unterstützt Standard-JSON-Schema-Features:

Typen:

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

Validierung:

• enum — auf bestimmte Werte einschränken
• minimum, maximum — numerische Grenzen
• minLength, maxLength — Stringlänge
• minItems, maxItems — Arraygröße
• pattern — Regex-Validierung
• format — Stringformate (z. B. "date-time", "email", "uri")

Struktur:

• properties — Objekt-Eigenschaften
• required — Pflichtfelder
• items — Array-Item-Schema
• additionalProperties — zusätzliche Eigenschaften erlauben/verbieten

Beispiel mit erweiterter Validierung:

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

So funktioniert es

1. Kontext-Laden

Wenn Sie eine Nachricht senden, lädt der Mind:

• Seinen System Prompt und seine Konfiguration
• Durchsucht automatisch seine Wissensbasis nach relevanten Informationen
• Berücksichtigt den Konversationsverlauf

2. Verarbeitung

Der Mind:

• Analysiert Ihre Nachricht im Kontext
• Grundiert Antworten in abgerufenem Wissen mit Citations
• Greift bei Bedarf auf weitere Tools zu (Web Search, Bildgenerierung usw.)
• Formuliert eine Antwort, die zu seiner Persönlichkeit passt

3. Antwortgenerierung

Der Mind:

• Erzeugt eine Antwort, die seine Expertise widerspiegelt
• Fügt Citations hinzu, wenn er die Wissensbasis oder Webquellen nutzt
• Liefert die Nachricht mit optionalen Metadaten (Citations, Bilder usw.)

Metadaten

Responses können zusätzliche Metadaten enthalten:

Bilder

Wenn ein Mind Bilder generiert oder anzeigt:

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

Knowledge Citations

Wenn ein Mind Informationen aus seiner Wissensbasis oder aus der Web-Suche abruft:

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

Citation-Felder:

• id - Eindeutige Kennung der Quelle
• displaySource - Menschlich lesbarer Quellenname oder URL
• similarity - Relevanzwert (0–1), der angibt, wie gut die Quelle zur Anfrage passt

Minds durchsuchen vor der Antwort automatisch ihre Wissensbasis und fügen Citations hinzu, wenn sie ihre Antworten in bestimmten Quellen grundieren.

Zugriffskontrolle

Sie können mit Minds chatten, die Sie:

• Besitzen - Minds, die Sie erstellt haben
• Zugriff haben - Minds, die Teammitglieder mit Ihnen geteilt haben
• Mitglied sind - Minds in Team-Workspaces, denen Sie angehören
• Öffentliche Minds - öffentlich zugängliche Minds

Der Versuch, auf nicht autorisierte Minds zuzugreifen, liefert:

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

Antwort-Formate

Textantwort

Die meisten Antworten sind Klartext:

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

Strukturierte Antwort

Einige Minds liefern strukturierten Inhalt zurück:

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

Leere Antwort mit Metadaten

Manchmal werden nur Metadaten zurückgegeben (z. B. bei Bildgenerierung):

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

Best Practices

Seien Sie konkret

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

Geben Sie Kontext

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

Nutzen Sie Nachfragen

Profitieren Sie vom Konversationsgedächtnis:

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

Beziehen Sie sich auf Wissen

Wenn Sie Wissen hochgeladen haben, beziehen Sie sich darauf:

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

Error Responses

400 Bad Request

Fehlende oder ungültige Spark-ID:

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

Nicht unterstützter Provider:

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

Mehrdeutiger Modellname ohne Provider:

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

401 Unauthorized

Ungültiger API key.

403 Forbidden

Zugriff auf Spark verweigert:

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

404 Not Found

Spark existiert nicht:

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

Hinweise zur Nutzung

• Die v1 API erzwingt ein konfigurierbares Limit pro authentifiziertem Konto (standardmäßig 300 Requests pro Minute)
• Lesen Sie RateLimit-Limit und RateLimit-Remaining und beachten Sie Retry-After nach 429
• Begrenzen Sie parallele Completions, da Generierungsrequests ressourcenintensiv sind

Nächste Schritte

• Latency und Performance verstehen
• Mehr zu Errors und Rate Limits erfahren
• Erstellen Sie Ihren ersten Mind
• Laden Sie Wissen hoch, um Antworten zu verbessern
• Lesen Sie die API-Übersicht