API-Übersicht

Willkommen zur Dokumentation der Minds API. Unsere API ermöglicht es Ihnen, KI-Minds programmatisch zu erstellen und zu verwalten, Wissen hochzuladen und mit ihnen zu interagieren.

Erste Schritte

Die Minds API ist nach REST-Prinzipien aufgebaut. Unsere API verwendet vorhersehbare, ressourcenorientierte URLs, akzeptiert JSON-codierte Request-Bodies, liefert JSON-codierte Responses und nutzt standardmäßige HTTP-Statuscodes, Authentifizierung und Verben.

Base URL

Produktion: https://getminds.ai/api/v1 oder https://api.getminds.ai/v1

Lokale Entwicklung: http://localhost:3000/api/v1

Beide produktiven Base URLs sind vollständig gleichwertig. Für saubere Integrations-URLs empfehlen wir die Subdomain api.getminds.ai.

Authentifizierung

Alle API-Endpoints erfordern eine Authentifizierung per API key. Sie können Ihre API keys unter Settings → API Keys erzeugen und verwalten.

Binden Sie Ihren API key im Authorization-Header ein:

Authorization: Bearer minds_your_api_key_here

OpenAPI Spec

Eine maschinenlesbare OpenAPI-3.1.0-Spezifikation wird unter /_openapi.json veröffentlicht. Nutze die Spezifikation, um typisierte Clients (TypeScript, Python usw.) zu generieren oder sie für One-Shot-Integrationscode in ein LLM einzugeben. Siehe OpenAPI für Beispiele.

Content Type

Alle Requests, die Daten senden, sollten den Content-Type-Header enthalten:

Content-Type: application/json

Für Datei-Uploads verwenden Sie:

Content-Type: multipart/form-data

Verfügbare Endpoints

Minds

Erstellen und verwalten Sie KI-Minds (Agenten) mit individuellen Konfigurationen.

GET /api/v1/minds - Alle Minds auflisten
GET /api/v1/minds/{mindId} - Mind-Details abrufen
POST /api/v1/minds - Neuen Mind erstellen
PUT /api/v1/minds/{mindId} - Mind aktualisieren
DELETE /api/v1/minds/{mindId} - Mind löschen
POST /api/v1/minds/{mindId}/regenerate-prompt - System Prompt aus Wissen neu generieren
GET /api/v1/minds/{mindId}/patterns - Rohe Denkmuster eines Minds abrufen

Knowledge

Verwalten Sie das Wissen Ihrer Minds.

GET /api/v1/minds/{mindId}/knowledge - Knowledge-Einträge auflisten
POST /api/v1/minds/{mindId}/knowledge - Wissen hinzufügen (Links, Dateien oder Keyword-Suche)
PUT /api/v1/minds/{mindId}/knowledge/{itemId} - Knowledge-Eintrag aktualisieren
DELETE /api/v1/minds/{mindId}/knowledge/{itemId} - Knowledge-Eintrag löschen
POST /api/v1/minds/{mindId}/knowledge/enrich - Anreicherung per Keyword-Suche (Convenience-Alias)
GET /api/v1/minds/{mindId}/knowledge/patterns - Wissensmuster nach Framework abrufen

Chat

Interagieren Sie mit Ihren Minds über Chat Completions.

POST /api/v1/minds/{mindId}/completion - Nachrichten senden und Antworten erhalten

Studies

Erstellen und verwalten Sie KI-Studies, um Audiences von Minds zu befragen.

GET /api/v1/studies - Alle Studies auflisten
POST /api/v1/studies - Neues Study erstellen
GET /api/v1/studies/{studyId} - Study-Details inklusive Nachrichtenverlauf abrufen
POST /api/v1/studies/{studyId}/ask - Eine Frage an alle Study-Minds stellen (SSE-Stream)
POST /api/v1/studies/{studyId}/export - Study-Ergebnisse als Report exportieren
GET /api/v1/studies/{studyId}/export-status - Status des Export-Jobs prüfen
GET /api/v1/studies/{studyId}/export-download - Exportiertes PDF herunterladen

User

Benutzerbezogene Endpoints.

