Resources

Components

The parts of a unit: compressors, fans, valves, controllers and the rest. A component is never deleted. When it is replaced, the old one is kept with the status replaced and the replacement goes into the service history, so the unit's history stays whole.

GET/units/{unit}/componentsList components
POST/units/{unit}/componentsCreate component
PATCH/components/{component}Update component
POST/components/{component}/replaceReplace component

The component model

Properties

id string (uuid)
unit_id string (uuid)
type string
label string
quantity integer
manufacturer string, nullable
model string, nullable
serial_no string, nullable
status string

One of active, replaced, removed
installed_at string (date), nullable
removed_at string (date), nullable
replaces_component_id string (uuid), nullable

The component this one replaced.
attributes object
custom_fields object, nullable
note string, nullable
created_at string (date-time)
updated_at string (date-time)

GET/units/{unit}/components

List components

The components of a unit.

Scope: units:read

Path parameters

unit string (uuid) required

The ID of the unit.

Query parameters

include_replaced boolean

true includes earlier components.
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 components. The fields are those of the component model.

Request

GET/units/{unit}/components

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

const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/components', {
  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/components",
    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/components', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "data": [
    {
      "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/{unit}/components

Create component

Add a component.

Scope: units:write

Path parameters

unit string (uuid) required

The ID of the unit.

Headers

Idempotency-Key string

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

Body

type string required

One of compressor, condenser, evaporator, fan, expansion_device, controller, defrost_heater, sensor, valve, vessel, cabinet, maci_sensor, other
label string required

The name of the component, such as Compressor 1.
quantity integer, nullable
manufacturer string, nullable
model string, nullable
serial_no string, nullable
installed_at string (date), nullable
note string, nullable
attributes object, nullable

The type's own fields, such as rated_current_a and motor_power_kw for a compressor. Unknown fields are refused with 422.
custom_fields object, nullable

Fields of your own, as name and text. At most 20.

Response

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

Request

POST/units/{unit}/components

curl -X POST https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/components \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Idempotency-Key: a-value-of-your-own" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "fan",
    "label": "Evaporator fan 1",
    "quantity": 2,
    "attributes": {
      "placement": "evaporator",
      "motor_type": "EC",
      "power_w": 38
    }
  }'

const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/components', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
    'Idempotency-Key': 'a-value-of-your-own',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "fan",
    "label": "Evaporator fan 1",
    "quantity": 2,
    "attributes": {
      "placement": "evaporator",
      "motor_type": "EC",
      "power_w": 38
    }
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/components",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}", "Idempotency-Key": "a-value-of-your-own"},
    json={
        "type": "fan",
        "label": "Evaporator fan 1",
        "quantity": 2,
        "attributes": {
            "placement": "evaporator",
            "motor_type": "EC",
            "power_w": 38
        }
    },
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/components', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
        'Idempotency-Key' => 'a-value-of-your-own',
    ],
    'json' => [
        'type' => 'fan',
        'label' => 'Evaporator fan 1',
        'quantity' => 2,
        'attributes' => [
            'placement' => 'evaporator',
            'motor_type' => 'EC',
            'power_w' => 38,
        ],
    ],
]);
$data = json_decode($response->getBody(), true);

Response 201

{
  "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"
}

PATCH/components/{component}

Update component

Change a component.

Send only the fields to change. A component that is replaced or removed cannot be changed (409).

Scope: units:write

Path parameters

component string (uuid) required

The ID of the component.

Body

label string

The name of the component, such as Compressor 1.
quantity integer, nullable
manufacturer string, nullable
model string, nullable
serial_no string, nullable
installed_at string (date), nullable
note string, nullable
attributes object, nullable

The type's own fields, such as rated_current_a and motor_power_kw for a compressor. Unknown fields are refused with 422.
custom_fields object, nullable

Fields of your own, as name and text. At most 20.

Response

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

Request

PATCH/components/{component}

curl -X PATCH https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66 \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Compressor 1",
    "quantity": 1,
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "installed_at": "2026-10-30"
  }'

const response = await fetch('https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "Compressor 1",
    "quantity": 1,
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "installed_at": "2026-10-30"
  }),
});
const data = await response.json();

import os
import requests

response = requests.patch(
    "https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
    json={
        "label": "Compressor 1",
        "quantity": 1,
        "manufacturer": "Example Ltd",
        "model": "K-100",
        "serial_no": "SN-204871",
        "installed_at": "2026-10-30"
    },
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
    'json' => [
        'label' => 'Compressor 1',
        'quantity' => 1,
        'manufacturer' => 'Example Ltd',
        'model' => 'K-100',
        'serial_no' => 'SN-204871',
        'installed_at' => '2026-10-30',
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "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"
}

POST/components/{component}/replace

Replace component

Replace a component.

The new component gets the type of the old one. The old one is kept with the status replaced, and the replacement is in the service history.

Scope: units:write

Path parameters

component string (uuid) required

The ID of the component.

Headers

Idempotency-Key string

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

Body

label string required

The name of the component, such as Compressor 1.
quantity integer, nullable
manufacturer string, nullable
model string, nullable
serial_no string, nullable
installed_at string (date), nullable
note string, nullable
attributes object, nullable

The type's own fields, such as rated_current_a and motor_power_kw for a compressor. Unknown fields are refused with 422.
custom_fields object, nullable

Fields of your own, as name and text. At most 20.
service_text string, nullable

Text for the service note about the replacement.

Response

201 The new component. The fields are those of the component model.

Request

POST/components/{component}/replace

curl -X POST https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66/replace \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Idempotency-Key: a-value-of-your-own" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Compressor 1",
    "quantity": 1,
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "installed_at": "2026-10-30",
    "attributes": {}
  }'

const response = await fetch('https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66/replace', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
    'Idempotency-Key': 'a-value-of-your-own',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "Compressor 1",
    "quantity": 1,
    "manufacturer": "Example Ltd",
    "model": "K-100",
    "serial_no": "SN-204871",
    "installed_at": "2026-10-30",
    "attributes": {}
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66/replace",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}", "Idempotency-Key": "a-value-of-your-own"},
    json={
        "label": "Compressor 1",
        "quantity": 1,
        "manufacturer": "Example Ltd",
        "model": "K-100",
        "serial_no": "SN-204871",
        "installed_at": "2026-10-30",
        "attributes": {}
    },
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.maci.energy/v1/components/c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66/replace', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
        'Idempotency-Key' => 'a-value-of-your-own',
    ],
    'json' => [
        'label' => 'Compressor 1',
        'quantity' => 1,
        'manufacturer' => 'Example Ltd',
        'model' => 'K-100',
        'serial_no' => 'SN-204871',
        'installed_at' => '2026-10-30',
        'attributes' => [],
    ],
]);
$data = json_decode($response->getBody(), true);

Response 201

{
  "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": "8d1f3a2c-5b4e-4c7d-9e0f-1a2b3c4d5e6f",
  "attributes": {},
  "custom_fields": null,
  "note": null,
  "created_at": "2026-10-30T09:15:00Z",
  "updated_at": "2026-10-30T09:15:00Z"
}