---
title: "Minds API"
description: "Erstellen und verwalten Sie KI-Minds programmatisch mit individuellen Konfigurationen und Persönlichkeiten."
---

# Minds API

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

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

## Mind abrufen

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

**Endpoint:** `GET /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}
```

### Response-Felder

<table>
<thead>
  <tr>
    <th>
      Feld
    </th>
    
    <th>
      Typ
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Eindeutige Mind-Kennung
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind-Name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind-Beschreibung
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
       oder <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Fachgebiet
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Vollständiger System Prompt, der das Verhalten des Minds definiert
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Tags zur Kategorisierung
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Ob der Mind öffentlich zugänglich ist
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLinkSharingEnabled
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Ob Link Sharing aktiviert ist
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicShareId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Share-ID für öffentlichen Zugriff (null, wenn nicht geteilt)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      URL des Avatarbildes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phoneNumber
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Zugehörige Telefonnummer (null, wenn keine)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clonedVoiceStatus
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Status des Voice-Clonings (null, wenn nicht geklont)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profitSplitOptIn
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Ob Profit-Split aktiviert ist
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        knowledgeItemCount
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Anzahl der angehängten Knowledge-Einträge
    </td>
  </tr>
</tbody>
</table>

### Beispiel-Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Error Responses

**400 Bad Request** - Ungültiges Mind-ID-Format

**401 Unauthorized** - Ungültiger oder fehlender API key

**403 Forbidden** - Kein Zugriff auf diesen Mind

**404 Not Found** - Mind existiert nicht

---

## Minds auflisten

Ruft alle Minds des authentifizierten Nutzers ab.

**Endpoint:** `GET /api/v1/minds`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Query-Parameter

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Typ
    </th>
    
    <th>
      Standard
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Filtert Minds nach Name, Beschreibung oder Discipline (case-insensitive)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      100
    </td>
    
    <td>
      Maximale Anzahl zurückgegebener Minds (1–100)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      0
    </td>
    
    <td>
      Anzahl der zu überspringenden Minds für Pagination
    </td>
  </tr>
</tbody>
</table>

### Response

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}
```

### Response-Felder

<table>
<thead>
  <tr>
    <th>
      Feld
    </th>
    
    <th>
      Typ
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Array von Mind-Objekten
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Gesamtzahl der Minds, die zur Anfrage passen
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Maximale Ergebnisse pro Seite
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Anzahl der übersprungenen Ergebnisse
    </td>
  </tr>
</tbody>
</table>

### Beispiel-Request

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

## Mind erstellen

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

**Endpoint:** `POST /api/v1/minds`

Für sichere Wiederholungen kannst du den optionalen Header `X-Minds-Idempotency-Key` (1–128 Zeichen) senden. Verwende nach einem Timeout denselben Schlüssel und Request-Body. Schlüssel gelten pro authentifiziertem Eigentümer. Solange der ursprüngliche Mind existiert, gibt derselbe Schlüssel diesen Mind mit HTTP `200` zurück, auch bei späteren Wiederholungen; er aktualisiert ihn nicht. Verwende für eine neue Erstellung einen neuen Schlüssel (HTTP `201`). Schlüssel mit mehr als 128 Zeichen werden mit `400` abgelehnt und nicht gekürzt.

In verwalteten Workspaces gelten die aktuellen Erstellungsberechtigungen für jede Anfrage, auch für Wiederholungen. Neu erstellte Minds gehören zu diesem Workspace. Ein Wiederholungsschlüssel kann keinen Mind aus einem anderen verwalteten Workspace zurückgeben; diese Anfrage liefert `404`. Bei deaktivierter Erstellung oder einem inaktiven Workspace wird vor der Erstellung `403` zurückgegeben.

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

```json
{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}
```

### Parameter

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Typ
    </th>
    
    <th>
      Erforderlich
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Ja
      </strong>
    </td>
    
    <td>
      Name des Minds (2–100 Zeichen)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Ja
      </strong>
    </td>
    
    <td>
      Das Fachgebiet des Minds (z. B. "Marketing", "Engineering")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mode
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Trainingsmodus: <code>
        keywords
      </code>
      
      , <code>
        clone
      </code>
      
      , <code>
        link
      </code>
      
       oder <code>
        manual
      </code>
      
      . Standard: <code>
        keywords
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Mind-Typ: <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
       oder <code>
        user
      </code>
      
      . Standard: <code>
        creative
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Beschreibung des Zwecks des Minds
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Bedingt
    </td>
    
    <td>
      Array von Keywords (erforderlich, wenn <code>
        mode
      </code>
      
       = <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        personaContext
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Bedingt
    </td>
    
    <td>
      Name/Kontext der zu emulierenden Person (erforderlich, wenn <code>
        mode
      </code>
      
       = <code>
        clone
      </code>
      
      ; wird auch zur automatischen Keyword-Ableitung verwendet)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contextLink
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Bedingt
    </td>
    
    <td>
      URL zu Profil/Inhalt (erforderlich, wenn <code>
        mode
      </code>
      
       = <code>
        link
      </code>
      
      ; der Server scrapt sie, um Keywords abzuleiten)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Array von Tags zur Kategorisierung (max. 20 Tags)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Externe URL zum Avatarbild (wird heruntergeladen und gespeichert)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Wenn <code>
        true
      </code>
      
      , wird im Hintergrund eine KI-generierte Profilbild-Generierung angestoßen
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cloneVoice
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Wenn <code>
        true
      </code>
      
      , wird Voice Cloning per YouTube-Suche ausgelöst (experimentell)
    </td>
  </tr>
</tbody>
</table>

### Werte für `mode`

Der Parameter `mode` bestimmt, wie Ihr Mind trainiert wird:

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

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

### Werte für `type`

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

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}
```

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

