Aufgaben API

Aufgabenarbeitsbereich

Aufgaben erstellen, Arbeit filtern und wiederverwendbare Aufgabenbezeichnungen verwalten

Diese Routen bilden die Grundlage des PrimeCal-Aufgabenarbeitsbereichs. Sie beziehen sich alle auf den authentifizierten Benutzer und umfassen Aufgaben-CRUD, Etikettenverwaltung, die Focus-Ansicht, automatische Terminplanung, Delegation und Abhängigkeiten.

JWT oder Benutzer API SchlüsselPaginierung und FilterungInline-EtikettenAutomatische TerminplanungDelegation und Abhängigkeiten

Quelle

Aufgabencontroller: backend-nestjs/src/tasks/tasks.controller.ts
Aufgabenbeschriftungscontroller: backend-nestjs/src/tasks/task-labels.controller.ts
DTOs: backend-nestjs/src/tasks/dto/create-task.dto.ts, backend-nestjs/src/tasks/dto/query-tasks.dto.ts, backend-nestjs/src/tasks/dto/create-task-label.dto.ts, backend-nestjs/src/tasks/dto/update-task-labels.dto.ts
Aufzählungen: backend-nestjs/src/entities/task.entity.ts

Authentifizierung und Berechtigungen

Alle Routen auf dieser Seite erfordern eine Authentifizierung.
Der Aufgaben- und Labelbesitz ist auf den aktuellen Benutzer beschränkt.
Aufgabenbezeichnungsrouten sind sowohl unter /api/tasks/labels als auch unter der Vorgängerversion /api/task-labels verfügbar.

Endpunktreferenz

Aufgaben

Methode	Pfad	Zweck	Anfrage oder Anfrage	Auth	Quelle
`POST`	`/api/tasks`	Erstellen Sie eine Aufgabe.	Text: Aufgabenfelder	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`GET`	`/api/tasks`	Listen Sie Aufgaben mit Filtern auf.	Abfrage: `status,priority,search,dueFrom,dueTo,labelIds,sortBy,sortDirection,page,limit`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`GET`	`/api/tasks/focus`	Die für heute instanziierten Routine- und fälligen Aufgaben, nach Zeitplan sortiert, ohne Aufgaben, die durch eine unerledigte Abhängigkeit blockiert sind.	Abfrage: `date` (optional, `YYYY-MM-DD`, Standard: heute UTC)	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`GET`	`/api/tasks/:id`	Holen Sie sich eine Aufgabe.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`PATCH`	`/api/tasks/:id`	Aktualisieren Sie eine Aufgabe.	Pfad: `id`, Text: Teilaufgabenfelder	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`DELETE`	`/api/tasks/:id`	Eine Aufgabe löschen.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`POST`	`/api/tasks/:id/auto-schedule`	Findet die nächste freie Kalenderlücke der Aufgabe (anhand von Dauer, Priorität, Kontext und bevorzugtem Zeitfenster) und setzt deren Fälligkeitsdatum/-uhrzeit auf diese Lücke.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`PATCH`	`/api/tasks/:id/auto-schedule/enable`	Aktiviert die automatische Terminplanung für eine Aufgabe.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`PATCH`	`/api/tasks/:id/auto-schedule/disable`	Deaktiviert die automatische Terminplanung für eine Aufgabe.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`POST`	`/api/tasks/:id/labels`	Ersetzen oder erweitern Sie Aufgabenbezeichnungen.	Pfad: `id`, Text: `labelIds,inlineLabels`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`DELETE`	`/api/tasks/:id/labels/:labelId`	Entfernen Sie ein Etikett von einer Aufgabe.	Pfad: `id,labelId`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`POST`	`/api/tasks/:id/accept-assignment`	Nimmt eine an Sie delegierte Aufgabe an. Nur die aktuell zugewiesene Person darf annehmen.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`POST`	`/api/tasks/:id/bounce-assignment`	Gibt eine delegierte Aufgabe zurück auf „nicht zugewiesen". Nur die aktuell zugewiesene Person darf sie zurückgeben.	Pfad: `id`, Text: `reason` (optional)	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`POST`	`/api/tasks/:id/dependencies`	Markiert diese Aufgabe als abhängig von einer anderen eigenen Aufgabe.	Pfad: `id`, Text: `dependsOnTaskId`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`DELETE`	`/api/tasks/:id/dependencies/:dependsOnTaskId`	Entfernt eine Abhängigkeitsverknüpfung.	Pfad: `id,dependsOnTaskId`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`

