# Service

A unit's service history: visits, repairs, fault reports and notes, from the app and from your own systems.

## The service entry model

- `id` (string (uuid))
- `unit_id` (string (uuid))
- `component_id` (string (uuid), nullable)
- `type` (string) One of `service`, `repair`, `replacement`, `addition`, `inspection`, `other`.
- `performed_at` (string (date-time))
- `text` (string, nullable)
- `company` (string, nullable): The company that did the work.
- `created_at` (string (date-time))

## List service entries

`GET /units/{unit}/service-entries` · scope `service:read`

Service history.

### Path parameters

- `unit` (string (uuid), required): The ID of the unit.

### Query parameters

- `limit` (integer): Records per page. At most 100, default 50.
- `cursor` (string): The value of `next_cursor` from the page before.

### Request

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

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

### Response 200

A page of service notes. The fields are those of the service entry model.

```json
{
  "data": [
    {
      "id": "bd58f66a-5f7e-494b-a81b-d5429bd71ba2",
      "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
      "component_id": null,
      "type": "service",
      "performed_at": "2026-10-30T09:15:00Z",
      "text": "Cleaned the condenser and checked the fans.",
      "company": "Example Cooling ApS",
      "created_at": "2026-10-30T09:15:00Z"
    }
  ],
  "next_cursor": null
}
```

## Create service entry

`POST /units/{unit}/service-entries` · scope `service:write`

New service note.

### 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 (JSON)

- `type` (string, required): Replacements and additions are written by the system when a component changes. One of `service`, `repair`, `inspection`, `other`.
- `text` (string, required)
- `performed_at` (string (date-time), nullable): When the work was done. The default is now.

### Request

```bash
curl -X POST https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/service-entries \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Idempotency-Key: a-value-of-your-own" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "service",
    "text": "Cleaned the condenser and checked the fans.",
    "performed_at": "2026-10-30T09:15:00Z"
  }'
```

```javascript
const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/service-entries', {
  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": "service",
    "text": "Cleaned the condenser and checked the fans.",
    "performed_at": "2026-10-30T09:15:00Z"
  }),
});
const data = await response.json();
```

```python
import os
import requests

response = requests.post(
    "https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/service-entries",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}", "Idempotency-Key": "a-value-of-your-own"},
    json={
        "type": "service",
        "text": "Cleaned the condenser and checked the fans.",
        "performed_at": "2026-10-30T09:15:00Z"
    },
)
data = response.json()
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/service-entries', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
        'Idempotency-Key' => 'a-value-of-your-own',
    ],
    'json' => [
        'type' => 'service',
        'text' => 'Cleaned the condenser and checked the fans.',
        'performed_at' => '2026-10-30T09:15:00Z',
    ],
]);
$data = json_decode($response->getBody(), true);
```

### Response 201

The service note that was created. The fields are those of the service entry model.

```json
{
  "id": "bd58f66a-5f7e-494b-a81b-d5429bd71ba2",
  "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
  "component_id": null,
  "type": "service",
  "performed_at": "2026-10-30T09:15:00Z",
  "text": "Cleaned the condenser and checked the fans.",
  "company": "Example Cooling ApS",
  "created_at": "2026-10-30T09:15:00Z"
}
```