# 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 `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

### `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<object> | 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<object> | 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<string> | 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<string> | No |  |

#### Responses

- **200**
- **400**
- **401**
- **500**
- **503**
---