Aufgaben-Checklisteneinträge

Teilschritte innerhalb einer einzelnen Aufgabe – zu unterscheiden von Aufgabenabhängigkeiten (die zwei getrennte Aufgaben verknüpfen) und von Routine-Vorlagen (die wiederkehrende Aufgaben definieren). Verwenden Sie dies für eine einmalige Aufgabe mit eigenen Schritten, z. B. „Geburtstagsparty planen" → „Location buchen", „Kuchen bestellen", „Einladungen verschicken".

Methode	Pfad	Zweck	Anfrage oder Anfrage	Auth	Quelle
`GET`	`/api/tasks/:id/checklist-items`	Listet die Checklisteneinträge einer Aufgabe, sortiert, auf.	Pfad: `id`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`POST`	`/api/tasks/:id/checklist-items`	Fügt einen Checklisteneintrag hinzu. Gibt die vollständige aktualisierte Checkliste zurück.	Pfad: `id`, Text: `title`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`PATCH`	`/api/tasks/:id/checklist-items/:itemId`	Benennt einen Eintrag um, ordnet ihn neu an oder hakt ihn ab. Gibt die vollständige aktualisierte Checkliste zurück.	Pfad: `id,itemId`, Text: teilweise `title,isDone,order`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`
`DELETE`	`/api/tasks/:id/checklist-items/:itemId`	Löscht einen Checklisteneintrag. Gibt die vollständige aktualisierte Checkliste zurück.	Pfad: `id,itemId`	JWT oder Benutzer-API-Schlüssel	`tasks/tasks.controller.ts`

Aufgabenbeschriftungen

Methode	Pfad	Zweck	Anfrage oder Anfrage	Auth	Quelle
`GET`	`/api/tasks/labels`	Aufgabenbezeichnungen auflisten.	Keine	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`POST`	`/api/tasks/labels`	Erstellen Sie eine Aufgabenbezeichnung.	Körper: `name,color`	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`PATCH`	`/api/tasks/labels/:id`	Aktualisieren Sie eine Aufgabenbezeichnung.	Pfad: `id`, Text: Teilbeschriftungsfelder	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`DELETE`	`/api/tasks/labels/:id`	Löschen Sie eine Aufgabenbezeichnung.	Pfad: `id`	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`GET`	`/api/task-labels`	Legacy-Alias für die Label-Auflistung.	Keine	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`POST`	`/api/task-labels`	Legacy-Alias für die Etikettenerstellung.	Körper: `name,color`	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`PATCH`	`/api/task-labels/:id`	Legacy-Alias für die Etikettenaktualisierung.	Pfad: `id`	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`
`DELETE`	`/api/task-labels/:id`	Legacy-Alias zum Löschen von Labels.	Pfad: `id`	JWT oder Benutzerschlüssel API	`tasks/task-labels.controller.ts`

Fordern Sie Formen an

Aufgabennutzlast

CreateTaskDto in backend-nestjs/src/tasks/dto/create-task.dto.ts

title: erforderlich, maximal 240 Zeichen
body: optional, max. 8000 Zeichen
bodyFormat: optional, derzeit nur markdown
color: optionale 6-stellige Hexadezimalfarbe
priority: optionale Aufzählung high|medium|low
status: optionale Aufzählung todo|in_progress|done
place: optional, maximal 255 Zeichen
dueDate: optionale ISO-Datumszeichenfolge
dueEnd: optionale ISO-Datumszeichenfolge
dueTimezone: optional, maximal 100 Zeichen
assigneeId: optionale Ganzzahl
durationMinutes: optionale Ganzzahl, 1..1440 – auf der Aufgabe erforderlich, bevor sie automatisch geplant werden kann
autoScheduled: optionaler Boolean
preferredWindowStartHour / preferredWindowEndHour: optionale Ganzzahl, 0..23 – überschreibt das standardmäßige Suchfenster von 9–18 Uhr für die automatische Terminplanung dieser Aufgabe
context: optionale Aufzählung deep_work|errand|admin|kid_safe|low_energy – wird von der automatischen Terminplanung verwendet (deep_work bevorzugt eine großzügigere Lücke)
labelIds: optionales eindeutiges Ganzzahl-Array, maximal 12 Elemente