### Beispiel: Mind im Keywords-Modus erstellen

```bash
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": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'
```

### Beispiel: Mind im Clone-Modus erstellen

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'
```

### Beispiel: Mind im Link-Modus erstellen

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'
```

### Beispiel: Mind im Manual-Modus erstellen

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'
```

## Mind-Trainingszyklus

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

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

```bash
curl "https://getminds.ai/api/v1/minds/{mindId}/training" \
  -H "Authorization: Bearer minds_your_api_key"
```

```json
{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}
```

### Statuswerte

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Bedeutung
    </th>
    
    <th>
      <code>
        readyToChat
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        queued
      </code>
    </td>
    
    <td>
      Das Training ist in der Warteschlange, aber noch nicht gestartet.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        running
      </code>
    </td>
    
    <td>
      Der Mind sammelt aktiv Wissen und baut seine Persona auf.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        completed
      </code>
    </td>
    
    <td>
      Das Training ist abgeschlossen. Der Mind ist bereit zum Chatten.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        failed
      </code>
    </td>
    
    <td>
      Das Training wurde nicht abgeschlossen. Prüfen Sie <code>
        error
      </code>
      
       und trainieren Sie neu, falls es wiederholbar ist.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

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

### Wenn das Training fehlschlägt

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

<table>
<thead>
  <tr>
    <th>
      Fehlercode
    </th>
    
    <th>
      Bedeutung
    </th>
    
    <th>
      <code>
        retryable
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        COLLECTION_FAILED
      </code>
    </td>
    
    <td>
      Die Wissenssammlung konnte nicht abgeschlossen werden.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROFILE_GEN_FAILED
      </code>
    </td>
    
    <td>
      Das Persona-Profil konnte nicht generiert werden.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMEOUT
      </code>
    </td>
    
    <td>
      Das Training hat sein Zeitbudget überschritten und wurde gestoppt.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INTERNAL
      </code>
    </td>
    
    <td>
      Ein unerwarteter interner Fehler ist aufgetreten.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

### Neutraining

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

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"
```

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

## Profilbilder

Wenn Sie eine `profileImageUrl` angeben:

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

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

