🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowTasks API - für moderne Projektmanagement-Tools

Eine vollständige REST API für FlowTasks mit Boards, Listen und Kommentaren. Perfekt für Projektmanagement-Tools, Aufgaben-Tracker und Automatisierungen.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards
IDs als Strings senden
Die Felder list_id, board_id, assigned_to, list_uuid und user_uuid werden serverseitig als String validiert. Senden Sie IDs deshalb immer als UUID-String oder als numerischen String (z. B. "123") - ein roher JSON-Integer (123 ohne Anführungszeichen) scheitert an der Validierung.

1. API-Zugangsdaten abrufen

Bevor Sie die Todo-API nutzen können, benötigen Sie Ihre persönlichen Zugangsdaten: Melden Sie sich an, navigieren Sie zu Profil → API-Zugang und kopieren Sie Ihren persönlichen API-Key (pk_...).

2. Typischer Workflow

Um ein Todo in einem Board zu erstellen, folgen Sie diesen Schritten: 1. Boards abrufen (GET /api/todos/boards - liefert die Boards inklusive verschachtelter Listen), 2. das gewünschte Board mit seinen Listen abrufen (GET /api/todos/boards/{uuid}), 3. Todo erstellen (POST /api/todos).

✅ Todo-Verwaltung

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards
Persönliche und Board-Todos
Lassen Sie list_id und board_id leer, um ein persönliches Todo zu erstellen. Geben Sie nur board_id an, um das Todo in der ersten Liste des Boards einzusortieren.

Todos auflisten

GET /api/todos

Ruft die Todos Ihres Teams cursor-paginiert ab. Ohne board_id werden nur Ihre eigenen persönlichen Todos zurückgegeben; mit board_id werden die Todos des Boards (optional weiter auf list_id eingegrenzt) zurückgegeben.

Query-Parameter:

type string Filter innerhalb der Ergebnismenge nach Typ: assigned (mir zugewiesen), completed (erledigt) oder created (von mir erstellt)
completed boolean Filter nach Status: true oder false
priority string Filter nach Priorität: low, medium, high
board_id string Board-UUID; grenzt die Ergebnisse auf Todos dieses Boards ein (erfordert Board-Zugriff)
list_id string Listen-UUID; nur in Kombination mit board_id, grenzt weiter auf eine Liste ein
cursor string Cursor aus dem meta-Objekt der vorherigen Antwort für die nächste/vorherige Seite
per_page integer Ergebnisse pro Seite, 1-100 (Default 50)
GET /api/todos/search

Durchsucht Titel und Beschreibung aller Todos, auf die Sie Zugriff haben (eigene persönliche Todos plus Todos aus Boards mit Ihrem Zugriff).

Query-Parameter:

search string * Suchbegriff (1-100 Zeichen). Zeichen wie % und _ werden literal gesucht, nicht als Platzhalter
cursor string Cursor aus dem meta-Objekt der vorherigen Antwort für die nächste/vorherige Seite
per_page integer Ergebnisse pro Seite, 1-100 (Default 50)

Todo abrufen

GET /api/todos/{todoUuid}

Ruft ein einzelnes Todo mit all seinen Details ab (inkl. Kommentare, Checklisten und Labels).

Todo erstellen

POST /api/todos

Erstellt ein neues Todo. Kann persönlich (ohne list_id/board_id) oder in einem Board erstellt werden.

Request Body:

title string * Titel des Todos (max. 255 Zeichen)
description string Beschreibung (max. 65.535 Zeichen)
due_date string Fälligkeitsdatum (ISO 8601)
priority string Priorität: low, medium, high
list_id string UUID der Ziel-Liste
board_id string UUID des Ziel-Boards (ohne list_id wird die erste Liste des Boards verwendet)
assigned_to string UUID des zugewiesenen Benutzers (wird ignoriert, wenn assigned_to_ids gesetzt ist)
assigned_to_ids array Array von Benutzer-UUIDs für Mehrfach-Zuweisung; hat Vorrang vor assigned_to
card_settings array Card-Darstellung; erlaubte Keys: color (max. 32 Zeichen), labels (max. 50 Strings)

Todo aktualisieren

PUT /api/todos/{todoUuid}

