# Neotask API-Referenz

Vollstaendige API-Referenz fuer die Neotask Plattform. Dieses Dokument behandelt jeden verfuegbaren Endpunkt, Authentifizierungsmethoden, Fehlerbehandlung und Ratenbegrenzungen.

---

## Authentifizierung

Alle API-Anfragen erfordern Authentifizierung ueber eine der folgenden Methoden:

- **Bearer JWT**: Uebergeben Sie den Header `Authorization: Bearer <token>`. Tokens werden ueber die unten beschriebenen Login-Endpunkte erhalten.
- **License HMAC**: Geraetegebundene HMAC-SHA256-Signierung, die von der Neotask Desktop-Anwendung verwendet wird. Der Client signiert Anfragen mit einem Geheimnis, das aus dem Lizenzschluessel und Geraetefingerabdruck abgeleitet wird.
- **Tenant Header**: Fuegen Sie `x-tenant-id: <tenantId>` fuer jeden Tenant-bezogenen Endpunkt hinzu. Dieser Header identifiziert, auf welchen Tenant (Arbeitsbereich) sich die Anfrage bezieht.

Viele Endpunkte kombinieren mehrere Authentifizierungsanforderungen. Zum Beispiel bedeutet "Tenant + Admin", dass die Anfrage sowohl ein gueltiges JWT (eines Benutzers mit der Admin-Rolle) als auch den `x-tenant-id`-Header enthalten muss.

---

## Auth-Endpunkte

Endpunkte fuer die Benutzerauthentifizierung ueber Web-, iOS- und Desktop-Plattformen.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/auth/login` | Mit E-Mail und Passwort authentifizieren. Gibt bei Erfolg ein JWT zurueck. | Keine |
| POST | `/api/auth/google` | Ueber Google OAuth im Web authentifizieren. Erwartet einen Google-Autorisierungscode. | Keine |
| POST | `/api/auth/google-ios` | Ueber Google OAuth auf iOS authentifizieren. Erwartet ein iOS-spezifisches Autorisierungs-Payload. | Keine |
| POST | `/api/auth/google-token` | Ein Google-Zugriffstoken verifizieren und ein Neotask JWT zurueckgeben. | Keine |
| POST | `/api/auth/apple` | Ueber Apple Sign-In authentifizieren. Erwartet ein Apple-Identitaetstoken. | Keine |
| GET | `/api/auth/me` | Das Profil des authentifizierten Benutzers zurueckgeben (Name, E-Mail, Avatar, Rollen). | JWT |
| DELETE | `/api/auth/account` | Das Konto des authentifizierten Benutzers und alle zugehoerigen Daten dauerhaft loeschen. | JWT |

---

## Dashboard-Auth-Endpunkte

Authentifizierungsendpunkte spezifisch fuer das Neotask Dashboard, einschliesslich Lizenzschluessel-Login und Zwei-Faktor-Authentifizierung (TOTP).

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/dashboard/auth/login` | Mit einem Lizenzschluessel authentifizieren. Gibt bei Erfolg ein JWT zurueck oder signalisiert, dass TOTP erforderlich ist. | Keine |
| POST | `/api/dashboard/auth/totp-login` | Login mit einem TOTP-Code oder Backup-Code abschliessen, wenn Zwei-Faktor-Authentifizierung aktiviert ist. | Keine |
| GET | `/api/dashboard/auth/me` | Die aktuellen Lizenzinformationen und Funktionsberechtigungen fuer den authentifizierten Dashboard-Benutzer zurueckgeben. | JWT |
| POST | `/api/dashboard/totp/setup` | Ein TOTP-Geheimnis und QR-Code fuer die Einrichtung der Zwei-Faktor-Authentifizierung generieren. | JWT |
| POST | `/api/dashboard/totp/verify` | Einen TOTP-Code verifizieren, um die Zwei-Faktor-Authentifizierung fuer das Konto zu bestaetigen und zu aktivieren. | JWT |

