# Maci API

> Give your own systems your units, components, service history, F-gas log, alarms and invoice bases, and get alarms and approved invoice bases the moment they happen.

Base address: https://api.maci.energy/v1. Every call takes an API key in the header `Authorization: Bearer ...`; keys are made in the app. Answers are JSON. The whole documentation as one file: https://api.maci.energy/llms-full.txt. The OpenAPI 3.1 description: https://api.maci.energy/openapi.yaml (YAML) and https://api.maci.energy/openapi.json (JSON).

## Guides

- [Introduction](https://api.maci.energy/docs.md): what the API covers, the base address and where to start
- [What you can build](https://api.maci.energy/docs/what-you-can-build.md): Maci Intelligence watches each refrigeration system and warns before it breaks down. The API and the webhooks take what it finds, and the data around each unit, into the systems your people already work in.
- [Quickstart](https://api.maci.energy/docs/quickstart.md): 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.
- [Authentication](https://api.maci.energy/docs/authentication.md): Every call carries an API key. The key decides where the call works, sandbox or production, and what it may do.
- [Lists, limits and versions](https://api.maci.energy/docs/conventions.md): The rules every endpoint follows: the format, paging, repeated calls, how many calls a key may make, and how the API changes.
- [Errors](https://api.maci.energy/docs/errors.md): The API answers with an ordinary HTTP status. An error also has a body with a fixed code your system can act on and a message for a person.
- [Webhooks](https://api.maci.energy/docs/webhooks.md): Maci can post events to an address of your own, so your system hears about an alarm or an approved invoice basis at once, signed with a secret only you and Maci know.
- [AI assistants (MCP)](https://api.maci.energy/docs/ai-assistants.md): Connect Maci to Claude, ChatGPT or another assistant that speaks the Model Context Protocol, and ask it about your refrigeration units in your own words. It reads through the API, so it sees what a key of yours would see, and it cannot change anything.

## Resources

- [Units](https://api.maci.energy/docs/units.md): A unit is one refrigeration system, display case, cold room or other piece of equipment with its own QR or NFC tag, and a site is where it stands. Endpoints: GET /sites, GET /units, POST /units, GET /units/{unit}, PATCH /units/{unit}
- [Components](https://api.maci.energy/docs/components.md): The parts of a unit: compressors, fans, valves, controllers and the rest. Endpoints: GET /units/{unit}/components, POST /units/{unit}/components, PATCH /components/{component}, POST /components/{component}/replace
- [Photos](https://api.maci.energy/docs/photos.md): Photos of a unit's nameplates, labels and overviews. Endpoints: GET /units/{unit}/photos, POST /units/{unit}/photos, GET /photos/{photo}/reading
- [Service](https://api.maci.energy/docs/service.md): A unit's service history: visits, repairs, fault reports and notes, from the app and from your own systems. Endpoints: GET /units/{unit}/service-entries, POST /units/{unit}/service-entries
- [F-gas log](https://api.maci.energy/docs/f-gas-log.md): The F-gas log under regulation (EU) 2024/573 and the unit's status: CO2 equivalent, the leak check interval and when the next check is due. Endpoints: GET /units/{unit}/fgas-entries, POST /units/{unit}/fgas-entries, GET /units/{unit}/fgas-status
- [Subscriptions](https://api.maci.energy/docs/subscriptions.md): The organisation's Maci Service subscriptions. Endpoints: GET /subscriptions, PUT /units/{unit}/subscription, DELETE /units/{unit}/subscription
- [Invoicing](https://api.maci.energy/docs/invoicing.md): A service company's invoice basis, made when a technician approves a service report from speech, and its catalogue. Endpoints: GET /invoice-drafts, POST /invoice-drafts/mark-exported, GET /invoice-drafts/{draft}, GET /price-list-items, PUT /price-list-items
- [Alarms](https://api.maci.energy/docs/alarms.md): Alarms from Maci Intelligence for the units' owner and for the refrigeration firm the owner has chosen as the watch. Endpoints: GET /alarms, GET /alarms/{alarm}, POST /alarms/{alarm}/acknowledge, POST /alarms/{alarm}/close
- [Refrigerants and usage](https://api.maci.energy/docs/refrigerants-and-usage.md): The refrigerant table with GWP, open to every key, and what the key and the organisation have used this month. Endpoints: GET /refrigerants, GET /usage

## Optional

- [OpenAPI (YAML)](https://api.maci.energy/openapi.yaml): every endpoint, field and webhook
- [About Maci](https://maci.energy/llms.txt): the company and its products