Entitätsstandardwerte von backend-nestjs/src/entities/task.entity.ts

bodyFormat: markdown
color: #eab308
priority: medium
status: todo

Delegations- und Abhängigkeits-Nutzlasten

BounceTaskAssignmentDto.reason: optionale Zeichenfolge, maximal 500 Zeichen – wird protokolliert, aber nicht in einer eigenen Audit-Tabelle gespeichert
AddTaskDependencyDto.dependsOnTaskId: erforderliche positive Ganzzahl

Checklisteneintrags-Nutzlasten

CreateTaskChecklistItemDto

title: erforderlich, maximal 240 Zeichen

UpdateTaskChecklistItemDto (alles optional)

title: maximal 240 Zeichen
isDone: Boolean
order: Ganzzahl – es gibt keinen eigenen Neuanordnungs-Endpunkt; setzen Sie order direkt auf den Einträgen, die Sie verschieben möchten

Die checklistItems einer Aufgabe sind nur bei GET /api/tasks/:id (dem Lesen einer einzelnen Aufgabe) enthalten, nicht in der paginierten Liste GET /api/tasks oder bei GET /api/tasks/focus – rufen Sie sie bei Bedarf für eine Listenansicht über die oben genannten dedizierten Endpunkte ab.

Focus-Abfrage

date: optionale Abfragezeichenfolge bei GET /api/tasks/focus, YYYY-MM-DD, Standard: heute (UTC)

Abfragefilter

QueryTasksDto

status: optionale Aufzählung todo|in_progress|done
priority: optionale Aufzählung high|medium|low
search: optionale Zeichenfolge, maximal 120 Zeichen
dueFrom: optionale ISO-Datumszeichenfolge
dueTo: optionale ISO-Datumszeichenfolge
labelIds: optionales eindeutiges Ganzzahl-Array, maximal 10 Elemente
sortBy: updatedAt|createdAt|dueDate
sortDirection: asc|desc
page: int >= 1, Standard 1
limit: int 1..100, Standard 25

Beschriften Sie Nutzlasten

CreateTaskLabelDto.name: erforderlich, maximal 64 Zeichen
CreateTaskLabelDto.color: optionale 6-stellige Hexadezimalfarbe
UpdateTaskLabelsDto.labelIds: optionale IDs vorhandener Labels
UpdateTaskLabelsDto.inlineLabels: optionale neue Labels zum Erstellen und Anhängen in einem Aufruf

Beispielanrufe

Erstellen Sie eine Aufgabe

curl -X POST "$PRIMECAL_API/api/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pack school bags",
    "priority": "high",
    "dueDate": "2026-03-30T18:00:00.000Z",
    "dueTimezone": "Europe/Budapest",
    "labelIds": [3, 7]
  }'

Aufgaben filtern

curl "$PRIMECAL_API/api/tasks?status=todo&sortBy=updatedAt&sortDirection=desc&limit=25" \
  -H "Authorization: Bearer $TOKEN"

Erstellen Sie ein Etikett

curl -X POST "$PRIMECAL_API/api/tasks/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "School",
    "color": "#14b8a6"
  }'

Holen Sie sich die heutige Focus-Liste

curl "$PRIMECAL_API/api/tasks/focus?date=2026-07-05" \
  -H "Authorization: Bearer $TOKEN"

Erstellen Sie eine Aufgabe mit Dauer und Kontext und planen Sie sie dann automatisch

curl -X POST "$PRIMECAL_API/api/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Write school newsletter",
    "durationMinutes": 90,
    "context": "deep_work"
  }'

curl -X POST "$PRIMECAL_API/api/tasks/57/auto-schedule" \
  -H "Authorization: Bearer $TOKEN"

Eine delegierte Aufgabe zurückgeben

curl -X POST "$PRIMECAL_API/api/tasks/58/bounce-assignment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Forgot which bin is recycling this week"
  }'

Eine Abhängigkeit hinzufügen

curl -X POST "$PRIMECAL_API/api/tasks/60/dependencies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dependsOnTaskId": 59
  }'

Einen Checklisteneintrag hinzufügen und abschließen

curl -X POST "$PRIMECAL_API/api/tasks/60/checklist-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Book the venue"
  }'

curl -X PATCH "$PRIMECAL_API/api/tasks/60/checklist-items/12" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isDone": true
  }'

