Resources

Units

A unit is one refrigeration system, display case, cold room or other piece of equipment with its own QR or NFC tag, and a site is where it stands. A unit has master data from its nameplate, its refrigerant and charge with the CO2 equivalent worked out, and its active components. The API reaches the units the organisation owns and, for a service company, the units where it has an active grant.

GET/sitesList sites
GET/unitsList units
POST/unitsCreate unit
GET/units/{unit}Get unit
PATCH/units/{unit}Update unit

The unit model

Properties

id string (uuid)
public_id string

The Maci ID, such as MC-0482.
name string
category string
status string

One of active, decommissioned
organization_id string (uuid)

The owner.
site_id string (uuid), nullable
parent_unit_id string (uuid), nullable
manufacturer string, nullable
model string, nullable
serial_no string, nullable
production_year integer, nullable
installation_year integer, nullable
system_type string, nullable
refrigerant string, nullable

The designation of the refrigerant.
charge_kg number, nullable
co2e_tonnes number, nullable

The charge in tonnes of CO2 equivalent.
charge_is_on_parent boolean

true when refrigerant and charge are those of the central system.
premium boolean

Whether the unit has Premium. The API only reaches units that have it.
hermetically_sealed boolean
leak_detection_system boolean
temp_min_c number, nullable
temp_max_c number, nullable
supply_voltage_v integer, nullable
supply_phases integer, nullable
supply_frequency_hz integer, nullable
rated_current_a number, nullable

Rated current in A, from the nameplate.
power_kw number, nullable

Power in kW, from the nameplate.
ps_high_bar number, nullable

Allowable pressure PS on the high side, in bar.
ps_low_bar number, nullable

Allowable pressure PS on the low side, in bar.
climate_class string, nullable
created_at string (date-time)
updated_at string (date-time)
components array

Active components. Only there when one unit is fetched.

See the component model.

The site model

Properties

id string (uuid)
organization_id string (uuid)
name string
address string, nullable
created_at string (date-time)
updated_at string (date-time)

GET/sites

List sites

The organisation's sites.

The organisation's own sites. For a service company also the sites where the company has access to units.

Scope: units:read

Query parameters

limit integer

Records per page. At most 100, default 50.
cursor string

The value of next_cursor from the page before.

Response

200 A page of sites. The fields are those of the site model.

Request

GET/sites

curl https://api.maci.energy/v1/sites \
  -H "Authorization: Bearer $MACI_API_KEY"

const response = await fetch('https://api.maci.energy/v1/sites', {
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.maci.energy/v1/sites",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.maci.energy/v1/sites', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "data": [
    {
      "id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
      "organization_id": "a3f1c2d4-6b8e-4f0a-9c1d-2e3f4a5b6c7d",
      "name": "Main store",
      "address": "Example Street 1, 2100 Copenhagen",
      "created_at": "2026-10-30T09:15:00Z",
      "updated_at": "2026-10-30T09:15:00Z"
    }
  ],
  "next_cursor": null
}

GET/units

List units

The units the organisation has access to.

Scope: units:read

Query parameters

site_id string (uuid)

Only units at this site.
status string

Only units with this status, active or decommissioned.

One of active, decommissioned
updated_since string (date-time)

Only units changed at or after this time.
limit integer

Records per page. At most 100, default 50.
cursor string

The value of next_cursor from the page before.

Response

200 A page of units, without components. The fields are those of the unit model.

Request

GET/units

curl https://api.maci.energy/v1/units \
  -H "Authorization: Bearer $MACI_API_KEY"