Aktualisiert ein bestehendes Todo. Alle Felder sind optional, nur gesendete Felder werden geändert. list_id:null ist nicht zulässig; zum expliziten Lösen vom Board dient der Detach-Endpoint. Validierungsfehler liefern HTTP 422 mit message und errors.

Request Body:

title string Titel (falls gesendet: required, max. 255 Zeichen)
description string Beschreibung (max. 65.535 Zeichen)
due_date string Fälligkeitsdatum
priority string Priorität: low, medium, high
list_id string UUID der neuen Ziel-Liste (verschiebt das Todo)
assigned_to string UUID des zugewiesenen Benutzers (wird ignoriert, wenn assigned_to_ids gesendet ist)
assigned_to_ids array Array von Benutzer-UUIDs; ersetzt die komplette Zuweisungsliste
completed boolean Als erledigt markieren
card_settings array Card-Darstellung; erlaubte Keys: color (max. 32 Zeichen), labels (max. 50 Strings)

Todo löschen

DELETE /api/todos/{todoUuid}

Löscht ein Todo unwiderruflich.

Todo duplizieren

POST /api/todos/{todoUuid}/duplicate

Erstellt eine Kopie eines Todos. Checklisten, Labels und Zuweisungen werden standardmäßig mitkopiert; über die Body-Parameter abschaltbar.

Request Body:

include_checklists boolean Checklisten mitkopieren (Default true)
include_labels boolean Labels mitkopieren (Default true)
include_assignments boolean Zugewiesene Benutzer mitkopieren (Default true)

Todo verschieben

PUT /api/todos/{todoUuid}/move

Verschiebt ein Todo in eine andere Board-Liste. Erfordert Zugriff auf das Board der Ziel-Liste.

Request Body:

list_uuid string * UUID der Ziel-Liste
sort_order integer Expliziter Sortier-Index in der Ziel-Liste (sonst automatisch ans Ende gesetzt)

Todo vom Board lösen

POST /api/todos/{todoUuid}/detach

Löst ein Board-Todo explizit und mit Audit-Log vom Board und überführt es in die persönliche Todo-Liste des Board-Owners. Nur der aktuelle Board-Owner darf diese Aktion ausführen; sichtbare Ressourcen mit unzureichender Rolle liefern HTTP 403, nicht zugängliche Ressourcen HTTP 404.

📋 Boards

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards
Rollenmodell: Owner, Admin, Member
Jedes Board hat genau einen Owner (der Ersteller, automatisch bei der Erstellung gesetzt) sowie beliebig viele Admin- und Member-Nutzer. Owner und Admin dürfen Mitglieder einladen/entfernen; nur der Owner darf das Board löschen, Rollen ändern oder die Ownership übertragen. Ein nicht berechtigter Aufruf liefert HTTP 403 mit {"success": false, "error": "You do not have permission to perform this action on this board."}.

Boards auflisten

GET /api/todos/boards

Ruft die Boards ab, auf die der authentifizierte Benutzer Zugriff hat (nicht alle Boards des Teams), inklusive verschachtelter Listen. Cursor-paginiert.

Query-Parameter:

cursor string Cursor aus dem meta-Objekt der vorherigen Antwort für die nächste/vorherige Seite
per_page integer Ergebnisse pro Seite, 1-100 (Default 50)

Board abrufen

GET /api/todos/boards/{uuid}

Ruft ein einzelnes Board mit dem vollständigen Baum ab: Listen -> Todos -> zugewiesene Benutzer + Labels, inklusive Statistiken (total_todos, completed_todos, progress_percentage) und der Liste der Benutzer mit Zugriff.

Board erstellen

POST /api/todos/boards

Erstellt ein neues Board. Der erstellende Benutzer wird automatisch als Owner eingetragen.

Request Body:

name string * Name des Boards (max. 255 Zeichen)
description string Beschreibung (max. 65.535 Zeichen)
background_settings array Hintergrund/Darstellung; erlaubte Keys: color (max. 32 Zeichen), image (max. 2.048 Zeichen)
project_id string UUID eines FlowCRM-Projekts, mit dem das Board verknüpft werden soll

Board aktualisieren

PUT /api/todos/boards/{uuid}

Aktualisiert Name, Beschreibung oder Hintergrund-Einstellungen eines Boards. Alle Felder sind optional, nur gesendete Felder werden geändert.