---

## Abrechnungsendpunkte

Abonnements, Checkout-Sitzungen und In-App-Kaeufe ueber Stripe und RevenueCat verwalten.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/billing/checkout` | Eine Stripe Checkout-Sitzung fuer den Pro-Tarif erstellen. Gibt eine Checkout-URL zurueck. | Tenant + Admin |
| POST | `/api/billing/checkout/enterprise` | Eine Stripe Checkout-Sitzung fuer den Enterprise-Tarif erstellen. Gibt eine Checkout-URL zurueck. | Tenant + Admin |
| GET | `/api/billing/status` | Den aktuellen Tarif, Nachrichtenanzahl und Nutzungslimits fuer den Tenant zurueckgeben. | Tenant + Viewer |
| POST | `/api/billing/portal` | Eine Stripe Kundenportal-Sitzung zur Verwaltung von Zahlungsmethoden und Rechnungen erstellen. | Tenant + Admin |
| POST | `/api/billing/agent-addon` | Ein zusaetzliches Agenten-Slot-Add-on fuer den Tenant erwerben. | Tenant + Admin |
| POST | `/api/billing/webhook` | Stripe Webhook-Handler. Validiert die Stripe-Signatur und verarbeitet Abonnement-Lebenszyklus-Ereignisse. | Stripe Signature |
| POST | `/api/billing/revenuecat-sync` | Einen iOS In-App-Kauf ueber RevenueCat verifizieren und Berechtigungen mit dem Tenant synchronisieren. | Tenant + Admin |
| POST | `/api/billing/revenuecat-webhook` | RevenueCat Webhook-Handler. Verarbeitet Abonnement-Ereignisse aus dem App Store. | Bearer |

---

## Chat-Endpunkte

Nachrichten senden und empfangen, Sitzungen verwalten und asynchrone Job-Ergebnisse abfragen.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/chat/init` | Automatisch einen Tenant, Agenten und eine Sitzung fuer den authentifizierten Benutzer bereitstellen. Verwenden Sie dies, um die Chat-Umgebung eines neuen Benutzers in einem einzigen Aufruf zu initialisieren. | JWT |
| POST | `/api/chat/send` | Eine Nachricht an den Agenten senden. Die Nachricht wird asynchron verarbeitet; eine Job-ID wird sofort zurueckgegeben. | Tenant + Admin |
| GET | `/api/chat/jobs/:jobId` | Den Status und das Ergebnis eines asynchronen Chat-Jobs anhand seiner ID abfragen. | Tenant + Viewer |
| GET | `/api/chat/messages` | Alle Nachrichten fuer eine bestimmte Sitzung abrufen. Uebergeben Sie die Sitzungs-ID als Abfrageparameter. | Tenant + Viewer |
| GET | `/api/chat/sessions` | Alle Chat-Sitzungen fuer den Tenant auflisten. | Tenant + Viewer |
| POST | `/api/chat/sessions` | Eine neue Chat-Sitzung erstellen. | Tenant + Admin |

---

## Agenten- und Aktivitaetsendpunkte

Agenten, Sitzungen, Tools, Dateien, Skills, Kanaele, geplante Aufgaben und Teams des Tenants durchsuchen.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| GET | `/api/activity/agents` | Alle Agenten des Tenants auflisten. | Tenant |
| GET | `/api/activity/sessions` | Sitzungen auflisten. Unterstuetzt Filterung nach `agentId`, `status` und Datumsbereich-Abfrageparametern. | Tenant |
| GET | `/api/activity/sessions/:id/entries` | Alle Eintraege (Nachrichten und Ereignisse) fuer eine bestimmte Sitzung abrufen. | Tenant |
| GET | `/api/activity/tools` | Alle fuer die Agenten des Tenants verfuegbaren Tools auflisten. | Tenant |
| GET | `/api/activity/files` | Alle mit den Agenten des Tenants verbundenen Dateien auflisten. | Tenant |
| GET | `/api/activity/skills` | Alle mit den Agenten des Tenants verbundenen Skills auflisten. | Tenant |
| GET | `/api/activity/channels` | Alle mit den Agenten des Tenants verbundenen Kanaele auflisten. | Tenant |
| GET | `/api/activity/cron-jobs` | Alle geplanten (Cron-)Aufgaben fuer den Tenant auflisten. | Tenant |
| GET | `/api/activity/teams` | Alle Teams innerhalb des Tenants auflisten. | Tenant |