const response = await fetch('https://api.maci.energy/v1/units', {
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.maci.energy/v1/units",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.maci.energy/v1/units', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "data": [
    {
      "id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
      "public_id": "MC-0482",
      "name": "Cold room 2",
      "category": "cold_room",
      "status": "active",
      "organization_id": "a3f1c2d4-6b8e-4f0a-9c1d-2e3f4a5b6c7d",
      "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
      "parent_unit_id": null,
      "manufacturer": "Example Ltd",
      "model": "K-100",
      "serial_no": "SN-204871",
      "production_year": 2019,
      "installation_year": 2020,
      "system_type": "split",
      "refrigerant": "R449A",
      "charge_kg": 42,
      "co2e_tonnes": 58.7,
      "charge_is_on_parent": false,
      "premium": true,
      "hermetically_sealed": false,
      "leak_detection_system": false,
      "temp_min_c": 0,
      "temp_max_c": 4,
      "supply_voltage_v": 400,
      "supply_phases": 3,
      "supply_frequency_hz": 50,
      "rated_current_a": 12.4,
      "power_kw": 5.5,
      "ps_high_bar": 28,
      "ps_low_bar": 19,
      "climate_class": "N",
      "created_at": "2026-10-30T09:15:00Z",
      "updated_at": "2026-10-30T09:15:00Z",
      "components": [
        {
          "id": "c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66",
          "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
          "type": "compressor",
          "label": "Compressor 1",
          "quantity": 1,
          "manufacturer": "Example Ltd",
          "model": "K-100",
          "serial_no": "SN-204871",
          "status": "active",
          "installed_at": "2026-10-30",
          "removed_at": null,
          "replaces_component_id": null,
          "attributes": {},
          "custom_fields": null,
          "note": null,
          "created_at": "2026-10-30T09:15:00Z",
          "updated_at": "2026-10-30T09:15:00Z"
        }
      ]
    }
  ],
  "next_cursor": null
}

POST/units

Create unit

Create a unit.

The unit is created at one of the organisation's sites. A service company can create at a customer's site when its grant includes creation.

Scope: units:write

Headers

Idempotency-Key string

A value of your own choosing, so that a repeated call does not create two records.

Body

site_id string (uuid) required

The site the unit is at.
name string required

The name of the unit.
category string required

One of display_case, freezer_case, plug_in_cabinet, cold_room, freezer_room, blast_chiller, condensing_unit, compressor_rack, chiller, heat_pump, other
tag_code string, nullable

The code on a pre-printed label that is not in use. The unit gets the Maci ID of the label. Not in the sandbox.
manufacturer string, nullable
model string, nullable
serial_no string, nullable
production_year integer, nullable
installation_year integer, nullable
system_type string, nullable

One of plug_in, split, central
parent_unit_id string (uuid), nullable

The central system the unit is connected to. It has to be one of the owner's units.
refrigerant string, nullable

The designation of the refrigerant, such as R449A. See GET /refrigerants.
refrigerant_id string (uuid), nullable

The ID of the refrigerant. Can be used instead of refrigerant.
charge_kg number, nullable

The charge in kg.
hermetically_sealed boolean
leak_detection_system boolean
temp_min_c number, nullable
temp_max_c number, nullable
supply_voltage_v integer, nullable
supply_phases integer, nullable

One of 1, 3
supply_frequency_hz integer, nullable

One of 50, 60
rated_current_a number, nullable

Rated current in A, from the nameplate.
power_kw number, nullable

Power in kW, from the nameplate.
ps_high_bar number, nullable

Allowable pressure PS on the high side, in bar.
ps_low_bar number, nullable

Allowable pressure PS on the low side, in bar.
climate_class string, nullable

Response

201 The unit that was created. The fields are those of the unit model.

Request

POST/units

curl -X POST https://api.maci.energy/v1/units \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Idempotency-Key: a-value-of-your-own" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
    "tag_code": "MC-0482",
    "name": "Cold room 2",
    "category": "cold_room",
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "production_year": 2019,
    "installation_year": 2020
  }'

