An Introduction to the Public API

Our Public API is a HTTP API that can be used to interact with your organization within the Hark Platform programmatically. The Public API allows you to retrieve contextual information about the Sites, Equipment and Points deployed in your organization, read Point metrics and manage your Equipment Alarms.

Useful Links / Information

Name	Link
Public API Endpoint Documentation (Swagger)	https://platform.harksys.com/public-api/docs
Public API HTTP Host	https://platform.harksys.com/public-api
Authentiction Header Name	x-api-key

API Authentication

Authentication with the Public API is performed by sending an API key through a header named x-api-key with each of your requests. API keys can be created under the user settings menu when authenticated with the Hark Platform, and are directly tied to your user.

The permissions you have as a user of the Platform will be applied to your API key, and any actions you perform, such as closing an Alarm, will be represented by your user within the organization.

Rate Limits

Requests to the Public API are rate limited to protect the Hark Platform from the service being abused, such as a DDoS attack. Requests are limited to 100 requests per 60 seconds, and when hitting a rate limit, requests will respond with a 429 response code.

Usage Guidance

When using the Public API it is advised to consider your usage of the endpoints that we provide, and how you can achieve what you need in the fewest requests with the most direct access to your data. Where possible, cache responses locally to reduce redundant calls and improve performance. Use pagination when retrieving large datasets, and request only the data you need by using appropriate filters and fields. Get-by-Id endpoints provide direct access to an item, as opposed to requesting a page of items mupltiple times.

It is not recommended to use this API to get a full history of your Point metrics or Alarms. Get in touch if you'd like to talk to us about using our Public API, and please share what you'd like to achieve.

Request Example

The following examples make a request to the Public API to retrieve an Equipment's Point's metrics between 00:00 and 00:30 on the 17th of July 2025 (UTC). You'll need to fill in your Equipment ID, Point ID and API key.

curl

curl -i -X "GET" "https://platform.harksys.com/public-api/v1/equipment/{equipmentId}/points/{pointId}/metrics?fromUtc=2025-06-17T00%3A00%3A00Z&toUtc=2025-06-17T00%3A30%3A00Z" \
  -H "accept: application/json" \
  -H "x-api-key: {YOUR API KEY}"

JavaScript

const equipmentId = "your-equipment-id";
const pointId = "your-point-id";
const apiKey = "your-api-key";

const fromUtc = "2025-06-17T00:00:00Z";
const toUtc = "2025-06-17T00:30:00Z";

const url = `https://platform.harksys.com/public-api/v1/equipment/${equipmentId}/points/${pointId}/metrics?fromUtc=${encodeURIComponent(fromUtc)}&toUtc=${encodeURIComponent(toUtc)}`;

const request = await fetch(url, {
  method: "GET",
  headers: {
    "accept": "application/json",
    "x-api-key": apiKey
  }
});

if (response.status !== 200) {
  console.log(`HTTP Request Returned ${respons.status} Code`);
  return;
}

const json = await request.json();
console.log(json);

Python

import requests

equipment_id = "your-equipment-id"
point_id = "your-point-id"
api_key = "your-api-key"

params = {
    "fromUtc": "2025-06-17T00:00:00Z",
    "toUtc": "2025-06-17T00:30:00Z"
}

url = f"https://platform.harksys.com/public-api/v1/equipment/{equipment_id}/points/{point_id}/metrics"

headers = {
    "accept": "application/json",
    "x-api-key": api_key
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"HTTP Request Returned {response.status_code} Code")

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string equipmentId = "your-equipment-id";
        string pointId = "your-point-id";
        string apiKey = "your-api-key";

        string fromUtc = Uri.EscapeDataString("2025-06-17T00:00:00Z");
        string toUtc = Uri.EscapeDataString("2025-06-17T00:30:00Z");

        string url = $"https://platform.harksys.com/public-api/v1/equipment/{equipmentId}/points/{pointId}/metrics?fromUtc={fromUtc}&toUtc={toUtc}";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(
                new MediaTypeWithQualityHeaderValue("application/json"));
            client.DefaultRequestHeaders.Add("x-api-key", apiKey);

            try
            {
                HttpResponseMessage response = await client.GetAsync(url);
                response.EnsureSuccessStatusCode();

                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine("Response data:");
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException e)
            {
                Console.WriteLine("Request error:");
                Console.WriteLine(e.Message);
            }
        }
    }
}

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

public class ApiRequest {
    public static void main(String[] args) {
        String equipmentId = "your-equipment-id";
        String pointId = "your-point-id";
        String apiKey = "your-api-key";

        try {
            String fromUtc = URLEncoder.encode("2025-06-17T00:00:00Z", "UTF-8");
            String toUtc = URLEncoder.encode("2025-06-17T00:30:00Z", "UTF-8");

            String apiUrl = String.format(
                "https://platform.harksys.com/public-api/v1/equipment/%s/points/%s/metrics?fromUtc=%s&toUtc=%s",
                equipmentId, pointId, fromUtc, toUtc);

            URL url = new URL(apiUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");

            // Set headers
            conn.setRequestProperty("accept", "application/json");
            conn.setRequestProperty("x-api-key", apiKey);

            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            BufferedReader in = new BufferedReader(new InputStreamReader(
                    responseCode == 200 ? conn.getInputStream() : conn.getErrorStream()));
            String inputLine;
            StringBuilder response = new StringBuilder();

            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();

            System.out.println("Response Body:");
            System.out.println(response.toString());

        } catch (IOException e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}