---

## Skills-Endpunkte

Den Skill-Katalog verwalten, Skills installieren und konfigurieren sowie benutzerdefinierte Skills veroeffentlichen.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| GET | `/api/skills/catalog` | Den vollstaendigen Skill-Katalog durchsuchen. Gibt alle zur Installation verfuegbaren veroeffentlichten Skills zurueck. | Tenant |
| GET | `/api/skills/list` | Die aktuell vom Benutzer installierten Skills auflisten. | Tenant + Viewer |
| POST | `/api/skills/sync` | Skills aus dem Dateisystem synchronisieren. Verwenden Sie dies nach dem Bereitstellen neuer Skill-Dateien, um die Registry zu aktualisieren. | Tenant + Admin |
| POST | `/api/skills/register` | Einen Skill aus dem Katalog registrieren (installieren). | Tenant + Viewer |
| DELETE | `/api/skills/register/:skillId` | Einen Skill anhand seiner ID abmelden (deinstallieren). | Tenant + Viewer |
| POST | `/api/skills/:skillId/publish` | Einen Skill veroeffentlichen, um ihn im Katalog verfuegbar zu machen. | Tenant + Admin |
| POST | `/api/skills/:skillId/unpublish` | Einen Skill von der Veroeffentlichung zurueckziehen und aus dem Katalog entfernen. | Tenant + Admin |
| GET | `/api/skills/all` | Alle Skills einschliesslich unveroeffentlichter auflisten. Nur-Admin-Endpunkt fuer die Skill-Verwaltung. | Tenant + Admin |
| PUT | `/api/skills/:skillId/env-schema` | Das Umgebungsvariablen-Schema fuer einen Skill definieren oder aktualisieren. Dies steuert, welche Konfigurationsfelder den Benutzern angezeigt werden. | Tenant + Admin |
| POST | `/api/skills/:skillId/configure` | Konfigurationswerte fuer einen installierten Skill speichern. | Tenant + Viewer |
| DELETE | `/api/skills/:skillId/configure` | Alle Konfiguration fuer einen Skill entfernen und auf Standards zuruecksetzen. | Tenant + Viewer |

---

## Kanal-Endpunkte

Messaging-Kanaele verknuepfen, konfigurieren, aktivieren und trennen (z.B. Slack, Discord, WhatsApp).

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| GET | `/api/channels/` | Alle Kanaele und ihre aktuellen Status auflisten. | Tenant + Viewer |
| GET | `/api/channels/:channel/status` | Den detaillierten Status eines bestimmten Kanals abrufen. | Tenant + Viewer |
| POST | `/api/channels/:channel/link` | Den Verknuepfungsprozess fuer einen Kanal starten. Gibt je nach Kanaltyp eine Verknuepfungs-URL oder ein Sitzungstoken zurueck. | Tenant + Admin |
| GET | `/api/channels/:channel/link/wait` | Auf den Abschluss eines Kanalverknuepfungs-Flows warten (Long-Polling). Gibt zurueck, sobald der Kanal erfolgreich verknuepft ist oder die Operation ablaeuft. | Tenant + Admin |
| GET | `/api/channels/:channel/jobs/:jobId` | Das Ergebnis eines kanalspezifischen asynchronen Jobs abrufen. | Tenant + Admin |
| POST | `/api/channels/:channel/enable` | Einen verknuepften Kanal aktivieren, damit der Agent beginnt, Nachrichten davon zu empfangen. | Tenant + Admin |
| POST | `/api/channels/:channel/disable` | Einen Kanal deaktivieren, ohne ihn zu trennen. Der Agent empfaengt keine Nachrichten mehr, aber die Kanalverbindung bleibt erhalten. | Tenant + Admin |
| POST | `/api/channels/:channel/disconnect` | Einen Kanal vollstaendig trennen und die Verknuepfung aufheben. | Tenant + Admin |
| GET | `/api/channels/:channel/config` | Die aktuelle Konfiguration fuer einen Kanal abrufen. | Tenant + Admin |
| POST | `/api/channels/:channel/config` | Die Konfiguration fuer einen Kanal aktualisieren. | Tenant + Admin |

