🔍 Contents
-
Prerequisites
-
Authentication
-
Overview of Endpoints
-
Creating a Deviation (POST)
-
Updating a Deviation (PUT)
-
Retrieving & Deleting Deviations (GET, DELETE)
-
Managing the Description
-
Technical Notes
-
Tips & Best Practices
-
FAQ
📋 Prerequisites
-
🔐 API credentials (Username + Password for HTTP Basic Auth)
-
🌐 Access to a tool for executing HTTP requests (e.g., Power Automate, Python, Postman, Swagger UI)
-
🧲 Team ID, Category ID, and optionally a Source Object ID (e.g., KPI, Task, Process Step)
🔑 Authentication
Authentication is done via HTTP Basic Auth. Username and password are provided by ValueStreamer Support.
All API activities are executed under the technical user API-USER and are documented in the change log.
🔹 Overview of Endpoints
| Action | Method | Path |
|---|---|---|
| Retrieve deviations | GET | /exchange/deviations?team={id} |
| Retrieve single deviation | GET | /exchange/deviations/{id} |
| Create new deviation | POST | /exchange/deviations |
| Update deviation | PUT | /exchange/deviations/{id} |
| Delete deviation | DELETE | /exchange/deviations/{id} |
| Retrieve description | GET | /exchange/deviations/{id}/description |
| Update description | PUT | /exchange/deviations/{id}/description |
📸 Screenshot: Endpoints in Swagger UI
✏️ Creating a Deviation (POST)
Endpoint:
/exchange/deviations
Method: POST
Content-Type: application/vs.v2.0+json
Required fields:
-
responsibleTeam→ ID of the responsible team -
category→ ID of the selected category -
deviationType→"ERROR"or"PROBLEM" -
duration→ Duration in minutes -
frequency→ Frequency (number > 0) -
title→ Short title of the deviation
Optional:
-
sourceEntity→ Link to KPI, Task, etc.
⚠️ Only single deviations can be created via the API. Combined and child deviations can only be created via the GUI.
✏️ Updating a Deviation (PUT)
Endpoint:
/exchange/deviations/{id}
Method: PUT
Required fields:
-
title -
closed→true/false -
duration,frequency(for single & child deviations) -
category(for single deviations)
Optional:
-
sourceEntity→ Update the link
✔ Combined or child deviations can be updated, but with restrictions: duration/frequency cannot be changed.
📂 Retrieving & Deleting Deviations
Retrieve a single deviation
GET /exchange/deviations/{id}
Optional: ?include=COUNTERMEASURES to include countermeasures.
Retrieve description
GET /exchange/deviations/{id}/description
(HTML format)
Delete a deviation
DELETE /exchange/deviations/{id}
⚠️ Also deletes all linked child deviations, countermeasures, Go & See, Top Issues, and Feedback.
Linked tasks remain but the connection is removed.
📃 Managing the Description
Read description:
GET /exchange/deviations/{id}/description
Update description:
PUT /exchange/deviations/{id}/description
Content-Type: text/html
💡 Technical Notes
-
Base URL:
https://api-<tenant>.valuestreamer.de/api/ -
Accepted Content-Type:
application/vs.v2.0+json -
Auth Header:
Authorization: Basic <Base64-encoded> -
Maximum 200 results per page
-
Possible filters:
?team=...&status=ACTIVE|CLOSED|ALL&level=SINGLE|COMBINED|CHILDREN
📊 Tips & Best Practices
-
Use
GET /teams/{id}/deviation-configto see valid categories per team -
Only active categories are available for
POST/PUT -
Combined deviations can only be created via the GUI
-
Descriptions can contain HTML (e.g., for formatting, links, lists)
🚗 FAQ
Can I also link tasks, KPIs, or meetings?
→ Yes, via sourceEntity. Valid types: KPI, LIST, PROCESSACTIVITY, TASK, MEETINGATTENDANCE
Can I query multiple teams at once?
→ No, queries are always team-specific via ?team={id}.
How do I know if a deviation is closed?
→ Check the closed field (true) or the status CLOSED_....
How do I find the correct Category ID?
→ Use GET /exchange/deviation-categories or team-specific via GET /teams/{id}/deviation-config.