API - Projekte Admin

📕 Für Administratoren und Entwickler.

Über die Public API können Projekte ausgelesen, erstellt, aktualisiert und gelöscht werden. Ausserdem lassen sich alle Aufgaben eines Projekts abrufen.

Basis-Pfad: /api/v1/projects

Referenzwerte

Projekt-Status-Werte

Status	Bedeutung
`PLANNED`	Geplant
`ACTIVE`	Aktiv
`COMPLETED`	Abgeschlossen
`ARCHIVED`	Archiviert

Projekt-Prioritäts-Werte

Priorität	Bedeutung
`LOW`	Niedrig
`NORMAL`	Normal
`HIGH`	Hoch
`CRITICAL`	Kritisch

Projekte auflisten

GET /api/v1/projects

Scope: projects:read

Query-Parameter:

Parameter	Typ	Pflicht	Beschreibung
`status`	String	Nein	Filtern nach Status (z.B. `ACTIVE`)
`search`	String	Nein	Volltextsuche in Titel und Beschreibung
`createdAfter`	String (ISO 8601)	Nein	Nur Projekte, die nach diesem Zeitpunkt erstellt wurden
`createdBefore`	String (ISO 8601)	Nein	Nur Projekte, die vor diesem Zeitpunkt erstellt wurden
`page`	Integer	Nein	Seite (Standard: `0`)
`size`	Integer	Nein	Einträge pro Seite, max. 100 (Standard: `20`)
`sort`	String	Nein	Sortierung (Standard: `createdAt,desc`). Erlaubte Felder: `createdAt`, `updatedAt`, `title`, `status`, `priority`

Antwort (200 OK):

{
  "data": [
    {
      "id": 5,
      "title": "Website-Relaunch ACME",
      "description": "Komplette Neugestaltung der Unternehmenswebseite für ACME GmbH.",
      "numberPrefix": "ACME",
      "color": "#3F51B5",
      "status": "ACTIVE",
      "priority": "HIGH",
      "startDate": "2025-01-01",
      "endDate": "2025-06-30",
      "progress": 32,
      "ownerId": 2,
      "assigneeId": 7,
      "teamMemberIds": [7, 8, 9],
      "customerName": "ACME GmbH",
      "createdAt": "2024-12-15T09:00:00Z",
      "updatedAt": "2025-02-28T16:45:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 12,
    "totalPages": 1
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-03-01T10:30:00Z"
  }
}

cURL-Beispiel:

curl -X GET "https://app.spiritflow.team/api/v1/projects?status=ACTIVE" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Einzelnes Projekt abrufen

GET /api/v1/projects/{id}

Scope: projects:read

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Projekts

Antwort (200 OK): Einzelnes PublicProjectDto-Objekt (gleiche Struktur wie in der Liste).

Fehler-Codes:

HTTP-Status	Code	Beschreibung
404	`NOT_FOUND`	Projekt nicht gefunden oder gehoert nicht zu diesem Mandanten

cURL-Beispiel:

curl -X GET "https://app.spiritflow.team/api/v1/projects/5" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Projekt erstellen

POST /api/v1/projects

Scope: projects:write

Request-Body:

Feld	Typ	Pflicht	Standard	Beschreibung
`title`	String	Ja	-	Projekttitel (max. 255 Zeichen)
`numberPrefix`	String	Ja	-	Ticket-Praefix (nur Grossbuchstaben und Ziffern, 1–10 Zeichen, z.B. `ACME`)
`description`	String	Nein	`null`	Projektbeschreibung
`color`	String	Nein	`#3F51B5`	Farbe als Hex-Code (Format: `#RRGGBB`)
`status`	String	Nein	`PLANNED`	Status (siehe Referenzwerte)
`priority`	String	Nein	`NORMAL`	Priorität (siehe Referenzwerte)
`startDate`	String	Nein	`null`	Startdatum (Format: `YYYY-MM-DD`)
`endDate`	String	Nein	`null`	Enddatum (Format: `YYYY-MM-DD`)
`assigneeId`	Long	Nein	`null`	ID des zugewiesenen Projektleiters
`teamMemberIds`	Long[]	Nein	`[]`	IDs der Projektmitglieder
`customerId`	Long	Nein	`null`	ID des zugeordneten Kunden

Hinweis zum numberPrefix: Das Praefix muss innerhalb des Mandanten eindeutig sein und wird für alle Ticket-Nummern dieses Projekts verwendet (z.B. ACME-0001, ACME-0002). Einmal vergeben, kann es nicht mehr geändert werden.

Beispiel-Request:

{
  "title": "Online-Shop Rollout Baeckerei Schneider",
  "numberPrefix": "BSNDR",
  "description": "Implementierung eines WooCommerce-basierten Online-Shops für Backwaren und Catering.",
  "color": "#FF9800",
  "status": "PLANNED",
  "priority": "HIGH",
  "startDate": "2025-04-01",
  "endDate": "2025-08-31",
  "assigneeId": 7,
  "teamMemberIds": [7, 8, 10],
  "customerId": 12
}

Antwort (201 Created):

{
  "data": {
    "id": 13,
    "title": "Online-Shop Rollout Baeckerei Schneider",
    "description": "Implementierung eines WooCommerce-basierten Online-Shops für Backwaren und Catering.",
    "numberPrefix": "BSNDR",
    "color": "#FF9800",
    "status": "PLANNED",
    "priority": "HIGH",
    "startDate": "2025-04-01",
    "endDate": "2025-08-31",
    "progress": 0,
    "ownerId": 2,
    "assigneeId": 7,
    "teamMemberIds": [7, 8, 10],
    "customerName": "Baeckerei Schneider",
    "createdAt": "2025-03-01T10:30:00Z",
    "updatedAt": "2025-03-01T10:30:00Z"
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-03-01T10:30:00Z"
  }
}

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Pflichtfeld fehlt, `numberPrefix` ungültig oder Farbe im falschen Format
404	`NOT_FOUND`	Referenzierter Kunde oder Benutzer nicht gefunden

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/projects" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Online-Shop Rollout Baeckerei Schneider",
    "numberPrefix": "BSNDR",
    "color": "#FF9800",
    "startDate": "2025-04-01",
    "endDate": "2025-08-31"
  }'