---

## Google OAuth-Endpunkte

Google OAuth-Flows fuer die Verbindung von Google-Diensten mit Neotask initiieren und verwalten.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| GET/POST | `/oauth/google/start` | Einen Google OAuth-Flow initiieren. Akzeptiert optionale Parameter zur Angabe, auf welche Google-Dienste Zugriff angefordert werden soll. | Optional |
| GET | `/oauth/google/services` | Alle von Neotask unterstuetzten Google-Dienstdefinitionen auflisten, nach Kategorie gruppiert. | Keine |
| GET | `/oauth/google/callback` | OAuth-Callback-Handler. Google leitet hierher weiter, nachdem der Benutzer den Zugriff gewaehrt oder verweigert hat. | Keine |
| GET | `/oauth/google/status` | Den Status eines laufenden OAuth-Flows abfragen. Gibt zurueck, ob der Flow ausstehend, abgeschlossen oder fehlgeschlagen ist. | Keine |

### Verfuegbare Google-Dienste

Neotask unterstuetzt die Verbindung mit 25 Google-Diensten, organisiert nach Kategorie:

| Kategorie | Dienste |
|----------|----------|
| **Kern** | Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Keep, Tasks |
| **Kommunikation** | People/Contacts, Chat, Meet, YouTube, Photos |
| **Standort** | Places API, Routes/Directions, Business Profile |
| **Spezialisiert** | Classroom, Play Developer, AdSense, Google Ads |

---

## Provider-Keys-Endpunkte

Drittanbieter-API-Schluessel verwalten (z.B. fuer LLM-Anbieter). Schluessel werden im Ruhezustand verschluesselt und koennen bei Bedarf entschluesselt werden.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| PUT | `/api/provider-keys/:provider` | Einen API-Schluessel fuer den angegebenen Anbieter speichern oder aktualisieren. Der Schluessel wird vor der Speicherung verschluesselt. | HMAC + Auth |
| GET | `/api/provider-keys/` | Alle gespeicherten Anbieterschluessel auflisten. Schluesselwerte sind maskiert (nur die letzten vier Zeichen werden angezeigt). | Auth |
| DELETE | `/api/provider-keys/:provider` | Einen gespeicherten API-Schluessel fuer den angegebenen Anbieter entfernen. | HMAC + Auth |
| GET | `/api/provider-keys/:provider/resolve` | Den vollstaendigen API-Schluessel fuer den angegebenen Anbieter entschluesseln und zurueckgeben. | Auth |
| GET | `/api/provider-keys/mode` | Den aktuellen Schluesselmodus (benutzerdefiniert vs. Plattform-Guthaben) und den verbleibenden Guthabenstand abrufen. | Auth |

### Erlaubte Anbieter

Der `:provider`-Pfadparameter muss einer der folgenden Werte sein:

- `anthropic`
- `openai`
- `openai-codex`
- `openrouter`
- `google-ai`

---

## Nutzungsendpunkte

