API interface

• Manage API keys
• General API usage
• Update counters via API
• API for Assets Tasks

Manage API keys

The HTTP(S) API has been available since MXSuite version 3.3.0.

To create an API key, there are 2 steps needed:

1. Create the API-user
2. Create the API-key

Create an API user

1. Open the Administration module 
2. Click on Users
   

   
   

   
   
3. Create a new user for the API with the correct user rights. Assure that you select user type API.
   

   

   
   

Create the API key

1. Open the Administration module
2. Click on API keys
   

   
   

   
   
3. Click on New...
   

   
   
   

4. Enter the Name of the API so you can easily distinguish all API keys.
5. Select the related API user
6. If needed, enter an expiry date.
7. Click on Save & close
8. Now the API key is created and visible.

General API usage

Authentication

To access the API, first an API key needs to be created from the Administration page. The key will be used as a header in the HTTP request.

MXSuite expects a mx-apikey header on each request.

mx-apikey: apikey

Besides the mx-apikey header, two more headers are required.

accept: application/json, text/plain, */*
content-type: application/json

Error handling

Successful responses will return a 200 or 204 HTTP response code. Errors will return a 4xx or a 5xx.

Some scenarios of errors:

• missing the mx-apikey header
• wrong api key
• expired api key
• MXSuite license expired
• The user doesn't have enough rights for that specific request

Examples

Below an example of how to use the API key in MXSuite. In this example the following parameters are used:

• URL for MXSuite: http://localhost:4200/
• Location mane: vessel2
• API key: 4a74ad039ffc4f3288da7a0e03e608da

Postman

Postman can be downloaded here: https://www.postman.com/downloads/
Open Postman, click on Import button and paste the following command:

curl 'http://localhost:4200/api/ExternalCounters/UploadCountersHistory' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'mx-apikey: 4a74ad039ffc4f3288da7a0e03e608da' \
  --data-raw '[{"name":"c1","locationName":"vessel2","value":1119,"timestamp":"2024-10-05T12:11:11.000Z"},{"name":"C2","locationName":"Vessel2","value":2229,"timestamp":"2024-10-05T12:11:11.000Z"},{"name":"c3","locationName":"Vessel2","value":3339,"timestamp":"2024-10-05T12:11:11.000Z"}]'

In the Headers tab the API key can be changed:

In the Body tab, the payload value can be changed.

Console

Define a payload variable:

let payload = [
    {
        "name": "c1",
	"locationName": "vessel2",
        "value": 1119,
        "timestamp": new Date(2024,09,05,15,11,11)
    },
    {
        "name": "C2",
	"locationName": "Vessel2",
        "value": 2229,
        "timestamp": new Date(2024,09,05,15,11,11)
    },
    {
        "name": "c3",
	"locationName": "Vessel2",
        "value": 3339,
        "timestamp": new Date(2024,09,05,15,11,11)
    }
];

Request:

fetch("http://localhost:4200/api/ExternalCounters/UploadCountersHistory", {
  "headers": {
    "accept": "application/json",
    "content-type": "application/json",
    "mx-apikey": "4a74ad039ffc4f3288da7a0e03e608da",
  },
  "body": JSON.stringify(payload),
  "method": "POST"
}).then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Don't forget to change the mx-apikey header value

Update counters via API

Overview

The Counters API provides endpoints for managing running hours (counters) within the MXSuite system. This API allows you to upload counter history records for one or more counters at a location, with proper authorization controls.

Base URL

• api/external/Counters/
  

1. Upload Counters History

Overview

The Upload Counters History endpoint allows authorized users to upload a batch of running hours (counter) history records for one or more counters at a specific location. This is typically used to record the latest readings for equipment counters.

Endpoint

POST /api/external/Counters/UploadCountersHistory

Authentication

All endpoints require authentication and appropriate user rights.
This endpoint requires the UpdateRunningHours right and the location must not be read-only.
Authorization is enforced via the MXApiPolicyAuthorize attribute.

Request

{
  name: string,
  locationName: string,
  value: number,
  timeStamp: Date
}

[
  {
    "Name": "Main Engine",
    "LocationName": "Neptune",
    "Value": 12345,
    "TimeStamp": "2025-06-23T14:00:00Z"
  },
  {
    "Name": "Generator 1",
    "LocationName": "Neptune",
    "Value": 6789,
    "TimeStamp": "2025-06-23T14:00:00Z"
  }
]

Error Responses

•    400 Bad Request: Invalid input data (e.g., missing required fields, invalid values).
•    401 Unauthorized: User is not authenticated.
•    403 Forbidden: User does not have the required rights or location is read-only.
•    500 Internal Server Error: An unexpected error occurred.

If there is no location with that name, the entry is ignored.
If there is no counter with that name for that location, the entry is ignored.
If there is already an entry added for that counter in that location with the same value and timestamp, the entry is ignored.

API for Assets Tasks

[
  {
    "id": "b1a2c3d4-e5f6-7890-abcd-1234567890ab",
    "uniqueId": "CAT-001",
    "name": "Engine Room",
    "parentId": "c2b3a4d5-e6f7-8901-bcda-2345678901bc",
    "displayIndex": 1
  }
]

[
  {
    "id": "d3e4f5a6-b7c8-9012-cdab-3456789012cd",
    "type": 1,
    "uniqueId": "GRP-001",
    "name": "Auxiliary Systems",
    "displayIndex":1
  }
]

{
  "GroupId":"3C160DF1-3A5C-406F-BAC6-00A4AB8C44A9",
  "GroupType":1,
  "UniqueId": "Task-001",
  "TaskName": "Oil Change - Updated",
  "Interval": 45,
  "IntervalType": 1,
  "DueDate": "2025-06-01T00:00:00Z",
  "IsCounterBased": false,
  "IsRemarkMandatory": true,
  "IsProject": false,
  "IsRecurrent": true,
  "IsFixedInterval": true,
  "IsAtServiceRequest": false,
  "IsDefect": false,
  "TaskDescription": "Updated description for oil change.",
  "MaxInterval": 90,
  "MaxIntervalType": 2,
  "DueCounters": 150,
  "Downtime": 3.0,
  "WarningInterval": 10,
  "WarningIntervalType": 1,
  "CounterName": "Main Engine",
  "DefaultEstimatedBudget": {
    "Amount": 600.0,
    "Currency": "USD" 
  },
  "Ranks": ["Rank1", "Rank2"],
  "ApproverRanks": ["Approver1"],
  "RequiresApproval": true
}

{
  "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467"
}

{
  "UniqueId": "Task-001",
  "TaskName": "Oil Change - Updated",
  "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467",
  "GroupId":"3C160DF1-3A5C-406F-BAC6-00A4AB8C44A9",
  "GroupType":1,
  "Interval": 45,
  "IntervalType": 1,
  "DueDate": "2025-06-01T00:00:00Z",
  "IsCounterBased": false,
  "IsRemarkMandatory": true,
  "IsProject": false,
  "IsRecurrent": true,
  "IsFixedInterval": true,
  "IsAtServiceRequest": false,
  "IsDefect": false,
  "TaskDescription": "Updated description for oil change.",
  "MaxInterval": 90,
  "MaxIntervalType": 2,
  "DueCounters": 150,
  "Downtime": 3.0,
  "WarningInterval": 10,
  "WarningIntervalType": 1,
  "CounterName": "Main Engine",
  "DefaultEstimatedBudget": {
    "Amount": 600.0,
    "Currency":  "EURO"
  },
  "Ranks": ["Rank1", "Rank2"],
  "ApproverRanks": ["Approver1"],
  "RequiresApproval": true
}

[
    "1463aea5-9062-45bf-8b9c-24cc5615d467",
    "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea"
]

{
  "GroupId": "d3e4f5a6-b7c8-9012-cdab-3456789012cd",
  "GroupType": 1
}

[
  "e4f5a6b7-c8d9-0123-dabc-4567890123de",
  "f5a6b7c8-d9e0-1234-abcd-5678901234ef"
]

{
  "TaskId": "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea",
  "NumberOfSignOffs": 5
}

{
  "Errors": [
    {
      "message": "string",
      "errorCode": number,
      "isBusinessException": false,
      "businessExceptionData": null,
      "failureServerReason": null
    }
  ]
}

{
    "errors": [
        {
            "message": "Category name is required",
            "errorCode": 9,
            "isBusinessException": false,
            "businessExceptionData": null,
            "failureServerReason": null
        }
    ]
}