API - Tags Admin

📕 Für Administratoren und Entwickler

Über die spiritflow Public API können Tags des Mandanten abgerufen und angelegt werden. Tags werden verwendet, um Aufgaben zu kennzeichnen und zu kategorisieren. Alle Endpunkte sind unter dem Basis-Pfad /api/v1/tags erreichbar und erfordern einen gültigen API-Key mit dem entsprechenden Scope.

---

Tags auflisten

GET /api/v1/tags

Erforderlicher Scope: tags:read

Gibt alle Tags des Mandanten zurück (alphabetisch sortiert).

Antwort-Felder:

Feld	Typ	Beschreibung
id	number	Eindeutige ID
name	string	Tag-Name
color	string?	Farbcode im Hex-Format (z.B. #FF5733), kann null sein
createdAt	string	Erstellungszeitpunkt (ISO 8601, UTC)

Antwort (200 OK):

{
  "data": [
    {
      "id": 3,
      "name": "Dringend",
      "color": "#F44336",
      "createdAt": "2025-01-10T08:00:00Z"
    },
    {
      "id": 7,
      "name": "Intern",
      "color": "#3F51B5",
      "createdAt": "2025-02-05T14:20:00Z"
    },
    {
      "id": 1,
      "name": "Kundenprojekt",
      "color": null,
      "createdAt": "2024-12-01T09:00:00Z"
    }
  ],
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-03-01T10:30:00Z"
  }
}

cURL-Beispiel:

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

---

Tag erstellen

POST /api/v1/tags

Erforderlicher Scope: tags:write

Request-Body:

Feld	Typ	Pflicht	Beschreibung
name	string	Ja	Tag-Name (pro Mandant eindeutig, max. 50 Zeichen)
color	string	Nein	Farbcode im Hex-Format (z.B. #3F51B5)

Antwort (201 Created): Erstelltes Tag-Objekt (gleiche Felder wie in der Liste).

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	VALIDATION_ERROR	Name fehlt, zu lang oder Farbcode ungültig
409	CONFLICT	Ein Tag mit diesem Namen existiert bereits in diesem Mandanten

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/tags" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dringend",
    "color": "#F44336"
  }'