✅ Managing Tasks via REST API

🔍 Contents

Prerequisites
Authentication
Overview of Endpoints
Managing Tasks (CRUD)
Retrieving/Editing Description & Status History
Technical Notes
Tips & Best Practices
FAQ

📋 Prerequisites

🔐 API credentials (Username + Password for HTTP Basic Auth)
⚙️ An environment to execute REST requests (e.g., Power Automate, Postman, Python, Swagger UI)

ℹ️ Note: To create a task, you need valid UUIDs for:

Team (responsibleTeam)
Category (category)
Optional: Label, responsible person, T-Card

🔑 Authentication

Authentication is done using HTTP Basic Auth.

Header example:

Authorization: Basic <Base64-encoded username:password>

🔧 Changes made via the API are recorded in the system under the user name "API-USER".

🔗 Overview of Endpoints (Tasks)

Method	Endpoint	Description
GET	`/exchange/tasks`	Retrieve all tasks
GET	`/exchange/tasks/{id}`	Retrieve a single task
POST	`/exchange/tasks`	Create a new task
PUT	`/exchange/tasks/{id}`	Update a task
DELETE	`/exchange/tasks/{id}`	Delete a task

📸 Screenshot: Endpoints in Swagger UI

Additional Endpoints:

📄 Retrieve/Edit Description:
- GET /tasks/{id}/description
- PUT /tasks/{id}/description
📈 Retrieve Status History:
- GET /tasks/{id}/status-history
🧾 Metadata (categories, labels, teams):
- GET /taskboard-categories
- GET /taskboard-labels
- GET /teams/{id}/taskboard

➕ Creating a New Task (POST)

Endpoint:

POST /exchange/tasks

Example request:

{
  "title": "New Task",
  "category": "263c2d97-762f-4ef3-a350-b88225d00882",
  "priority": true,
  "responsibleTeam": "49af7f6c-c1e5-49c7-99ed-c27b29067eec",
  "status": 2,
  "targetEndDate": "2025-08-31",
  "targetEffort": 6.0
}

✨ Tip: For T-Card tasks, also add "tCard": true and the appropriate label ID.

🛠 Updating a Task (PUT)

Endpoint:

PUT /exchange/tasks/{task-id}

Example request:

{
  "title": "Updated Title",
  "category": "263c2d97-762f-4ef3-a350-b88225d00882",
  "priority": false,
  "status": 3,
  "statusMessage": "Blocked due to missing resources",
  "responsibleTeam": "c2c1483f-7b29-4ed5-9d46-c290f8cb50a5",
  "targetEffort": 4.0,
  "targetEndDate": "2025-09-10"
}

⚠️ Important: When changing status (e.g., green → red), you must include statusMessage!

🗑️ Deleting a Task (DELETE)

DELETE /exchange/tasks/{task-id}

⚠️ Warning: Deleting a task will also remove all linked content (deviations, feedback, etc.).

📄 Editing the Description (PUT)

PUT /exchange/tasks/{task-id}/description
Content-Type: text/html

Example:

<p>New description with HTML markup</p>

🕓 Retrieving Status History

GET /exchange/tasks/{task-id}/status-history

Example response:

[
  {
    "comment": "Status changed",
    "modifiedByUser": "API-USER",
    "modifiedDate": "2025-08-01",
    "status": 3
  }
]

📌 Technical Notes

Required fields when creating: title, category, responsibleTeam, status, targetEffort, targetEndDate
Status codes: 1 = green, 2 = blue, 3 = red
Archiving is only possible via the UI
T-Card tasks cannot be automatically completed or replanned
HTML for description must be valid

✨ Tips & Best Practices

🔄 Use unique labels & categories per team (via GET /teams/{id}/taskboard)
🧪 Test API requests first in Swagger or Postman
👥 Responsible persons for tasks must be members of the team (via GET /teams/{id})

❓ FAQ

Which fields are required to create a task?
→ At minimum: title, category, responsibleTeam, status, targetEndDate, targetEffort.

Can I archive tasks via the API?
→ No – this is only possible via the UI.

What happens if I send a field with null?
→ It will be deleted or set to null.