Externe Downloads benötigen eine öffentliche HTTP(S)-URL zu einem Rasterbild. Ziele in privaten Netzwerken, auch bei Weiterleitungen, sowie SVG-Inhalte werden abgelehnt. Downloads sind auf 50 MiB und 30 Sekunden begrenzt. Schlägt das Herunterladen oder Speichern fehl, wird der Mind trotzdem mit der ursprünglichen URL erstellt; eine zurückgegebene URL bestätigt nicht, dass das Bild gespeichert wurde.

## So funktioniert das Training

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

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

Sie können Ihren Mind weiter optimieren, indem Sie nach der Erstellung [Wissen hochladen](/docs/api/knowledge).

## Plan-Limits

Die aktuellen öffentlichen Standardwerte finden Sie in der generierten [Plan-Limit-Tabelle](/docs/api/overview). Vertragliche Overrides können abweichen; Integrationen sollten deshalb `data.limit` und `data.current` aus einer authentifizierten `PLAN_LIMIT`-Antwort verwenden. Der Starter-Plan wird in API-Payloads als `"premium"` ausgegeben.

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

```json
{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "minds",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}
```

## Error Responses

### 400 Bad Request

Fehlende oder ungültige Parameter.

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

### 401 Unauthorized

Ungültiger oder fehlender API key.

### 403 Forbidden

Plan-Limit erreicht.

### 500 Internal Server Error

Serverseitiger Fehler (selten).

## Mind aktualisieren

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

**Endpoint:** `PUT /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

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

### Parameter

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Typ
    </th>
    
    <th>
      Erforderlich
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Name des Minds (2–100 Zeichen)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Beschreibung des Zwecks des Minds
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Typ: <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
       oder <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Das Fachgebiet des Minds
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Individueller System Prompt, der Verhalten und Persönlichkeit des Minds definiert
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Array von Tags zur Kategorisierung (max. 20 Tags)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Nein
    </td>
    
    <td>
      Ob der Mind öffentlich zugänglich ist
    </td>
  </tr>
</tbody>
</table>

### System Prompt

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

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

**Beispiel-System-Prompts:**

```text
# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.
```

```text
# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.
```

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}
```

### Beispiel: System Prompt aktualisieren

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'
```

### Beispiel: Mehrere Felder aktualisieren

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'
```

### Error Responses

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

**401 Unauthorized** - Ungültiger oder fehlender API key

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

**404 Not Found** - Mind existiert nicht

## Mind-Knowledge-Patterns abrufen

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

**Endpoint:** `GET /api/v1/minds/{mindId}/knowledge/patterns`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response-Struktur

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

```json
{
  "success": true,
  "data": {
    "mindId": "550e8400-e29b-41d4-a716-446655440000",
    "mindName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "mind": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "mind": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### Verständnis der Response

- **frameworks**: Array von Frameworks, die die Patterns des Minds enthalten

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

### Beispiel-Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Anwendungsfälle

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

### Error Responses

**401 Unauthorized** - Ungültiger oder fehlender API key

**403 Forbidden** - Kein Zugriff auf diesen Mind

**404 Not Found** - Mind existiert nicht

## System Prompt neu generieren

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

**Endpoint:** `POST /api/v1/minds/{mindId}/regenerate-prompt`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Funktionsweise

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

Für Minds vom Typ **user**:

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

Für Minds vom Typ **expert**:

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

Für Minds vom Typ **creative**:

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

### Response

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

### Beispiel-Request

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Anwendungsfälle

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

### Error Responses

**401 Unauthorized** - Ungültiger oder fehlender API key

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

**404 Not Found** - Mind existiert nicht

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

## Mind löschen

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

**Endpoint:** `DELETE /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

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

### Beispiel-Request

```bash
curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Was wird gelöscht

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

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

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

### Error Responses

**400 Bad Request** - Ungültiges Mind-ID-Format

**401 Unauthorized** - Ungültiger oder fehlender API key

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

**404 Not Found** - Mind existiert nicht

## Nächste Schritte

- [Wissen für Ihren Mind hochladen](/docs/api/knowledge)
- [Mit Ihrem Mind chatten](/docs/api/chat)
- Mehr über [Errors und Limits](/docs/api/errors) erfahren