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

Wählen Sie genau eine nicht leere Auswahl: mindId, mindIds oder audienceIds. Gemischte Auswahlen ergeben 400; ein leeres optionales Array überschreibt keinen einzelnen Mind. UUIDs sind unabhängig von Groß- und Kleinschreibung; doppelte IDs werden ignoriert. Die Chat-Erstellung akzeptiert höchstens 1 MiB JSON einschließlich Escape-Sequenzen. Größere Anfragen erhalten vor Datenbank- oder Berechtigungsprüfungen 413. Antworten sind privat und werden nicht zwischengespeichert.

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

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

Response (201):

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "minds": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

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

Chats mit einem oder mehreren Minds beachten die gespeicherte Richtlinie knowledge_only jedes Minds und die Webrecherche-Beschränkungen des Arbeitsbereichs. Ein eingeschränkter Mind nutzt die aktuelle Frage, seine trainierte Persona und relevante abgerufene Mind-Wissensinhalte; interne Tools, Client-Tools, früherer Chat-Kontext und kopierte Study-Quellen werden aus seinem Antwortkontext ausgeschlossen. Die Antwort meldet metadata.knowledgeRetrieval.status als grounded, wenn relevante Belege abgerufen wurden, oder als fallback, wenn keine verfügbar waren oder der Abruf fehlschlug. Bei mehreren Minds steht dies separat in den metadata jedes Eintrags in messages[].

Die Webrecherche-Berechtigung des Arbeitsbereichs ist von knowledge_only getrennt: Ist sie deaktiviert, entfallen Websuche und Linkanalyse-Tools; bereitgestelltes Material und der Gesprächsverlauf bleiben für Minds mit auto erhalten. Der oben beschriebene eingeschränkte Antwortkontext gilt für Minds mit knowledge_only.

Das rollende Gedächtnis setzt nach der ID der zuletzt erfassten Nachricht fort, statt sich auf eine Position zu verlassen, die sich durch geänderten kopierten Study-Kontext verschieben kann. Generierte Zusammenfassungszeilen zählen nicht als Gesprächsbeiträge; Systemnotizen des Eigentümers bleiben in v1-Chats verfügbar. Ein Hintergrundresultat wird verworfen, wenn eine andere Anfrage die zugrunde liegende gespeicherte Zusammenfassung geändert hat.

Schlägt die rollende Zusammenfassung fehl oder liefert sie keinen Zusammenfassungstext, übernimmt der Fallback die bisherige Zusammenfassung und gültige gespeicherte Fakten und ergänzt einen kurzen Abriss des neuen Gesprächsabschnitts. Der Fallback enthält pro Aktualisierung Auszüge aus höchstens 30 neu erfassten Nachrichten und setzt die Abdeckung nur bis zu diesen fort. Die übrigen Nachrichten bleiben für spätere Aktualisierungen offen. Bei der Anfrage-Komprimierung verhindert der gespeicherte Nachrichtenanker wiederholte Auszüge; aktuelle Nachrichten, hervorgehobene Belege und kopierter Study-Kontext bleiben erhalten.

Der Moderator unterscheidet Teilnehmende anhand ihrer Mind-ID. Minds mit demselben Anzeigenamen bleiben eigenständige Kandidaten; Gesprächslimits und die Vermeidung unmittelbar aufeinanderfolgender Beiträge gelten pro ID. Der Moderator kann die Diskussion beenden, bevor jeder Mind geantwortet hat.

Unerwartete Generierungsfehler liefern ein generisches 500 ohne Anbieterdetails; für fehlgeschlagene Antworten wird eine Erstattung reservierter Einheiten veranlasst. Bereits generierte Antworten und gespeicherte Nachrichten werden nicht rückgängig gemacht. Eine ausdrückliche Ablehnung wegen fehlender Modellfähigkeiten bleibt 400 mit data.errorType: "unsupported_model_capability". Bei Multi-Mind-Chats verzögert die optionale Zusammenfassung im Hintergrund keine bereits gespeicherte Antwort und macht daraus keinen Fehler.

Auch Nachrichtenanfragen haben ein JSON-Limit von 1 MiB; größere Anfragen erhalten vor Datenbank- oder Berechtigungsprüfungen 413. Antworten sind privat und werden nicht zwischengespeichert. Nur der Chat-Eigentümer darf schreiben. Verwaltete Workspaces prüfen bei jeder Anfrage den aktuellen Workspace und die Freigaben der angehängten Minds/Audiences erneut; entzogener Zugriff ergibt vor Speicherung oder Abrechnung 404.