GET /api/v1/auth/me - Aktuell authentifizierten Benutzer abrufen
GET /api/v1/user/shareable-sparks - Minds auflisten, die zum Teilen verfügbar sind

API Keys

Verwalten Sie Ihre API keys für die Authentifizierung.

GET /api/v1/api-keys - Ihre API keys auflisten
POST /api/v1/api-keys - Neuen API key erstellen
DELETE /api/v1/api-keys/{keyId} - API key löschen

Schnellbeispiel

Hier ist ein kurzes Beispiel, das einen Mind erstellt und mit ihm chattet:

# 1. Einen Mind erstellen (keywords-Modus)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Expert in digital marketing strategies",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["SEO", "content marketing", "social media", "analytics"]
  }'

# Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } }

# 2. Einen Mind aus einem Social-Profil erstellen (clone-Modus)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Clone",
    "description": "AI trained on influencer social presence",
    "mode": "clone",
    "type": "creative",
    "discipline": "Social Media Marketing",
    "personaContext": "https://twitter.com/username"
  }'

# 3. Mit dem Mind chatten
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 social media trends for 2025?"
      }
    ]
  }'

Nächste Schritte

Erfahren Sie mehr über Authentifizierung
Entdecken Sie die Minds-Endpoints
Lesen Sie über Knowledge-Management
Verstehen Sie Chat Completions
Erstellen Sie Studies für Multi-Mind-Umfragen
Prüfen Sie Latency & Performance
Verbinden Sie sich per MCP-Integration
Prüfen Sie Errors & Limits

Plan-Limits

Der API- und MCP-Zugriff ist in unterstützten kostenpflichtigen Plänen verfügbar. Verarbeiten Sie strukturierte plan_limited- und 429-Antworten, statt Limits in Ihrer Integration fest zu codieren. Der Starter-Plan wird in API-Payloads als "premium" ausgegeben.

Die folgenden öffentlichen Standardwerte werden aus demselben Plan-Limit- und Feature-Access-Vertrag wie das Produkt generiert. Konto- und Enterprise-spezifische Overrides, die im Produkt angezeigt werden, haben Vorrang.

Plan	API & MCP	Studies	Minds & Audiences	Synthetische Antworten
Nutzungsbasiert	API, MCP und Standardintegrationen inklusive	Studies, Forschungsmethoden und Exporte inklusive	10 gespeicherte Audiences pro Workspace · Bis zu 200 Minds pro Audience	Jederzeit aufladen. Ungenutzte Antworten bleiben erhalten.

Pläne ansehen

Hilfe benötigt?

Wenn Sie Fragen haben oder Unterstützung zur API benötigen:

Sehen Sie sich unseren Guide an
Kontaktieren Sie uns über das Feedback-Formular
Nehmen Sie an unseren Community-Diskussionen teil

n8n-Workflows

Verwenden Sie den Minds-Community-Node für n8n, um Studies zu erstellen, Forschungspläne in der Vorschau anzuzeigen, Studies und gespeicherte Zusammenfassungen abzurufen oder eine Operation für einen AI Agent bereitzustellen. Installieren Sie n8n-nodes-minds auf selbst gehostetem n8n und verbinden Sie einen Minds API-Schlüssel. Das Paket ist auf npm veröffentlicht; die n8n-Verifizierung wird geprüft, daher ist es auf n8n Cloud noch nicht verfügbar. Überprüfen und starten Sie die Forschung separat in Minds.

Stripe-Abrechnung für Agenten

Nutzen Sie den authentifizierten Abrechnungskatalog, bevor Sie einen Kauf von Antwortguthaben vorschlagen. Neukunden nutzen Pay as you go; neue Starter-Abonnements und Testphasen werden eingestellt. Die Verwaltung bestehender Abonnements verbleibt in den Minds-Abrechnungseinstellungen. Bitten Sie den Käufer, das ausgewählte Antwortpaket und den endgültigen Stripe-Checkout-Betrag zu bestätigen.

Geben Sie für einen neuen Pay as you go-Workspace das Rechnungsland des Käufers an, wenn Sie den Katalog abrufen und den Checkout starten, damit die Preise aus dem richtigen Stripe-Konto stammen. Die Anzahl der Antworten bleibt die Kaufeinheit; jedes Paket hat denselben Stückpreis. Rufen Sie den Katalog erneut ab, wenn sich das Land ändert.