const response = await fetch('https://api.maci.energy/v1/units', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
    'Idempotency-Key': 'a-value-of-your-own',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
    "tag_code": "MC-0482",
    "name": "Cold room 2",
    "category": "cold_room",
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "production_year": 2019,
    "installation_year": 2020
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.maci.energy/v1/units",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}", "Idempotency-Key": "a-value-of-your-own"},
    json={
        "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
        "tag_code": "MC-0482",
        "name": "Cold room 2",
        "category": "cold_room",
        "manufacturer": "Example Ltd",
        "model": "K-100",
        "serial_no": "SN-204871",
        "production_year": 2019,
        "installation_year": 2020
    },
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.maci.energy/v1/units', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
        'Idempotency-Key' => 'a-value-of-your-own',
    ],
    'json' => [
        'site_id' => '5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30',
        'tag_code' => 'MC-0482',
        'name' => 'Cold room 2',
        'category' => 'cold_room',
        'manufacturer' => 'Example Ltd',
        'model' => 'K-100',
        'serial_no' => 'SN-204871',
        'production_year' => 2019,
        'installation_year' => 2020,
    ],
]);
$data = json_decode($response->getBody(), true);

Response 201

{
  "id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
  "public_id": "MC-0482",
  "name": "Cold room 2",
  "category": "cold_room",
  "status": "active",
  "organization_id": "a3f1c2d4-6b8e-4f0a-9c1d-2e3f4a5b6c7d",
  "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
  "parent_unit_id": null,
  "manufacturer": "Example Ltd",
  "model": "K-100",
  "serial_no": "SN-204871",
  "production_year": 2019,
  "installation_year": 2020,
  "system_type": "split",
  "refrigerant": "R449A",
  "charge_kg": 42,
  "co2e_tonnes": 58.7,
  "charge_is_on_parent": false,
  "premium": true,
  "hermetically_sealed": false,
  "leak_detection_system": false,
  "temp_min_c": 0,
  "temp_max_c": 4,
  "supply_voltage_v": 400,
  "supply_phases": 3,
  "supply_frequency_hz": 50,
  "rated_current_a": 12.4,
  "power_kw": 5.5,
  "ps_high_bar": 28,
  "ps_low_bar": 19,
  "climate_class": "N",
  "created_at": "2026-10-30T09:15:00Z",
  "updated_at": "2026-10-30T09:15:00Z",
  "components": [
    {
      "id": "c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66",
      "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
      "type": "compressor",
      "label": "Compressor 1",
      "quantity": 1,
      "manufacturer": "Example Ltd",
      "model": "K-100",
      "serial_no": "SN-204871",
      "status": "active",
      "installed_at": "2026-10-30",
      "removed_at": null,
      "replaces_component_id": null,
      "attributes": {},
      "custom_fields": null,
      "note": null,
      "created_at": "2026-10-30T09:15:00Z",
      "updated_at": "2026-10-30T09:15:00Z"
    }
  ]
}

GET/units/{unit}

Get unit

Master data, refrigerant, charge and active components.

Scope: units:read

Path parameters

unit string (uuid) required

The ID of the unit.

Response

200 The unit with its active components. The fields are those of the unit model.

Request

GET/units/{unit}

curl https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11 \
  -H "Authorization: Bearer $MACI_API_KEY"

const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11', {
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
  "public_id": "MC-0482",
  "name": "Cold room 2",
  "category": "cold_room",
  "status": "active",
  "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
  "refrigerant": "R449A",
  "charge_kg": 42,
  "co2e_tonnes": 58.7,
  "components": [
    {
      "id": "c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66",
      "type": "compressor",
      "label": "Compressor 1",
      "manufacturer": "Example Ltd",
      "model": "K-100",
      "status": "active",
      "attributes": {
        "rated_current_a": 9.8,
        "motor_power_kw": 3.7
      }
    }
  ]
}

PATCH/units/{unit}

Update unit

Change master data.

Send only the fields to change.

Scope: units:write

Path parameters

unit string (uuid) required

The ID of the unit.

Body

name string