Request Body:

name string Name (falls gesendet: required, max. 255 Zeichen)
description string Beschreibung (max. 65.535 Zeichen)
background_settings array Hintergrund/Darstellung; erlaubte Keys: color (max. 32 Zeichen), image (max. 2.048 Zeichen)

Board löschen

DELETE /api/todos/boards/{uuid}

Löscht ein Board unwiderruflich, kaskadierend über Listen, Todos, Zugriffsrechte und externe Freigaben. Owner-exklusiv: nur der Owner des Boards darf löschen; Admin und Member erhalten HTTP 403 ("You do not have permission to perform this action on this board.").

Board archivieren/entarchivieren

PUT /api/todos/boards/{uuid}/archive

Schaltet den Archiv-Status eines Boards um (archiviert -> aktiv oder umgekehrt). Erfordert lediglich Board-Zugriff, kein Rollen-Gate.

Board-Mitglieder auflisten

GET /api/todos/boards/{uuid}/users

Ruft alle Benutzer mit Zugriff auf ein Board ab.

Board-Zugriff gewähren

POST /api/todos/boards/{uuid}/users

Gewährt einem Team-Mitglied Zugriff auf ein Board. Neue oder wiederhergestellte Grants liefern HTTP 201; ein bereits aktiver, idempotenter Grant liefert HTTP 200. Neue Grants erhalten immer die Rolle Member; Rollenänderungen erfolgen ausschließlich über den role-Endpoint. Nur Owner oder Admin dürfen Zugriff gewähren; Member erhalten HTTP 403.

Request Body:

user_uuid string * UUID des Team-Mitglieds, dem Zugriff gewährt werden soll

Board-Zugriff entziehen

DELETE /api/todos/boards/{uuid}/users/{userUuid}

Entzieht einem Benutzer den Zugriff auf ein Board. Nur Owner oder Admin dürfen den Zugriff eines ANDEREN Mitglieds entziehen (sonst HTTP 403 "You do not have permission to perform this action on this board."); jedes Mitglied darf jedoch seinen EIGENEN Zugriff entziehen (Selbst-Entfernung). Ausnahme: der Owner kann sich nicht selbst entfernen und muss die Ownership zuerst übertragen (HTTP 403 "The board Owner cannot remove their own access. Transfer ownership first."); ebenso kann der Owner niemals über diesen Endpoint durch andere entfernt werden.

Board-Rolle ändern / Ownership übertragen

PUT /api/todos/boards/{uuid}/users/{userUuid}/role

Owner-exklusive Aktion: nur der Owner des Boards darf Rollen ändern oder die Ownership übertragen - Admin und Member erhalten HTTP 403 ("You do not have permission to perform this action on this board."). role=admin oder role=member ändert die Rolle des Zielbenutzers ("User role updated successfully."). role=owner überträgt die Ownership atomar: der Zielbenutzer wird Owner, der bisherige Owner wird automatisch zu Admin herabgestuft ("Board ownership transferred successfully."). Fehlerfälle: HTTP 404 wenn Board oder Zielbenutzer nicht gefunden werden, HTTP 422 wenn der Zielbenutzer keinen aktiven Board-Zugriff hat, HTTP 422 wenn der Owner versucht sich selbst die Ownership zu übertragen ("You are already the Owner of this board."), HTTP 422 wenn versucht wird den Owner direkt via role=admin/member herabzustufen (stattdessen role=owner auf einen anderen Zielbenutzer nutzen, um die Ownership zu übertragen), sowie HTTP 409 wenn die Ownership-Übertragung durch eine gleichzeitige Änderung der Berechtigungen des aufrufenden Owners blockiert wurde ("Ownership changed concurrently. Please retry." - Retry empfohlen).

Request Body:

role string * Neue Rolle: admin, member oder owner (owner löst eine Ownership-Übertragung aus)

📑 Listen

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards

Liste erstellen

POST /api/todos/boards/{uuid}/lists

Erstellt eine neue Liste in einem Board. Erfordert Board-Zugriff.

Request Body:

name string * Name der Liste (max. 255 Zeichen)
list_settings array Listen-Darstellung; erlaubte Keys: color (max. 32 Zeichen), label (max. 255 Zeichen)

Liste abrufen