Hinweise zu Reaktion und Verhalten

Aufgaben können über die Aufgaben-Kalender-Brücke mit gespiegelten Kalenderereignissen verknüpft werden, diese Verknüpfung wird jedoch in diesen DTOs nicht direkt konfiguriert.
POST /api/tasks/:id/labels unterstützt sowohl vorhandene Etiketten als auch die Inline-Etikettenerstellung.
Aufgabenbeschriftungsrouten werden aus Kompatibilitätsgründen absichtlich unter dem alten Pfad /api/task-labels dupliziert.
GET /api/tasks/focus schließt done-Aufgaben und jede Aufgabe mit einer unerledigten Abhängigkeit aus, sortiert nach Fälligkeitsdatum (null-Werte zuletzt), dann nach Routine-Eintragsreihenfolge, dann nach Erstellungszeit.
POST /api/tasks/:id/auto-schedule erfordert, dass durationMinutes für die Aufgabe gesetzt ist; andernfalls liefert es 400. Wird innerhalb des prioritätsbasierten Suchhorizonts keine freie Lücke gefunden, wird der Planungsstatus der Aufgabe auf unscheduled gesetzt, statt einen Fehler auszulösen.
POST /api/tasks/:id/accept-assignment und POST /api/tasks/:id/bounce-assignment liefern beide 403, wenn der Aufrufer nicht die aktuell zugewiesene Person der Aufgabe ist.
POST /api/tasks/:id/dependencies weist Selbstverweise und den direkten Zwei-Aufgaben-Zyklus (B hängt von A ab, während A bereits von B abhängt) mit 400 zurück. Längere Abhängigkeitsketten werden nicht geprüft.
Eine Änderung des status einer Aufgabe löst den Automatisierungs-Trigger task.status_changed für jede Regel aus, die darauf lauscht.
Alle Checklisteneintrags-Endpunkte geben die gesamte aktualisierte Checkliste der Aufgabe zurück (nicht nur den betroffenen Eintrag), sortiert nach order dann id – am einfachsten ersetzt ein Client damit einfach seine lokale Liste durch die Antwort.
Checklisteneinträge haben keine eigene Besitzer-Spalte; jeder Checklisten-Endpunkt prüft zunächst, ob der Aufrufer Eigentümer der übergeordneten Aufgabe ist, bevor er auf den Eintrag zugreift.

Best Practices

Verwenden Sie sortBy=updatedAt und einen kleinen limit für interaktive Aufgabenlisten.
Bevorzugen Sie labelIds beim Anhängen bekannter Labels und inlineLabels nur, wenn das Label wirklich noch nicht existiert.
Halten Sie dueTimezone explizit für Aufgaben, die über Zeitzonen hinweg gespiegelt oder interpretiert werden können.
Setzen Sie durationMinutes und, falls relevant, context, bevor Sie auto-schedule aufrufen – die automatische Terminplanung verschiebt nur dueDate/dueEnd, sie erstellt niemals die Aufgabe.
Behandeln Sie den reason von bounce-assignment als informellen Kontext für die Person, die die Aufgabe neu zuweist, nicht als dauerhaft gespeicherten Audit-Trail.
Behandeln Sie /api/tasks/labels als kanonischen Labelpfad und /api/task-labels als Kompatibilitätsroute.

Aufgaben erstellen, Arbeit filtern und wiederverwendbare Aufgabenbezeichnungen verwalten

Quelle​

Authentifizierung und Berechtigungen​

Endpunktreferenz​

Aufgaben​

Aufgaben-Checklisteneinträge​

Aufgabenbeschriftungen​

Fordern Sie Formen an​

Aufgabennutzlast​

Delegations- und Abhängigkeits-Nutzlasten​

Checklisteneintrags-Nutzlasten​

Focus-Abfrage​

Abfragefilter​

Beschriften Sie Nutzlasten​

Beispielanrufe​

Erstellen Sie eine Aufgabe​

Aufgaben filtern​

Erstellen Sie ein Etikett​

Holen Sie sich die heutige Focus-Liste​

Erstellen Sie eine Aufgabe mit Dauer und Kontext und planen Sie sie dann automatisch​

Eine delegierte Aufgabe zurückgeben​

Eine Abhängigkeit hinzufügen​

Einen Checklisteneintrag hinzufügen und abschließen​

Hinweise zu Reaktion und Verhalten​

Best Practices​