What is a UUID and where do I find it?
What ValueStreamer uses UUIDs for and which REST API endpoint returns the UUID of a team, a KPI or a list.
Applies to: users with REST API credentials · Module: Integrations & API
A UUID (Universally Unique Identifier) is a 36-character identifier that ValueStreamer uses to identify every object unambiguously: users, teams, KPIs, sub-tiles, lists, list entries, deviations and countermeasures. The UUID is assigned when the object is created, never changes afterwards and cannot be edited. In the REST API you pass UUIDs as path parameters, for example in /exchange/list/{list-id}/{team-id}. You retrieve the UUID you need beforehand from the matching meta endpoint.
Prerequisites
- REST API credentials for your ValueStreamer instance. Every call requires HTTP Basic Auth, see API Authentication & Error Codes.
- Base URL of your instance:
https://api-<tenant>.valuestreamer.de/api/. All paths in this article are relative to it.
How a UUID is structured
32 hexadecimal characters in five groups, separated by four hyphens in an 8-4-4-4-12 pattern:
4f8a2c71-93be-4b0d-a1e6-7c2d5e9f3b48The value is assigned randomly and carries no meaning. A UUID tells you neither which object it belongs to nor when that object was created. It cannot be incremented or derived from a name either. You have to retrieve it and use it exactly as returned.
ℹ️ Note: A UUID is not an access key. Without valid credentials, a known UUID grants no access.
Which endpoint returns which UUID
| Object | Endpoint that returns the UUID | Used as |
|---|---|---|
| User | GET /exchange/users |
User reference in further calls |
| Team | GET /exchange/teams |
{team-id} |
| Parent team | GET /exchange/teams (field parentTeam) |
Evaluating the cascade structure |
| KPI | GET /exchange/kpi |
{kpi-id} |
| Sub-tile and KPI value | GET /exchange/kpi/{kpi-id} |
{sub-tile-id}, kpiValueId |
| List | GET /exchange/list/meta |
{list-id} |
| Fields of a list | GET /exchange/list/meta/{list-id} |
Checking field names and field types |
| List entry | GET /exchange/list/{list-id}/{team-id} |
{entry-id} |
| Deviation | GET /exchange/deviations?team={team-id} |
{id} in /exchange/deviations/{id} |
| Deviation category | GET /exchange/deviation-categories |
Category when creating a deviation |
The endpoints for users and teams are described in detail in Retrieve User & Team IDs via API.
✨ Tip: Store the UUIDs your integration needs permanently once, in the configuration of your script or middleware, instead of querying them on every run. Since they never change, they stay valid for as long as the object exists.
What the sequence looks like in a call
First retrieve the team UUID:
GET https://api-<tenant>.valuestreamer.de/api/exchange/teamsThen pass the returned UUID into the target call:
GET https://api-<tenant>.valuestreamer.de/api/exchange/list/9c1f7a30-5d42-4e18-b7c9-2a6e8d4f1b03/4f8a2c71-93be-4b0d-a1e6-7c2d5e9f3b48The first UUID is the list, the second one is the team. The order of the path parameters is binding.
⚠️ Caution: Check the order before you send write calls. Two swapped UUIDs are formally valid and are not caught by the format check. They result in a 404, or in the worst case they write to the wrong object.
If it does not work
| Symptom | Cause | Solution |
|---|---|---|
400 Bad Request |
UUID malformed, truncated, or copied with spaces or quotation marks | Copy the value unchanged from the meta endpoint response, check the 8-4-4-4-12 pattern |
404 Not found |
UUID does not exist, belongs to a different object type, or the object was deleted | Query the UUID from the meta endpoint again |
404 Not found despite correct UUIDs |
The combination does not match, for example a list that is not assigned to the team you specified | Check the assignment via GET /exchange/list/meta |
| Call returns an empty result set | The UUID points to an object with no data in the period queried | Check the filter parameters, not the UUID |
If the call still fails after you have verified the UUIDs, contact ValueStreamer Support and provide the full call, the UUIDs used and the response code.
Related articles
- Retrieve User & Team IDs via API: the next step when you specifically need user or team UUIDs.
- API Authentication & Error Codes: which credentials are required and what the response codes mean.
- Architecture & Usage of the REST API in ValueStreamer: base URL, structure of the endpoints and data flow at a glance.
- API Documentation & YAML Files for Download: the full specification per module as PDF and YAML.
Frequently asked questions
Does an object's UUID change when I rename the object? No. Name, short name and assignment can be changed, the UUID stays the same. It is the only reference an integration can rely on permanently.
Can I assign or change a UUID myself? No. ValueStreamer assigns the UUID when the object is created. It cannot be edited, neither in the interface nor via the API.
Why do some examples show /api/exchange/... and others only /exchange/...? Both refer to the same endpoint. /api/ is part of the base URL https://api-<tenant>.valuestreamer.de/api/, and the relative paths start with /exchange/ after it.
Do I get an object's UUID back after deleting the object? No. A UUID is never reused. Calls against the UUID of a deleted object are answered with 404 Not found.