Projekt aktualisieren

PUT /api/v1/projects/{id}

Scope: projects:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Projekts

Request-Body (alle Felder optional):

Feld	Typ	Beschreibung
`title`	String	Neuer Titel (max. 255 Zeichen)
`description`	String	Neue Beschreibung
`color`	String	Neue Farbe (`#RRGGBB`)
`status`	String	Neuer Status (siehe Referenzwerte)
`priority`	String	Neue Priorität (siehe Referenzwerte)
`startDate`	String	Neues Startdatum (`YYYY-MM-DD`)
`endDate`	String	Neues Enddatum (`YYYY-MM-DD`)
`assigneeId`	Long	Neuer Projektleiter (User-ID)
`teamMemberIds`	Long[]	Neue Teammitglieder — ersetzt alle bisherigen Mitglieder vollständig
`customerId`	Long	Neuer zugeordneter Kunde

Hinweis zu teamMemberIds: Das Feld ersetzt bei jeder Übertragung die gesamte Mitgliederliste. Um ein Mitglied hinzuzufuegen, müssen alle bisherigen IDs zusammen mit der neuen ID übergeben werden.

Beispiel-Request:

{
  "status": "ACTIVE",
  "endDate": "2025-09-30",
  "teamMemberIds": [7, 8, 10, 11]
}

Antwort (200 OK): Aktualisiertes PublicProjectDto-Objekt.

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Ungültige Feldwerte
404	`NOT_FOUND`	Projekt nicht gefunden

cURL-Beispiel:

curl -X PUT "https://app.spiritflow.team/api/v1/projects/13" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACTIVE",
    "endDate": "2025-09-30"
  }'

Projekt löschen (archivieren)

DELETE /api/v1/projects/{id}

Scope: projects:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Projekts

Antwort: 204 No Content

Fehler-Codes:

HTTP-Status	Code	Beschreibung
404	`NOT_FOUND`	Projekt nicht gefunden

cURL-Beispiel:

curl -X DELETE "https://app.spiritflow.team/api/v1/projects/13" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Aufgaben eines Projekts auflisten

GET /api/v1/projects/{id}/tasks

Scope: projects:read und tasks:read (beide Scopes sind erforderlich)

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Projekts

Query-Parameter:

Parameter	Typ	Pflicht	Beschreibung
`page`	Integer	Nein	Seite (Standard: `0`)
`size`	Integer	Nein	Einträge pro Seite, max. 100 (Standard: `20`)
`sort`	String	Nein	Sortierung (Standard: `createdAt,desc`)

Antwort (200 OK): Paginierte Liste von PublicTaskDto-Objekten. Die Struktur der einzelnen Aufgaben-Objekte entspricht der Antwort von GET /api/v1/tasks.

Fehler-Codes:

HTTP-Status	Code	Beschreibung
403	`ACCESS_DENIED`	Der Scope `tasks:read` fehlt im API-Key
404	`NOT_FOUND`	Projekt nicht gefunden

cURL-Beispiel:

curl -X GET "https://app.spiritflow.team/api/v1/projects/5/tasks?page=0&size=50" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Projekt-Logo

Logo hochladen

POST /api/v1/projects/{id}/logo

Lädt ein Logo für das Projekt hoch. Das Bild wird auf max. 512px verkleinert. Unterstützte Formate: JPEG, PNG, WebP.

Scope: projects:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Projekts

Request: Multipart Form-Data mit dem Feld file.

Antwort (200 OK):

{
  "data": {
    "logoUrl": "/api/attachments/project-logos/13_1234567890.png"
  }
}

Die Logo-URL ist öffentlich ohne Authentifizierung abrufbar.

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`BAD_REQUEST`	Dateiformat nicht unterstützt oder Datei fehlt
404	`NOT_FOUND`	Projekt nicht gefunden

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/projects/13/logo" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/pfad/zum/logo.png"

Logo entfernen

DELETE /api/v1/projects/{id}/logo

Entfernt das Logo eines Projekts.

Scope: projects:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Projekts

Antwort: 204 No Content

Fehler-Codes:

HTTP-Status	Code	Beschreibung
404	`NOT_FOUND`	Projekt nicht gefunden

cURL-Beispiel:

curl -X DELETE "https://app.spiritflow.team/api/v1/projects/13/logo" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"