Lists, limits and versions

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.

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

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();

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

$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.

What a key and the organisation have used this month: 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.