GET /api/todos/boards/{uuid}/lists/{listUuid}

Ruft eine einzelne Liste mit ihren Todos (inklusive zugewiesener Benutzer und Labels) ab. Dies ist der reale Endpoint zum Abrufen einer einzelnen Liste - es existiert kein Endpoint zum Auflisten aller Listen eines Boards separat vom Board selbst (dafür GET /api/todos/boards/{uuid}, das Board inklusive aller Listen liefert).

Liste aktualisieren

PUT /api/todos/boards/{uuid}/lists/{listUuid}

Aktualisiert Name oder list_settings einer Liste. Alle Felder sind optional, nur gesendete Felder werden geändert.

Request Body:

name string Name (falls gesendet: required, max. 255 Zeichen)
list_settings array Listen-Darstellung; erlaubte Keys: color (max. 32 Zeichen), label (max. 255 Zeichen)

Liste löschen

DELETE /api/todos/boards/{uuid}/lists/{listUuid}

Löscht eine Liste unwiderruflich; kaskadiert auf alle Todos der Liste.

Listen neu anordnen

PUT /api/todos/boards/{uuid}/lists/reorder

Ordnet alle Listen eines Boards atomar und kollisionsfrei anhand der übergebenen UUID-Reihenfolge neu an. Das Array muss jede Board-Liste genau einmal enthalten; fehlende oder fremde UUIDs liefern HTTP 422 mit skipped und verändern keine Sortierung.

Request Body:

list_uuids array * Array aller Listen-UUIDs des Boards in der gewünschten Reihenfolge

Liste archivieren/entarchivieren

PUT /api/todos/boards/{uuid}/lists/{listUuid}/archive

Schaltet den Archiv-Status einer Liste um (archiviert -> aktiv oder umgekehrt).

👥 Zuweisungen

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards

Zuweisungen auflisten

GET /api/todos/{todoUuid}/assignments

Ruft alle Benutzer ab, die einem Todo aktuell zugewiesen sind.

Benutzer zuweisen

POST /api/todos/{todoUuid}/assignments

Weist einem Todo einen weiteren Benutzer zu (additiv, bestehende Zuweisungen bleiben erhalten). Der Benutzer muss Mitglied des Teams sein.

Request Body:

user_uuid string * UUID des zuzuweisenden Team-Mitglieds

Zuweisung entfernen

DELETE /api/todos/{todoUuid}/assignments/{userUuid}

Entfernt die Zuweisung eines Benutzers von einem Todo.

💬 Kommentare

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards

Kommentare auflisten

GET /api/todos/{todoUuid}/comments

Ruft alle Kommentare eines Todos ab, chronologisch aufsteigend sortiert.

Kommentar hinzufügen

POST /api/todos/{todoUuid}/comments

Fügt einem Todo einen neuen Kommentar hinzu.

Request Body:

comment string * Kommentartext (max. 1000 Zeichen)

Kommentar bearbeiten

PUT /api/todos/{todoUuid}/comments/{commentUuid}

Bearbeitet einen Kommentar. Nur der ursprüngliche Autor darf seinen eigenen Kommentar bearbeiten - andernfalls antwortet die API mit HTTP 403 "You can only edit your own comments."

Request Body:

comment string * Neuer Kommentartext (max. 1000 Zeichen)

Kommentar löschen

DELETE /api/todos/{todoUuid}/comments/{commentUuid}

Löscht einen Kommentar unwiderruflich. Nur der ursprüngliche Autor darf seinen eigenen Kommentar löschen - andernfalls antwortet die API mit HTTP 403 "You can only delete your own comments."

🏷️ Labels

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards
Team-weite Labels
Labels gehören dem gesamten Team (nicht einem einzelnen Board oder Todo) und werden über POST /api/todos/labels angelegt. Ein Label wird erst über POST /api/todos/{todoUuid}/labels an einzelne Todos angehängt.

Labels auflisten

GET /api/todos/labels

Ruft alle Labels des Teams cursor-paginiert ab, sortiert nach sort_order.

Query-Parameter:

cursor string Cursor aus dem meta-Objekt der vorherigen Antwort für die nächste/vorherige Seite
per_page integer Ergebnisse pro Seite, 1-100 (Default 50)

Label erstellen

POST /api/todos/labels

