Overview

The Watchmen REST API allows authorized users to retrieve specific data securely. API-Access Keys grant unrestricted access only to the endpoints documented below. These keys cannot be used to access any other APIs on watchmen.novoai.de.

Authentication

All API requests must include the JWT in the Authorization header using the Bearer token scheme

The below set of APIs can be accessed by having API-Access Key in the X-API-KEY header with the generated token in string format

Example Authorization Header

Authorization: Bearer <Bearer-Token>

X-API-KEY: <API-AccessKey>

Generating an API-Access Key

Navigate to the Admin Panel
- Go to the API Access Keys section.
- Click Create New API Access Key.
- Set a validity period (maximum: 1 year).

Copy the key securely. It cannot be retrieved later.ca

Using the API-Access Key
- Include the key in the request header as shown above.

Accessible APIs

Authentication

All endpoints require authentication using either a Bearer Token or an X-API-KEY.

Headers

Ensure that API responses include the appropriate headers:

Header	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`
`X-API-KEY`	string	Yes	API Access Key for authentication
`Authorization`	string	Yes (if using JWT)	Bearer token for JWT authentication
`Cache-Control`	string	No	Defines cache policies
`Access-Control-Allow-Origin`	string	No	Specifies allowed cross-origin requests

Base URL

Use the base URL: https://wm.novoai.de

For testing the integration, access to a development server could also be provided on request

Endpoints

1. Retrieve All Halls

Endpoint: GET /v2/halls

Description: This API retrieves all halls associated with the company for an authenticated user. The user must have the necessary permissions to access the halls.

Authentication: This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)

Request Type: GET

Request Parameters: None

Successful Response (200 OK): The response contains a list of halls associated with the company.

Example Response:

{
  "status": 1,
  "hall_list": [
    {
      "id": 1,
      "name": "Main Hall",
      "description": "Main manufacturing hall",
      "meta_frontend": {},
      "active": true
    }
  ]
}

Response Fields:

status (integer): Indicates the success of the request. 1 for success, 0 for failure.
hall_list (array): A list of halls associated with the company.
- id (integer): Unique identifier for the hall.
- name (string): Name of the hall.
- description (string): Description of the hall.
- meta_frontend (object): Additional frontend metadata.
- active (boolean): Indicates if the hall is active.

Error Responses:

404 Not Found: No halls exist for the company.

{
  "status": 0,
  "message": "No halls found."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'GET' '<BaseURL>/v2/halls/' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here'

This API ensures that users can retrieve all halls associated with their company in a structured and authenticated manner.

2. Retrieve Specific Hall

Endpoint: GET /v2/halls/{id}

Description:
This API retrieves details of a specific hall identified by its unique id. The user must have the necessary permissions to access the hall.

Authentication:
This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)

Request Type: GET

Request Parameters:

id (integer) – The unique identifier of the hall to retrieve.

Successful Response (200 OK):
The response contains detailed information about the requested hall.

Example Response:

{
  "id": 1,
  "name": "Main Hall",
  "description": "Main manufacturing hall",
  "meta_frontend": {},
  "active": true
}

Response Fields:

id (integer): Unique identifier for the hall.
name (string): Name of the hall.
description (string): Description of the hall.
meta_frontend (object): Additional frontend metadata.
active (boolean): Indicates if the hall is active.

Error Responses:

404 Not Found: The requested hall does not exist.

{
  "status": 0,
  "message": "Hall not found."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'GET' '<BaseURL>/v2/halls/1' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here'

This API ensures that users can retrieve detailed information about a specific hall using its unique identifier in a structured and authenticated manner.

3. Retrieve All Machines

Endpoint: GET /v2/machine

Description:
This API retrieves all machines associated with the authenticated user's company. The user must have the necessary permissions to access the machines.

Authentication:
This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)

Request Type: GET

Request Parameters:
None. However, an optional query parameter can be added:

all (boolean, optional) – If set to true, includes inactive machines in the response.

Successful Response (200 OK):
The response contains a list of machines associated with the company.

Example Response:

jsonCopyEdit{
  "status": 1,
  "machine_list": [
    {
      "id": 1,
      "name": "Machine A",
      "public_id": "MACH-001",
      "description": "High precision lathe",
      "current": 5.2,
      "voltage": 220,
      "meta_frontend": {},
      "meta_backend": {},
      "active": true,
      "ratings": 4.5,
      "created_at": "2025-02-25",
      "hall": { "id": 1, "name": "Main Hall" },
      "tag_list": [{ "id": 11, "name": "Tag1" }],
      "ava": [{ "id": 21, "name": "AVA1", "mac_id": "MAC123", "priority": 1 }],
      "shift_group": { "id": 31, "name": "Day Shift" }
    }
  ]
}

Response Fields:

status (integer): 1 for success, 0 for failure.
machine_list (array): A list of machines associated with the company.
- id (integer): Unique identifier for the machine.
- name (string): Name of the machine.
- public_id (string): Public identifier of the machine.
- description (string): Description of the machine.
- current (float): Current measured in amperes.
- voltage (integer): Voltage level of the machine.
- meta_frontend (object): Additional frontend metadata.
- meta_backend (object): Additional backend metadata.
- active (boolean): Whether the machine is active.
- ratings (float): Machine performance rating.
- created_at (string): Machine creation date in YYYY-MM-DD format.
- hall (object): The hall where the machine is located.
  - id (integer): Hall ID.
  - name (string): Hall name.
- tag_list (array): Tags assigned to the machine.
  - id (integer): Tag ID.
  - name (string): Tag name.
- ava (array): Machine availability details.
  - id (integer): Availability ID.
  - name (string): Availability name.
  - mac_id (string): Machine identifier.
  - priority (integer): Priority level.
- shift_group (object): Machine shift group details.
  - id (integer): Shift group ID.
  - name (string): Shift group name.

Error Responses:

404 Not Found: No machines exist for the company.

{
  "status": 0,
  "message": "No machines found."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'GET' '<BaseURL>/v2/machine/' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here'

This API allows users to retrieve a comprehensive list of machines associated with their company, including details such as hall location, tags, and availability.

4. Retrieve All Timeline Reasons

Endpoint: GET /v2/timeline_reason

Description:
This API retrieves all timeline reasons associated with the current company. These reasons are used to track machine downtimes, operational issues, and other significant events.

Authentication:
This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)

Request Type: GET

Request Parameters:
None.

Successful Response (200 OK):
The response contains a list of timeline reasons associated with the company.

Example Response:

{
  "status": 1,
  "timeline_reason_list": [
    {
      "id": 1,
      "name": "Downtime",
      "level": "Critical",
      "reason": "Power failure",
      "meta_backend": {},
      "meta_frontend": {}
    }
  ]
}

Response Fields:

status (integer): 1 for success, 0 for failure.
timeline_reason_list (array): A list of timeline reasons available for the company.
- id (integer): Unique identifier for the timeline reason.
- name (string): Name of the timeline reason.
- level (string): The severity level of the reason (e.g., Critical, Warning).
- reason (string): A brief explanation of the timeline reason.
- meta_backend (object): Additional metadata for backend usage.
- meta_frontend (object): Additional metadata for frontend usage.

Error Responses:

404 Not Found: No timeline reasons exist for the company.

{
  "status": 0,
  "message": "No timeline reasons are set. Get started by adding them from Admin Panel."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'GET' '<BaseURL>/v2/timeline_reason/' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here'

This API enables users to retrieve a list of all timeline reasons configured for their company, ensuring better tracking of machine performance and operational events

5. Assign Timeline Reason

Endpoint: POST /v2/timeline/reason_assign

Description:
This API assigns a timeline reason to a machine, allowing users to track specific operational events such as machine downtimes or other predefined reasons. The assignment can be used for labeling machine status changes in real-time or for historical adjustments.

Authentication:
This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)
Content-Type: application/json (Required for POST requests)

Request Type: POST

Request Body:
The request body should contain a list of machine timeline reason assignments.

Example Request Body:

{
  "data": [
    {
      "machine_id": 1,
      "timeline_reason_id": 1,
      "operation": "add",
      "idx": 1
    }
  ]
}

Request Fields:

data (array): List of assignments.
- machine_id (integer): The machine to which the reason is assigned.
- timeline_reason_id (integer): The timeline reason ID being assigned.
- operation (string): The operation to be performed. Allowed values: "add", "modify", "delete".
- idx (integer): The timeline entry index (used to reference a specific time range for assignment).

Successful Response (200 OK):

{
  "message": "Successfully assigned timeline reason.",
  "status": 1
}

Response Fields:

message (string): Success confirmation message.
status (integer): 1 for success, 0 for failure.

Error Responses:

400 Bad Request: Invalid request format.

{
  "status": 0,
  "message": "Invalid request data."
}

401 Unauthorized: Invalid authentication credentials.

{
  "status": 0,
  "message": "Unauthorized access."
}

404 Not Found: The specified machine or timeline reason does not exist.

{
  "status": 0,
  "message": "Machine with ID 1 not found for the current company."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'POST' '<BaseURL>/v2/timeline/reason_assign' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
        "data": [
          {
            "machine_id": 1,
            "timeline_reason_id": 1,
            "operation": "add",
            "idx": 1
          }
        ]
      }'

This API provides a structured method to assign, modify, or delete timeline reasons for machines, ensuring accurate tracking of machine events.

6. Preset Timeline Reason

Endpoint: POST /v2/timeline/reason_preset

Description:
This API allows users to preset a timeline reason for a machine. It is useful for real-time or pre-scheduled event labeling, ensuring accurate machine activity tracking.

Authentication:
This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)
Content-Type: application/json (Required for POST requests)

Request Type: POST

Request Body:
The request body should contain the details of the machine and the timeline reason being assigned.

Example Request Body:

{
  "machine_id": 1,
  "reason_id": 1,
  "meta_frontend": {},
  "idx": 1
}

Request Fields:

machine_id (integer): The machine to which the timeline reason is assigned.
reason_id (integer): The ID of the timeline reason being preset.
meta_frontend (object, optional): Additional frontend metadata.
idx (integer): The timeline entry index for reference.

Successful Response (200 OK):

{
  "status": 1,
  "message": "Live Timeline Reason Set Successfully"
}

Response Fields:

status (integer): 1 for success, 0 for failure.
message (string): Success confirmation message.

Error Responses:

400 Bad Request: Missing required fields or incorrect request format.

{
  "status": 0,
  "message": "Machine ID is required."
}

{
  "status": 0,
  "message": "Reason ID is required."
}

401 Unauthorized: Invalid authentication credentials.

{
  "status": 0,
  "message": "Unauthorized access."
}

404 Not Found: The specified machine or timeline reason does not exist.

{
  "status": 0,
  "message": "Machine with ID 1 not found for the current company."
}

{
  "status": 0,
  "message": "Timeline reason with ID 1 not found for the current company."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'POST' '<BaseURL>/v2/timeline/reason_preset' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
        "machine_id": 1,
        "reason_id": 1,
        "meta_frontend": {},
        "idx": 1
      }'

This API ensures efficient pre-labeling of machine activity, making it easier to manage operational logs and analytics.

7. Retrieve Machine Data

Endpoint: POST /v2/analytics/day

Description:
This API retrieves machine-specific analytics data for a given date, including energy consumption, anomalies, cycles, timeline data, and pulse information. It supports multiple machines in a single request.

Authentication:
This endpoint requires authentication using either a Bearer Token or an X-API-KEY.

Required Headers:

accept: Must be application/json
X-API-KEY: API Access Key for authentication
Authorization: Bearer token (if using JWT authentication)
Content-Type: application/json (Required for POST requests)

Request Type: POST

Query Parameters:

async (boolean, optional): Determines if the request should be processed asynchronously. Default: false.
csv_format (boolean, optional): Determines if the response should be in CSV format. Default: false.

Request Body:
The request body should contain a list of machine IDs along with various data flags.

Example Request Body:

{
  "machine_list": [1],
  "date": "2025-02-24",
  "energy_data": true,
  "anomalies": true,
  "cycles": true,
  "timeline": true,
  "pulse": true,
  "window_period": "1m",
  "timeline_reason": true
}

Request Fields:

machine_list (array): List of machine IDs to retrieve data for.
date (string, format: YYYY-MM-DD): The date for which data is requested.
energy_data (boolean, optional): Whether to include energy consumption data.
anomalies (boolean, optional): Whether to include anomaly detection results.
cycles (boolean, optional): Whether to include cycle analysis data.
timeline (boolean, optional): Whether to include timeline details.
pulse (boolean, optional): Whether to include pulse data.
window_period (string, optional): Time window for aggregation (e.g., "1m" for 1 minute).
timeline_reason (boolean, optional): Whether to include timeline reason data.

Successful Response (200 OK):
The response contains detailed analytics data for each requested machine.

Example Response:

{
  "machine_dict": {
    "1": {
      "id": 1,
      "name": "243 - Kunzmann WF650",
      "hall": {
        "id": 1,
        "name": "Fräserei"
      },
      "last_heartbeat": "2025-02-25 01:26:14",
      "day_data": {
        "anomalies": 0,
        "availability": 0.2705,
        "energy_consumption": 0.13,
        "energy_wastage": 0.08,
        "idle_duration": 28786.39,
        "oee": 0.0695,
        "off_duration": 0,
        "on_duration": 39458.95,
        "performance": 0.2705,
        "production_duration": 10672.56,
        "quality": 0.95,
        "rating_energy_consumption": 0.11,
        "total_duration": 39458.95
      },
      "anomalies": {
        "columns": ["_time", "duration_sec", "probability"],
        "data": []
      },
      "cycles": {
        "columns": ["_time", "duration_sec", "probability"],
        "data": []
      },
      "pulse": {
        "1": {
          "columns": ["_time", "std"],
          "data": [
            [1740351600, 9.04],
            [1740351660, 9.06]
          ]
        }
      },
      "live_timeline_reason": {
        "can_set": true,
        "created_at": "2025-02-24 15:36:17",
        "idx": 41165,
        "is_set": false
      }
    }
  }
}

Response Fields:

machine_dict (object): A dictionary of machine data, where the key is the machine ID.
- id (integer): Machine ID.
- name (string): Machine name.
- hall (object): Information about the machine's hall.
  - id (integer): Hall ID.
  - name (string): Hall name.
- last_heartbeat (string, format: YYYY-MM-DD HH:MM:SS): Last recorded activity timestamp.
- day_data (object): Aggregated analytics for the machine.
  - anomalies (integer): Number of anomalies detected.
  - availability (float): Availability percentage.
  - energy_consumption (float): Total energy consumed.
  - energy_wastage (float): Energy wasted.
  - idle_duration (float): Time spent idle (in seconds).
  - oee (float): Overall Equipment Effectiveness.
  - off_duration (float): Time spent in OFF state (in seconds).
  - on_duration (float): Time spent in ON state (in seconds).
  - performance (float): Performance percentage.
  - production_duration (float): Time spent in production (in seconds).
  - quality (float): Quality percentage.
  - total_duration (float): Total operation duration.
- anomalies (object): Anomaly detection results.
  - columns (array): Column names.
  - data (array): Anomalous event data.
- cycles (object): Cycle detection data.
  - columns (array): Column names.
  - data (array): Cycle information.
- pulse (object): Machine pulse data over time.
  - {sensor_id} (object): Data for a specific sensor.
    - columns (array): Column names.
    - data (array): Time-series pulse data.
- live_timeline_reason (object): Information about live timeline reasons.
  - can_set (boolean): Whether a reason can be set.
  - created_at (string, format: YYYY-MM-DD HH:MM:SS): Creation timestamp.
  - idx (integer): Timeline index.
  - is_set (boolean): Whether a reason is currently set.

Error Responses:

400 Bad Request: Missing required fields or incorrect request format.

{
  "status": 0,
  "message": "Invalid request data."
}

401 Unauthorized: Invalid authentication credentials.

{
  "status": 0,
  "message": "Unauthorized access."
}

404 Not Found: No data available for the requested machine(s).

{
  "status": 0,
  "message": "No data found for the provided machine ID(s)."
}

500 Internal Server Error: Unexpected server error.

{
  "status": 0,
  "message": "An unexpected error occurred."
}

Example cURL Request:

curl -X 'POST' '<BaseURL>/v2/analytics/day' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: your_api_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
        "machine_list": [1],
        "date": "2025-02-24",
        "energy_data": true,
        "anomalies": true,
        "cycles": true,
        "timeline": true,
        "pulse": true,
        "window_period": "1m",
        "timeline_reason": true
      }'

This API provides detailed insights into machine performance, anomalies, and energy consumption, aiding in predictive maintenance and efficiency tracking.

Security Considerations

Limited Scope: API-Access Keys provide access only to the endpoints listed in this documentation.
Key Protection: Never expose the API-Access Key in client-side applications or logs.
Regeneration & Revocation: Expired or compromised keys should be revoked and regenerated via the Admin Panel.

Ensure that your application securely manages API-Access Keys to prevent unauthorized access.

REST API Documentation

Overview

Authentication

Example Authorization Header

Generating an API-Access Key

Accessible APIs

Authentication

Headers

Base URL

Endpoints

1. Retrieve All Halls

2. Retrieve Specific Hall

3. Retrieve All Machines

4. Retrieve All Timeline Reasons

5. Assign Timeline Reason

6. Preset Timeline Reason

7. Retrieve Machine Data

Security Considerations