The name of the unit.
category string

One of display_case, freezer_case, plug_in_cabinet, cold_room, freezer_room, blast_chiller, condensing_unit, compressor_rack, chiller, heat_pump, other
manufacturer string, nullable
model string, nullable
serial_no string, nullable
production_year integer, nullable
installation_year integer, nullable
system_type string, nullable

One of plug_in, split, central
parent_unit_id string (uuid), nullable

The central system the unit is connected to. It has to be one of the owner's units.
refrigerant string, nullable

The designation of the refrigerant, such as R449A. See GET /refrigerants.
refrigerant_id string (uuid), nullable

The ID of the refrigerant. Can be used instead of refrigerant.
charge_kg number, nullable

The charge in kg.
hermetically_sealed boolean
leak_detection_system boolean
temp_min_c number, nullable
temp_max_c number, nullable
supply_voltage_v integer, nullable
supply_phases integer, nullable

One of 1, 3
supply_frequency_hz integer, nullable

One of 50, 60
rated_current_a number, nullable

Rated current in A, from the nameplate.
power_kw number, nullable

Power in kW, from the nameplate.
ps_high_bar number, nullable

Allowable pressure PS on the high side, in bar.
ps_low_bar number, nullable

Allowable pressure PS on the low side, in bar.
climate_class string, nullable

Response

200 The unit after the change. The fields are those of the unit model.

Request

PATCH/units/{unit}

curl -X PATCH https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11 \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cold room 2",
    "category": "cold_room",
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "production_year": 2019
  }'

const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Cold room 2",
    "category": "cold_room",
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "production_year": 2019
  }),
});
const data = await response.json();

import os
import requests

response = requests.patch(
    "https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
    json={
        "name": "Cold room 2",
        "category": "cold_room",
        "manufacturer": "Example Ltd",
        "model": "K-100",
        "serial_no": "SN-204871",
        "production_year": 2019
    },
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
    'json' => [
        'name' => 'Cold room 2',
        'category' => 'cold_room',
        'manufacturer' => 'Example Ltd',
        'model' => 'K-100',
        'serial_no' => 'SN-204871',
        'production_year' => 2019,
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
  "public_id": "MC-0482",
  "name": "Cold room 2",
  "category": "cold_room",
  "status": "active",
  "organization_id": "a3f1c2d4-6b8e-4f0a-9c1d-2e3f4a5b6c7d",
  "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30",
  "parent_unit_id": null,
  "manufacturer": "Example Ltd",
  "model": "K-100",
  "serial_no": "SN-204871",
  "production_year": 2019,
  "installation_year": 2020,
  "system_type": "split",
  "refrigerant": "R449A",
  "charge_kg": 42,
  "co2e_tonnes": 58.7,
  "charge_is_on_parent": false,
  "premium": true,
  "hermetically_sealed": false,
  "leak_detection_system": false,
  "temp_min_c": 0,
  "temp_max_c": 4,
  "supply_voltage_v": 400,
  "supply_phases": 3,
  "supply_frequency_hz": 50,
  "rated_current_a": 12.4,
  "power_kw": 5.5,
  "ps_high_bar": 28,
  "ps_low_bar": 19,
  "climate_class": "N",
  "created_at": "2026-10-30T09:15:00Z",
  "updated_at": "2026-10-30T09:15:00Z",
  "components": [
    {
      "id": "c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66",
      "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
      "type": "compressor",
      "label": "Compressor 1",
      "quantity": 1,
      "manufacturer": "Example Ltd",
      "model": "K-100",
      "serial_no": "SN-204871",
      "status": "active",
      "installed_at": "2026-10-30",
      "removed_at": null,
      "replaces_component_id": null,
      "attributes": {},
      "custom_fields": null,
      "note": null,
      "created_at": "2026-10-30T09:15:00Z",
      "updated_at": "2026-10-30T09:15:00Z"
    }
  ]
}