Nutzung verfolgen, Analysen abfragen, Ausgaben ueberwachen und Budgets verwalten.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/usage/ingest` | Einen Nutzungsdatensatz aufnehmen (z.B. Token-Zaehler, verwendetes Modell). | Auth |
| GET | `/api/usage/query` | Nutzungsanalysen mit flexiblen Filtern abfragen (Datumsbereich, Modell, Agent). | Auth |
| GET | `/api/usage/summary` | Eine Nutzungszusammenfassung fuer einen bestimmten Zeitraum abrufen. Uebergeben Sie `period` als Abfrageparameter (z.B. `day`, `week`, `month`). | Auth |
| GET | `/api/usage/analytics` | Detaillierte Nutzungsanalysen einschliesslich Aufschluesselungen nach Modell und Agent abrufen. | Auth |
| GET | `/api/usage/spending` | Ausgabendaten fuer einen bestimmten Zeitraum abrufen. Uebergeben Sie `period` als Abfrageparameter. | Auth |
| GET | `/api/usage/budget` | Budgetinformationen einschliesslich Gesamtlimit, verbrauchtem Betrag und verbleibendem Betrag abrufen. | Auth |
| POST | `/api/usage/cron-runs` | Die Ausfuehrung einer geplanten (Cron-)Aufgabe fuer die Nutzungsverfolgung aufzeichnen. | Auth |
| POST | `/api/usage/budget-snapshot` | Einen Zeitpunkt-Snapshot des aktuellen Budgetstatus erfassen. | Auth |

---

## Onboarding-Endpunkte

Neue Benutzer durch die Ersteinrichtung fuehren, einschliesslich Auswahl eines Modellanbieters und Konfiguration eines API-Schluessels.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/onboarding/init` | Die Onboarding-Konfiguration fuer den authentifizierten Benutzer initialisieren. Erstellt Standardeinstellungen und gibt den Onboarding-Status zurueck. | JWT |
| GET | `/api/onboarding/models` | Verfuegbare Modellanbieter und ihre unterstuetzten Modelle auflisten. Dieser Endpunkt ist oeffentlich und erfordert keine Authentifizierung. | Keine |
| POST | `/api/onboarding/setup` | Einen Anbieter-API-Schluessel waehrend des Onboardings konfigurieren. Validiert den Schluessel vor dem Speichern. | Tenant + Admin |
| POST | `/api/onboarding/complete` | Das Onboarding fuer den aktuellen Benutzer als abgeschlossen markieren. | Dashboard Auth |

---

## Tenant-Endpunkte

