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:

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:

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:

{
  "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.