Erstellt ein neues, team-weites Label.

Request Body:

name string * Name des Labels (max. 255 Zeichen)
color string * Farbe des Labels. Erlaubte Werte: zinc, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

Label aktualisieren

PUT /api/todos/labels/{labelUuid}

Aktualisiert Name oder Farbe eines Labels. Alle Felder sind optional, nur gesendete Felder werden geändert.

Request Body:

name string Name (falls gesendet: required, max. 255 Zeichen)
color string Farbe (falls gesendet: required). Erlaubte Werte: zinc, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

Label löschen

DELETE /api/todos/labels/{labelUuid}

Löscht ein Label (Soft-Delete). Ein Model-Boot-Event hängt das Label vorher von allen Todos ab.

Labels eines Todos auflisten

GET /api/todos/{todoUuid}/labels

Ruft alle Labels ab, die an ein bestimmtes Todo angehängt sind.

Labels an Todo anhängen

POST /api/todos/{todoUuid}/labels

Hängt ein oder mehrere Labels additiv an ein Todo an und liefert bei Erfolg HTTP 201. Wenn sich eine UUID nicht auf ein Team-Label auflösen lässt, antwortet der Endpoint mit HTTP 422 und skipped; es werden dann keine Labels angehängt.

Request Body:

label_uuids array * Array von Label-UUIDs (mindestens 1 Eintrag)

Label von Todo entfernen

DELETE /api/todos/{todoUuid}/labels/{labelUuid}

Entfernt ein einzelnes Label von einem Todo (das Label selbst bleibt für das Team bestehen).

☑️ Checklisten

Basis-URL: https://creativeskyline.de/api/todos https://creativeskyline.de/api/todos/boards

Checklisten auflisten

GET /api/todos/{todoUuid}/checklists

Ruft alle Checklisten eines Todos inklusive ihrer Items und Fortschritt (progress_percentage, total_items_count, completed_items_count) ab.

Checkliste erstellen

POST /api/todos/{todoUuid}/checklists

Erstellt eine neue Checkliste auf einem Todo.

Request Body:

name string * Name der Checkliste (max. 255 Zeichen)

Checkliste aktualisieren

PUT /api/todos/{todoUuid}/checklists/{checklistUuid}

Aktualisiert Name oder sort_order einer Checkliste. Alle Felder sind optional, nur gesendete Felder werden geändert.

Request Body:

name string Name (falls gesendet: required, max. 255 Zeichen)
sort_order integer Expliziter Sortier-Index

Checkliste löschen

DELETE /api/todos/{todoUuid}/checklists/{checklistUuid}

Löscht eine Checkliste unwiderruflich, inklusive aller ihrer Items.

Checklisten-Item erstellen

POST /api/todos/{todoUuid}/checklists/{checklistUuid}/items

Fügt einer Checkliste ein neues Item hinzu. Wird assigned_to gesendet, muss die UUID einem Team-Mitglied entsprechen - andernfalls antwortet die API mit HTTP 404 "Assigned user not found or not a team member."

Request Body:

content string * Text des Items (max. 500 Zeichen)
assigned_to string UUID des zugewiesenen Team-Mitglieds

Checklisten-Item aktualisieren

PUT /api/todos/{todoUuid}/checklists/{checklistUuid}/items/{itemUuid}

Aktualisiert Text oder Zuweisung eines Checklisten-Items. Alle Felder sind optional, nur gesendete Felder werden geändert; assigned_to=null entfernt eine bestehende Zuweisung.

Request Body:

content string Text (falls gesendet: required, max. 500 Zeichen)
assigned_to string UUID des zugewiesenen Team-Mitglieds, oder null um die Zuweisung zu entfernen

Checklisten-Item löschen

DELETE /api/todos/{todoUuid}/checklists/{checklistUuid}/items/{itemUuid}

Löscht ein Checklisten-Item unwiderruflich.

Checklisten-Item umschalten

PUT /api/todos/{todoUuid}/checklists/{checklistUuid}/items/{itemUuid}/toggle

Schaltet den Erledigt-Status eines Checklisten-Items um (nicht erledigt -> erledigt oder umgekehrt). Die Message unterscheidet sich je nach neuem Status: "Checklist item marked complete." bzw. "Checklist item marked incomplete."