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.

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

Für neue Abonnements und Antwortguthaben gelten die bestehenden Stripe-Preise. Rufe vor einem Kaufvorschlag den authentifizierten Katalog ab; Berechtigung, Kontozuordnung, Testzeiträume, Steuern und Rabatte folgen denselben Abrechnungsdiensten wie die Minds-App. Hole die Zustimmung des Käufers und für Abonnements die ausdrückliche Bestätigung der AGB und des Widerrufshinweises ein.

Starte den Checkout mit einem stabilen Idempotency-Key aus 1–128 Buchstaben, Ziffern, Unterstrichen oder Bindestrichen. Verwende nach einem Timeout denselben Schlüssel und Inhalt; ein anderer Kauf unter demselben Schlüssel wird abgelehnt. Die Antwort enthält data.url und data.checkoutSessionId. Gib die URL unverändert an den Käufer weiter. Eine Checkout-URL bestätigt keine Zahlung; Änderungen bestehender Abonnements erfolgen in den Minds-Abrechnungseinstellungen.

{
  "kind": "subscription",
  "priceId": "price_from_catalog",
  "planType": "premium",
  "billingCountry": "DE",
  "legalAcceptance": { "termsAccepted": true, "withdrawalConsent": true }
}

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.