Tenants (Arbeitsbereiche) erstellen und verwalten, verschluesselte Geheimnisse speichern sowie Sitzungen und Jobs direkt erstellen.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/tenants/` | Einen neuen Tenant (Arbeitsbereich) erstellen. Gibt die Tenant-ID und Standardeinstellungen zurueck. | JWT |
| GET | `/api/tenants/:tenantId` | Details fuer einen bestimmten Tenant abrufen, einschliesslich Einstellungen und Mitgliederanzahl. | JWT |
| POST | `/api/tenants/secrets` | Ein verschluesseltes Geheimnis speichern, das dem Tenant zugeordnet ist. Wird fuer Dienst-Integrationen verwendet. | Tenant + Admin |
| POST | `/api/tenants/sessions` | Eine neue Sitzung innerhalb des Tenants erstellen. | Tenant + Admin |
| POST | `/api/tenants/jobs` | Einen neuen asynchronen Job innerhalb des Tenants erstellen. | Tenant + Admin |

---

## Memory-Endpunkte

Agenten-Speicherkonfiguration, Dateien und Inhalte verwalten. Speicher ermoeglicht es Agenten, Informationen ueber Sitzungen hinweg beizubehalten.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| GET | `/api/memory/config` | Die aktuelle Speicherkonfiguration abrufen (Aktivierungsstatus, Aufbewahrungsrichtlinie, Limits). | Auth |
| POST | `/api/memory/config` | Speichereinstellungen wie Aufbewahrungszeitraum und Speicherlimits aktualisieren. | Auth |
| GET | `/api/memory/files` | Alle fuer den Agenten gespeicherten Speicherdateien auflisten. | Auth |
| GET | `/api/memory/files/:filename` | Den Inhalt einer bestimmten Speicherdatei anhand des Dateinamens abrufen. | Auth |
| DELETE | `/api/memory/files/:filename` | Eine bestimmte Speicherdatei anhand des Dateinamens loeschen. | Auth |
| GET | `/api/memory/content` | Gespeicherten Speicherinhalt abrufen. | Auth |
| POST | `/api/memory/content` | Neuen Speicherinhalt fuer den Agenten speichern. | Auth |

---

## Google-Konten-Endpunkte

Ueber OAuth mit Neotask verbundene Google-Konten verwalten.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| GET | `/api/google-accounts/` | Alle verbundenen Google-Konten mit ihren Dienst-Scopes und Status auflisten. | Auth |
| POST | `/api/google-accounts/:accountId/activate` | Ein verbundenes Google-Konto aktivieren, damit der Agent seine autorisierten Dienste nutzen kann. | Auth |
| DELETE | `/api/google-accounts/:accountId` | Ein verbundenes Google-Konto entfernen und seine gespeicherten Tokens widerrufen. | Auth |

---

## Kontakt- und Support-Endpunkte

Support-Kontaktanfragen einreichen und verwalten.

| Methode | Endpunkt | Beschreibung | Auth |
|--------|----------|-------------|------|
| POST | `/api/contact/` | Eine Kontaktformular-Nachricht einreichen. Auf 5 Anfragen pro 15 Minuten pro IP-Adresse begrenzt. | Keine |
| GET | `/api/contacts/` | Alle Kontaktanfragen mit Paginierung auflisten. Nur Admin. | Admin |
| PATCH | `/api/contacts/:id` | Den Status einer Kontaktanfrage aktualisieren (z.B. als geloest markieren). | Admin |
| DELETE | `/api/contacts/:id` | Eine Kontaktanfrage loeschen. | Admin |

---

## Ratenbegrenzungen

Neotask erzwingt Ratenbegrenzungen auf bestimmten Endpunkten zum Schutz der Dienststabilitaet. Wenn eine Ratenbegrenzung ueberschritten wird, gibt die API eine `429 Too Many Requests`-Antwort zurueck.

| Endpunkt-Kategorie | Limit |
|-------------------|-------|
| Kontaktformular | 5 Anfragen pro 15 Minuten pro IP |
| Anmeldeversuche | 10 Anfragen pro 15 Minuten pro IP |
| Tracking/Analysen | 30 Anfragen pro 60 Sekunden pro IP |

---

## Fehlerantworten

Alle Fehlerantworten folgen einem einheitlichen JSON-Format:

```json
{
  "error": "Fehlermeldungsbeschreibung",
  "status": 400
}
```

### Statuscodes

| Code | Bedeutung |
|------|---------|
| 400 | **Bad Request** -- Die Anfrage war fehlerhaft oder enthielt ungueltige Parameter. |
| 401 | **Unauthorized** -- Authentifizierung fehlt oder das bereitgestellte Token ist ungueltig. |
| 402 | **Payment Required** -- Das Guthaben des Tenants ist aufgebraucht. Upgraden Sie Ihren Tarif oder fuegen Sie Guthaben hinzu, um fortzufahren. |
| 403 | **Forbidden** -- Der authentifizierte Benutzer hat nicht ausreichende Berechtigungen fuer diese Aktion. |
| 404 | **Not Found** -- Die angeforderte Ressource existiert nicht. |
| 429 | **Rate Limited** -- Zu viele Anfragen. Warten Sie und versuchen Sie es nach dem in den Antwort-Headern angegebenen Zeitraum erneut. |
| 500 | **Internal Server Error** -- Ein unerwarteter Fehler ist auf dem Server aufgetreten. Wenn dies anhalt, kontaktieren Sie den Neotask Support. |