Starten Sie den Checkout mit einem stabilen Idempotency-Key aus 1–128 Buchstaben, Ziffern, Unterstrichen oder Bindestrichen. Behalten Sie denselben Schlüssel und Body nach einem Timeout bei; eine Änderung des Kaufs unter diesem Schlüssel wird abgelehnt. Geben Sie data.url unverändert an den Käufer zurück. Eine Checkout-URL ist kein Zahlungsnachweis: Die signierte Stripe-Auftragsabwicklung aktualisiert das geteilte Antwortguthaben.

{
  "kind": "response_credits",
  "amountMinor": 10000,
  "priceId": "price_from_customTopUp",
  "billingCountry": "DE"
}

MPP und x402 gelten für eigene offene send_invoice-Rechnungen in USD oder EUR mit mindestens 50 verbleibenden Untereinheiten. Automatisch eingezogene Rechnungen bleiben auf der Stripe-Rechnungsseite. Die Zahlungsanforderung enthält den tatsächlichen Restbetrag einschließlich Steuern und Rabatten. MPP erfordert ein Geschäftsprofil im zugehörigen Stripe-Konto. x402 erfordert zusätzlich Krypto-Berechtigung und einen eingerichteten Facilitator, unterstützt USD-Rechnungen über Base USDC und benötigt die mppx-Erweiterung zur Bindung an die Rechnung; andere Wallet-Clients ohne diese Erweiterung können diesen Endpunkt nicht bezahlen.

Behalte Authorization: Bearer für die Minds-Identität und sende MPP-Zugangsdaten in Payment-Authorization oder x402-Zugangsdaten in PAYMENT-SIGNATURE. Native MPP-Clients können hier Authorization: Payment zusammen mit dem Minds-Bearer in Minds-Authorization verwenden. Zahlungszugangsdaten gehören niemals in modelllesbare MCP-Argumente. Wiederhole eine ungewisse Zahlung nur mit ihren ursprünglichen Zugangsdaten; neue Zugangsdaten dürfen keine zweite Zahlung auslösen. Stripe-Bestätigung und signierter Webhook bestimmen die Bereitstellung.

Zahlungsangebote stehen in /openapi.json; dynamische Beträge werden in der 402-Antwort angegeben. /.well-known/acp.json beschreibt den gehosteten Checkout unter /api/acp, Version 2026-04-17. Erstelle eine ACP-Sitzung mit einem Stripe-Preis in line_items, seiner currency und capabilities: {}; billingCountry, Team-quantity und Abonnement-legalAcceptance gehören in metadata. Abruf, Aktualisierung, Abschluss und Abbruch nutzen /checkout_sessions/{id} sowie /complete oder /cancel. POST-Anfragen brauchen einen Idempotenzschlüssel. Aktualisierung und Abschluss akzeptieren leere Inhalte: Gib bei erforderlicher Käufereingabe continue_url zurück und melde den Abschluss erst nach Stripe-Bestätigung.

Die UCP-Erkennung ist unter /.well-known/ucp mit Version 2026-08-25 verfügbar; der REST-Checkout liegt unter /api/ucp und verwendet dieselben eigenen Stripe-Sitzungen wie MCP und die Abrechnungs-API. Veröffentliche ein kompatibles Plattformprofil und verwende einen Minds-OAuth-Client mit Metadatendokument auf derselben HTTPS-Origin. Persönliche API-Schlüssel können kein beliebiges Plattformprofil beanspruchen. Sende bei jeder Anfrage UCP-Agent: profile="https://your-platform.example/.well-known/ucp" und bei Schreibvorgängen einen Idempotency-Key. Die Payment-Handler sind leer, da der Käufer die Zahlung im Stripe-Checkout abschließt.

Webhook-Abonnements für Bereitschaft