Das folgende Antwortbeispiel gilt für einen einzelnen Mind. Multi-Mind-Chats liefern messages[], Study-Chats outputData. Mit role: "system" wird eine Kontextnotiz ohne Generierung oder Verbrauch des Nachrichtenlimits gespeichert; die Antwort lautet { messageId, role: "system" }.

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", "mindId": "your-mind-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
• In Chats mit einem Mind und langem Verlauf bleiben die letzten 8 Nachrichten im vollständigen Kontext
• Ältere Beiträge nutzen eine gespeicherte Zusammenfassung, sofern vorhanden, sowie Auszüge noch nicht erfasster Nachrichten
• Zusammenfassungen verlieren Details; sehr lange Verläufe oder große Nachrichten können weiterhin die Kontextgrenzen des Modells erreichen.

Chat löschen

DELETE /api/v1/chats/{chatId}

Nur der Eigentümer kann einen Chat samt Nachrichten endgültig löschen. Minds und Audiences bleiben erhalten. Bei Erfolg folgt 204 ohne Antworttext; die Antwort darf nicht als JSON geparst werden. Fehlende oder ungültige Zugangsdaten ergeben 401, ein fremder Chat 403 und ein fehlender Chat 404, auch wenn er vor dem abschließenden Schreibzugriff gelöscht oder übertragen wurde. Löschantworten verwenden Cache-Control: private, no-store.

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/minds/{mindId}/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": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}

Beispiel für eine einzelne Nachricht

Stellen Sie eine einzelne Frage:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'

Multi-Turn-Konversation

Erhalten Sie den Konversationskontext, indem Sie vorherige Nachrichten mitsenden:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

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:

Verwenden Sie für zustandslose Completions einen eigenen Upload, eine Chat-Datei-URL mit gültiger Signatur oder Kontext, der über die Study des Uploaders geteilt wurde. Ohne Dateiberechtigung folgt 403 Upload access denied (im Streaming-Modus als Fehler-Frame). Externe HTTP(S)-URLs behalten ihr eigenes Zugriffstoken; ein beliebiger Speicherpfad wird nicht neu signiert. Ersetzen Sie your-user-id in den Beispielen durch Ihre Benutzer-ID und verwenden Sie den Pfad aus der Upload-Antwort.

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "chat/your-user-id/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

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": "chat/your-user-id/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/minds/mind-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/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-6-luna"
  }'

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

Provider

Übergeben Sie eines der oben aufgeführten Modelle. Ausgemusterte IDs werden weitergeleitet (siehe unten); jedes andere Modell führt zu 400 Bad Request. Der Provider wird aus gängigen Modellnamen-Präfixen automatisch erkannt (claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI).

Your own model

Um ein Fine-Tune oder ein selbst gehostetes Modell zu nutzen, fügt ein Team-Admin es als Team-Modellverbindung hinzu (Protokoll OpenAI Chat Completions, OpenAI Responses oder Anthropic Messages) und prüft es. Senden Sie dann statt model und provider die ID und die aktuelle Revision der Verbindung:

{
  "messages": [...],
  "modelConnection": { "id": "3f6c1e2a-5b7d-4c1e-9a0f-2d8e4b6a1c90", "revision": 3 }
}

GET /api/v1/model-connections listet die Verbindungen Ihres Teams mit ihren Revisionen und geprüften Fähigkeiten auf. Die Verbindung benötigt Text und Streaming, außerdem strukturierte Ausgabe, wenn Sie response_format senden, und Werkzeugaufrufe, wenn die Anfrage Tools verwendet. Schlägt Ihr Endpunkt fehl, schlägt die Anfrage fehl: Minds wechselt nie auf eines seiner eigenen Modelle. Bilder und andere Medien werden mit MODEL_CONNECTION_MEDIA_UNVERIFIED abgelehnt. Stateful Chat-Nachrichten (/chats/{chatId}/messages) akzeptieren keine Verbindung.

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/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

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/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

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/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

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/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

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

Tool-Ergebnisse folgen auf die passende Assistant-Nachricht einschließlich ihrer tool_calls. Übernimm die zurückgegebene Aufruf-ID und den Namen und sende jedes Ergebnis einmal. Fehlerhafte Argumente, unbekannte Aufruf-IDs, abweichende Tool-Namen doppelte Ergebnisse und fehlende clientseitige Ergebnisse führen vor der Generierung zu 400.

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/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

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": "Mind 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 Mind-ID:

{
  "statusCode": 400,
  "statusMessage": "Mind 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 Mind verweigert:

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

404 Not Found

Mind existiert nicht:

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