diff --git a/misc/BreCalApi.md b/misc/BreCalApi.md
index 381842a..b19d260 100644
--- a/misc/BreCalApi.md
+++ b/misc/BreCalApi.md
@@ -1,10 +1,21 @@
 # Bremen calling API
-_Version 1.7.0_
+Version: _1.7.0_
+Last change: _Nov 14, 2025_
 
-Administer DEBRE ship calls, times and notifications
+## Introduction
 
-## Authentication
-- **ApiKey**: API key in `header` header named `Authorization`.
+This API allows users to interact with "Bremen calling" without an UI. Apart vom querying data via _GET_ endpoints users may create and update shipcalls, assign participants and update participant times for shipcalls. 
+
+Creating and updating times and shipcalls depend on the participant roles a user is assigned to. For example, if a participant has the role "AGENCY" they may change assignments _and_ create and update agency times. A participant with the role "PILOT" on the other hand may not change the assigments and only create/update times for the pilot.
+
+### Authentication
+- **ApiKey**: API key in `header` header named `Authorization`. This is a JWT Token that the caller receives upon login.
+
+### Notes on this version
+
+This version refers to _1.7_ whereas the public client currently has version _1.6_. This means that there is some functionality available in the API that cannot be accessed through the UI yet, specifically notifications.
+
+There is no documentation for the structures returned by _GET_ requests but these can easily be determined via a single query.
 
 ## Ship Endpoints