# Quickstart

From no key to your first answer in a few minutes: make a key in the app, call the API, and read what comes back.

## Get an API key

An admin of your organisation makes keys in the app under [Konto → API-nøgler](https://app.maci.energy/organization/api-keys). Give the key a name, choose the scopes it needs, and choose sandbox or production. The key is shown once, when it is made, so put it in your secret store straight away.

Start with a sandbox key. It starts with `maci_sandbox_` and works on test data of your own, a site and two units, so you can build without touching the real units. A production key starts with `maci_live_`.

The examples here read the key from the environment variable `MACI_API_KEY`:

```bash
export MACI_API_KEY="maci_sandbox_..."
```

## Make your first call

List the units the key can reach. Every call goes to `https://api.maci.energy/v1` with the key in the header `Authorization: Bearer ...`.

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

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

```python
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()
```

```php
$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);
```

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

## Read the answer

A list comes as `data` and `next_cursor`. When `next_cursor` is not `null`, send it as `cursor` to get the next page. Times are ISO 8601 in UTC, IDs are UUIDs, and measurements are in SI units.

The header `Maci-Environment` says whether the answer came from the sandbox or production, and the `X-RateLimit-*` headers how many calls the key has left this minute.

## Next steps

- [Authentication](https://api.maci.energy/docs/authentication.md): Keys, scopes, the sandbox and what a key can reach.
- [Units](https://api.maci.energy/docs/units.md): Read and change units, the heart of the API.
- [Webhooks](https://api.maci.energy/docs/webhooks.md): Get alarms and invoice bases the moment they happen.
- [Errors](https://api.maci.energy/docs/errors.md): What each status means, and how to handle it.