Nutze denselben authentifizierten API-Schlüssel oder dieselbe OAuth-Verbindung wie für die Ressource. GET /api/v1/events liefert erlaubte Ereignisse und deren genaue Eingabe- und Nutzlastschemata. POST /api/v1/events/subscribe erstellt oder erneuert ein deterministisches Abonnement; POST /api/v1/events/unsubscribe beendet es anhand von Ereignis, Argumenten und Callback-URL, ohne die Forschung abzubrechen. Zielgruppenfilter benötigen operationId; Studienfilter studyId und runId. Die MCP-Methoden heißen events/list, events/subscribe und events/unsubscribe; server/discover entdeckt sie mit Protokoll 2026-07-28.

{
  "name": "study.run.finished",
  "arguments": {
    "studyId": "163bcb31-6ca7-4fef-91bd-9b963a9dd39f",
    "runId": "663bcb31-6ca7-4fef-91bd-9b963a9dd39f"
  },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example/mcp-events",
    "secret": "whsec_<base64-encoded-signing-key>"
  },
  "cursor": null
}

Der HTTPS-Callback muss die Challenge der signierten Verifizierungsanfrage zurückgeben. Anfragen verwenden die Standard-Webhooks-Header webhook-id, webhook-timestamp, webhook-signature und X-MCP-Subscription-Id. Der whsec_-Schlüssel muss 24–64 Bytes ergeben. Private Adressen, Weiterleitungen und Zugangsdaten in URLs sind ausgeschlossen. Fehler geben MCP -32015 mit Grund zurück und aktivieren kein Abonnement. HTTP 2xx bestätigt den Empfang; vorübergehende Fehler werden begrenzt mit exponentiellen Abständen und stabiler Ereignis-ID wiederholt, 410 und 413 beenden die Zustellung. Entferne doppelte Ereignis-IDs vor Folgeaktionen.

Antworten enthalten id, refreshBefore, cursor:null und truncated:false. ttlMs kann eine kürzere Laufzeit anfordern; fehlend oder null gewährt den endlichen Standard bis 86400000 ms. Gleicher Zugang, Callback, Ereignis und Argumente erneuern dieselbe ID. Beim Schlüsselwechsel wird kurz mit beiden Schlüsseln signiert. Ablauf oder Zugriffsverlust beendet die Zustellung. Nutzlasten enthalten weder Bearer-Zugangsdaten noch Forschungsantworten.

Antworten mit eigenem Budget aufladen

Geben Sie ein Budget in der Abrechnungswährung ein und sehen Sie vor dem Checkout ganze Antworten und den genauen Betrag zum selben Preis und Mindestbetrag wie beim kleinsten Paket. Gekaufte Antworten fließen in das bestehende Guthaben und lassen sich für ausdrücklich erlaubte automatische Aufladungen auswählen.

responseCredits.customTopUp.priceId → priceId; amountMinor = EUR/USD × 100.

Automatische Aufladungen verwalten

Der Katalog meldet den Standard-Workspace schon vor der ersten Zahlung als prepaid. Die enthaltene Nutzung ist null; ein bezahlter Antwortauftrag schreibt die gekauften Einheiten gut. Eine Kündigung wird in den Abrechnungseinstellungen bestätigt und zum Ende des bezahlten Zeitraums wirksam.

Lesen Sie vor einer automatischen Aufladung den aktuellen Abrechnungskatalog. Verwenden Sie kind: auto_recharge und den Basispreis aus responseCredits.customTopUp; Budget, Guthabenschwelle und Monatslimit werden als ganze Untereinheiten der Währung übermittelt. Ein Idempotency-Key im Checkout-Aufruf sorgt bei Wiederholungen für dieselbe Einwilligungssitzung. Die Antwort enthält eine Stripe-Einrichtungs-URL. Erst wenn der Abrechnungsverantwortliche diese Sitzung abschließt, werden automatische Aufladungen aktiv. Ein Währungswechsel kann bei noch reservierter automatischer Zahlung einen Konflikt auslösen.

{
  "kind": "auto_recharge",
  "priceId": "price_from_customTopUp",
  "amountMinor": 10000,
  "thresholdAmountMinor": 500,
  "monthlyAmountLimit": 19992
}

responseCredits.customTopUp.priceId → priceId; amountMinor, thresholdAmountMinor, monthlyAmountLimit = EUR/USD × 100; monthlyAmountLimit: "none".

POST /api/v1/billing/checkout + Idempotency-Key / start_billing_checkout + idempotencyKey → Stripe Checkout mode=setup.