# Lists, limits and versions

The rules every endpoint follows: the format, paging, repeated calls, how many calls a key may make, and how the API changes.

## Format

JSON in UTF-8. Times are ISO 8601 in UTC. IDs are UUIDs. Measurements are in SI units. Error messages are in English, or in Danish with `Accept-Language: da`.

## Lists and paging

Lists are paged with `limit` (at most 100, default 50) and `cursor`. The answer has `data` and `next_cursor`. Send `next_cursor` as `cursor` to get the next page. It is `null` on the last page.

```bash
curl https://api.maci.energy/v1/units?limit=50&cursor=eyJpZCI6IjBiNmY0YzFlIn0 \
  -H "Authorization: Bearer $MACI_API_KEY"
```

```javascript
const response = await fetch('https://api.maci.energy/v1/units?limit=50&cursor=eyJpZCI6IjBiNmY0YzFlIn0', {
  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?limit=50&cursor=eyJpZCI6IjBiNmY0YzFlIn0",
    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?limit=50&cursor=eyJpZCI6IjBiNmY0YzFlIn0', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);
```

## Repeated calls

A POST can be sent with the header `Idempotency-Key`. Sent again within 24 hours with the same value and the same body, it gets the first answer back with the header `Idempotency-Replayed: true`, and no second record is created.

Use a value that is unique to the record you are making, such as the ID it has in your own system. A network error is then safe to retry.

## Limits

Each key can make 60 calls a minute. Past that the answer is 429 with `Retry-After`. Every answer has the headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. On top of that there is a fair usage limit of 100,000 production calls a month per organisation, unless otherwise agreed. The organisation's admins are told at 80 % and at 100 %. At 200 % the keys are slowed down to 10 calls a minute until Maci has looked at the usage.

| Header | What it says |
| --- | --- |
| `X-RateLimit-Limit` | Calls a minute the key may make. |
| `X-RateLimit-Remaining` | Calls left this minute. |
| `X-RateLimit-Reset` | When the minute starts over, as a Unix time. |
| `Retry-After` | Only at 429: the seconds to wait. |

What a key and the organisation have used this month: [GET /usage](https://api.maci.energy/docs/refrigerants-and-usage.md#get-usage).

## Versions

The version is in the path. Changes that break existing integrations come in a new version, and the old one works for at least 12 months after notice.