16 KiB
Bremen calling API
Version: 1.7.0 Last change: Nov 14, 2025
Introduction
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
headerheader namedAuthorization. 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
DELETE /ships
Summary: Delete a ship (logically). A ship can only be logically deleted, since it is possible to have been used in previous shipcalls. On logical delete, the ship can no longer be selected in a new ship call.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | integer | Yes | Id of ship. Example: 42. Id of ship to be deleted. |
Responses
- 200
- 400
- 401
- 500
- 503
GET /ships
Summary: gets a list of ships Gets a list of ships including logically deleted ships to be used with shipcalls
Responses
- 200: list of ships
- 400
- 401
- 500
- 503
POST /ships
Summary: create a new ship entry adds a new non-existing ship to the database. The ships IMO number is the unique identifier.
Request Body
Ship details. Do not provide id parameter.
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| name | string | No | |
| imo | integer | No | |
| callsign | string | No | |
| participant_id | integer | No | Optional reference to participant (tug role) |
| length | number | No | |
| width | number | No | |
| is_tug | boolean | No | |
| bollard_pull | integer | No | |
| eni | integer | No | BSMD internal use |
| created | string | No | Readonly field set by the database when ship was created |
| modified | string | No | Readonly field set by the database when ship was last modified |
| deleted | boolean | No | marks the ship as logically deleted |
Responses
- 201
- 400
- 401
- 500
- 503
PUT /ships
Summary: Update a ship entry Updating a ship entry. Please do not modify the IMO number. In that case please add a new entry.
Request Body
Updated ship entry. The id parameter is required.
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| name | string | No | |
| imo | integer | No | |
| callsign | string | No | |
| participant_id | integer | No | Optional reference to participant (tug role) |
| length | number | No | |
| width | number | No | |
| is_tug | boolean | No | |
| bollard_pull | integer | No | |
| eni | integer | No | BSMD internal use |
| created | string | No | Readonly field set by the database when ship was created |
| modified | string | No | Readonly field set by the database when ship was last modified |
| deleted | boolean | No | marks the ship as logically deleted |
Responses
- 200
- 400
- 401
- 500
- 503
Shipcall Endpoints
GET /shipcalls
Summary: Gets a list of ship calls Get current ship calls
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| past_days | query | integer | No | number of days in the past to include in the result. Example: 7. |
Responses
- 200: ship call list
- 400
- 401
- 500
- 503
POST /shipcalls
Summary: Create a new ship call A new shipcall is created without times at this point. This is ususally done by the BSMD or a participant with that particular role.
Request Body
Creates a new ship call. Do not provide id parameter.
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| ship_id | integer | Yes | |
| port_id | integer | No | |
| type | string | Yes | Type of ship call |
| eta | string | No | |
| voyage | string | No | |
| etd | string | No | |
| arrival_berth_id | integer | No | |
| departure_berth_id | integer | No | |
| tug_required | boolean | No | |
| pilot_required | boolean | No | |
| flags | integer | No | |
| pier_side | boolean | No | |
| bunkering | boolean | No | |
| replenishing_terminal | boolean | No | |
| replenishing_lock | boolean | No | |
| draft | number | No | |
| tidal_window_from | string | No | |
| tidal_window_to | string | No | |
| rain_sensitive_cargo | boolean | No | |
| recommended_tugs | integer | No | |
| anchored | boolean | No | |
| moored_lock | boolean | No | |
| canceled | boolean | No | |
| evaluation | string | No | Evaluation of the ship call |
| evaluation_message | string | No | |
| time_ref_point | integer | No | Physical reference point for all times given in shipcall and depending times entries |
| participants | array | No | |
| created | string | No | Readonly field set by the database when shipcall was created |
| modified | string | No | Readonly field set by the database when shipcall was last modified |
Responses
- 201
- 400
- 401
- 500
- 503
PUT /shipcalls
Summary: Updates a ship call Updates a shipcall. Usually done if the participant assignments change.
Request Body
Creates a new ship call. The id parameter is required.
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| ship_id | integer | Yes | |
| port_id | integer | No | |
| type | string | Yes | Type of ship call |
| eta | string | No | |
| voyage | string | No | |
| etd | string | No | |
| arrival_berth_id | integer | No | |
| departure_berth_id | integer | No | |
| tug_required | boolean | No | |
| pilot_required | boolean | No | |
| flags | integer | No | |
| pier_side | boolean | No | |
| bunkering | boolean | No | |
| replenishing_terminal | boolean | No | |
| replenishing_lock | boolean | No | |
| draft | number | No | |
| tidal_window_from | string | No | |
| tidal_window_to | string | No | |
| rain_sensitive_cargo | boolean | No | |
| recommended_tugs | integer | No | |
| anchored | boolean | No | |
| moored_lock | boolean | No | |
| canceled | boolean | No | |
| evaluation | string | No | Evaluation of the ship call |
| evaluation_message | string | No | |
| time_ref_point | integer | No | Physical reference point for all times given in shipcall and depending times entries |
| participants | array | No | |
| created | string | No | Readonly field set by the database when shipcall was created |
| modified | string | No | Readonly field set by the database when shipcall was last modified |
Responses
- 200
- 400
- 401
- 500
- 503
Static Endpoints
GET /berths
Summary: Gets a list of all berths registered Returns a list of berths, including berths that are (logically) deleted
Responses
- 200: list of berths
- 400
- 401
- 500
- 503
GET /history
Summary: History data This endpoint returns a list of changes made to the specific shipcall
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| shipcall_id | query | integer | Yes | Id of ship call. Example: 3. Id given in ship call list |
Responses
- 200: list of history entries
- 400
- 401
- 500
- 503
GET /notifications
Summary: Gets a list of notifications pursuant to a specified participant and ship call List of notifications (tbd)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| shipcall_id | query | integer | No | Id of ship call. Example: 52. Id given in ship call list |
Responses
- 200: notification list
- 400
- 401
- 500
- 503
GET /participants
Summary: gets one or all participants If no parameter is given, all participants are returned. The list can be used to display participant information in the context of ship calls.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | query | integer | No | Id of user. Example: 2. User id returned by verify call. |
Responses
- 200: one or all participants as list
- 400
- 401
- 404
- 500
- 503
GET /ports
Summary: Your GET endpoint Returns a list of ports
Responses
- 200: list of ports
- 401
- 403
- 500
- 503
Times Endpoints
DELETE /times
Summary: Delete a times entry for a ship call. A times entry is typically deleted if the agent for example changes or removes the participant assignment for a particular role.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | integer | Yes | Id of times. Example: 42. Id of times entry to be deleted. |
Responses
- 200
- 400
- 401
- 500
- 503
GET /times
Summary: Gets list of times Get all times assigned to a shipcall. These might not be complete.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| shipcall_id | query | integer | No | Id. Example: 42. Id of referenced ship call. |
Responses
- 200: list of recorded times
- 400
- 401
- 500
- 503
POST /times
Summary: Create a new times entry for a ship call The times entry for a shipcall is created with reference to a participant. For each participant type there should be only one times data record.
Request Body
Times entry that will be added to the ship call. Do not provide id parameter.
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| eta_berth | string | No | Arrival time at berth |
| eta_berth_fixed | boolean | No | If true, the eta is fixed and cannot be changed |
| etd_berth | string | No | departure time from berth |
| etd_berth_fixed | boolean | No | If true, the etd is fixed and cannot be changed |
| lock_time | string | No | arrival time at lock |
| lock_time_fixed | boolean | No | If true, the lock time is fixed and cannot be changed |
| zone_entry | string | No | Expected time of entry into the zone |
| zone_entry_fixed | boolean | No | If true, the zone entry time is fixed and cannot be changed |
| operations_start | string | No | Start time for terminal operations |
| operations_end | string | No | End time for terminal operations |
| remarks | string | No | Additional remarks |
| shipcall_id | integer | Yes | Reference to a shipcall id |
| participant_id | integer | Yes | Reference to a participant id |
| berth_id | integer | No | Reference to a berth id |
| berth_info | string | No | Additional info text for berth |
| pier_side | boolean | No | true if ship is rotated, false otherwise |
| participant_type | integer | No | |
| ata | string | No | ata can be set by mooring if actual times are different from planned |
| atd | string | No | atd can be set by mooring if actual times are different from planned |
| eta_interval_end | string | No | Optional end of the interval for the times eta entry |
| etd_interval_end | string | No | Optional end of the interval for the times etd entry |
| created | string | No | Readonly field set by the database when times record was created |
| modified | string | No | Readonly field set by the database when times record was last modified |
Responses
- 201
- 400
- 401
- 500
- 503
PUT /times
Summary: Update a times entry for a ship call Updating a times entry for a ship for a particular participant. The times entries are required for a shipcall to pass the validation rules.
Request Body
Times entry that will be added to the ship call. The id parameter is required.
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| eta_berth | string | No | Arrival time at berth |
| eta_berth_fixed | boolean | No | If true, the eta is fixed and cannot be changed |
| etd_berth | string | No | departure time from berth |
| etd_berth_fixed | boolean | No | If true, the etd is fixed and cannot be changed |
| lock_time | string | No | arrival time at lock |
| lock_time_fixed | boolean | No | If true, the lock time is fixed and cannot be changed |
| zone_entry | string | No | Expected time of entry into the zone |
| zone_entry_fixed | boolean | No | If true, the zone entry time is fixed and cannot be changed |
| operations_start | string | No | Start time for terminal operations |
| operations_end | string | No | End time for terminal operations |
| remarks | string | No | Additional remarks |
| shipcall_id | integer | Yes | Reference to a shipcall id |
| participant_id | integer | Yes | Reference to a participant id |
| berth_id | integer | No | Reference to a berth id |
| berth_info | string | No | Additional info text for berth |
| pier_side | boolean | No | true if ship is rotated, false otherwise |
| participant_type | integer | No | |
| ata | string | No | ata can be set by mooring if actual times are different from planned |
| atd | string | No | atd can be set by mooring if actual times are different from planned |
| eta_interval_end | string | No | Optional end of the interval for the times eta entry |
| etd_interval_end | string | No | Optional end of the interval for the times etd entry |
| created | string | No | Readonly field set by the database when times record was created |
| modified | string | No | Readonly field set by the database when times record was last modified |
Responses
- 200
- 400
- 401
- 500
- 503
User Endpoints
POST /login
Summary: Returns a JWT session token and user data if successful Perform login
Request Body
Login credentials
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| username | string | Yes | |
| password | string | Yes |
Responses
- 200: Successful response
- 400
- 403
- 500
- 503
Response 200 JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| participant_id | integer | No | |
| first_name | string | No | |
| last_name | string | No | |
| user_name | string | No | |
| user_phone | string | No | |
| user_email | string | No | |
| notify_email | boolean | No | |
| notify_whatsapp | boolean | No | |
| notify_signal | boolean | No | |
| notify_popup | boolean | No | |
| exp | number | No | |
| token | string | No | |
| notify_on | array | No |
PUT /user
Summary: Update user details (first/last name, phone, password) Update user information
Request Body
User details
JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | |
| old_password | string | No | |
| new_password | string | No | |
| first_name | string | No | |
| last_name | string | No | |
| user_phone | string | No | |
| user_email | string | No | |
| notify_email | boolean | No | |
| notify_popup | boolean | No | |
| notify_whatsapp | boolean | No | |
| notify_signal | boolean | No | |
| notify_on | array | No |
Responses
- 200
- 400
- 401
- 500
- 503