{ "openapi": "3.1.0", "info": { "title": "Maci API", "version": "1.0", "summary": "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.", "description": "The API gives an organisation's own systems access to the data the organisation has in Maci Service, the alarms from Maci Intelligence and, for a service company, its invoice bases. Webhooks post alarms and approved invoice bases to an address of the organisation's own.\n\n**Keys.** The organisation's admins create, rotate and delete API keys in the app under Konto → API-nøgler. A key is shown once, when it is created. Maci Service (Premium) is bought in the app as a number of subscriptions, and each is on one unit or unassigned. The API only reaches units that have one: a unit without Maci Service is left out of lists and answers 403. The subscriptions endpoints list the organisation's subscriptions and give an unassigned one to a unit, or take one off, so an integration can decide which units have Maci Service.\n\n**Authentication.** Send the key in the header `Authorization: Bearer maci_live_...`. The key is accepted only in that header and only over HTTPS. A call without a valid key gets 401.\n\n**Sandbox and production.** There is one API, and the key decides where a call works. A production key starts with `maci_live_` and works on the organisation's real units. A sandbox key starts with `maci_sandbox_` and works on the organisation's own sandbox: test data that starts with a site and two units, and that nothing in production can see or be changed by. Addresses, scopes, limits, errors and answers are the same in both, so moving to production is a matter of changing the key. Every answer has the header `Maci-Environment` with `sandbox` or `production`. Sandbox calls do not count towards the monthly limit, and a label (`tag_code`) cannot be used in the sandbox.\n\n**What a key can do.** A key can never do more than the organisation itself. An owner's key reaches the organisation's own units. A service company's key reaches the units where the company has an active grant. Grants are checked on every call. Each endpoint asks for a scope, which is chosen per key.\n\n**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`.\n\n**Lists.** 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.\n\n**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.\n\n**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.\n\n**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.\n\n**Errors.** Errors are returned as JSON with `code` and `message`. At 422 the answer also has `errors` with one field per error.\n\nLogin, passkeys, grants, invitations, API keys and administration can only be handled in the web app.\n" }, "servers": [ { "url": "https://api.maci.energy/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Units", "x-slug": "units", "x-models": [ "Unit", "Site" ], "description": "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. A unit has master data from its nameplate, its refrigerant and charge with the CO2 equivalent worked out, and its active components. The API reaches the units the organisation owns and, for a service company, the units where it has an active grant.\n" }, { "name": "Components", "x-slug": "components", "x-models": [ "Component" ], "description": "The parts of a unit: compressors, fans, valves, controllers and the rest. A component is never deleted. When it is replaced, the old one is kept with the status `replaced` and the replacement goes into the service history, so the unit's history stays whole.\n" }, { "name": "Photos", "x-slug": "photos", "x-models": [ "Photo", "PhotoReading" ], "description": "Photos of a unit's nameplates, labels and overviews. A nameplate or a label is read by AI into suggestions with a confidence for each field. Nothing on the unit changes until the suggestions are saved with the calls for units and components.\n" }, { "name": "Service", "x-slug": "service", "x-models": [ "ServiceEntry" ], "description": "A unit's service history: visits, repairs, fault reports and notes, from the app and from your own systems.\n" }, { "name": "F-gas log", "x-slug": "f-gas-log", "x-models": [ "FGasEntry", "FGasStatus" ], "description": "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. An entry takes the certificates of the company and of the person and cannot be changed afterwards, only corrected by a new entry. Adding entries needs Maci Service Premium on the unit.\n" }, { "name": "Subscriptions", "x-slug": "subscriptions", "x-models": [ "Subscription" ], "description": "The organisation's Maci Service subscriptions. Each is on one unit or unassigned, and the API only reaches units that have one. Subscriptions are bought in the app; the API decides which units have them.\n" }, { "name": "Invoicing", "x-slug": "invoicing", "x-models": [ "InvoiceDraft", "PriceListItem" ], "description": "A service company's invoice basis, made when a technician approves a service report from speech, and its catalogue. The fields are the same as in the CSV and Excel export, so an accounting system is set up once. When the company sets a webhook address in the app, each approved basis is posted to it as `invoice_draft.approved`, with the body signed in the header `X-Maci-Signature` as `sha256=` and the HMAC-SHA256 of the body with the webhook's secret.\n" }, { "name": "Alarms", "x-slug": "alarms", "x-models": [ "Alarm" ], "description": "Alarms from Maci Intelligence for the units' owner and for the refrigeration firm the owner has chosen as the watch. An alarm is open until someone closes it, also after its cause has cleared. Taking an alarm (`acknowledge`) stops it from going on to the next recipients, as on the unit's card. When the organisation sets a webhook address for alarms in the app, each alarm is also posted to it as `alarm.raised`, `alarm.cleared`, `alarm.acknowledged` and `alarm.closed`, with the alarm as the body's `data` and the body signed in the header `X-Maci-Signature` as `sha256=` and the HMAC-SHA256 of the body with the webhook's secret. The SMS and mail to the recipients do not depend on the webhook.\n" }, { "name": "Other", "x-slug": "refrigerants-and-usage", "x-title": "Refrigerants and usage", "x-models": [ "Refrigerant", "Usage" ], "description": "The refrigerant table with GWP, open to every key, and what the key and the organisation have used this month.\n" } ], "paths": { "/sites": { "get": { "tags": [ "Units" ], "operationId": "listSites", "summary": "The organisation's sites", "description": "The organisation's own sites. For a service company also the sites where the company has access to units.", "security": [ { "apiKey": [ "units:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteList" } } } } } } }, "/units": { "get": { "tags": [ "Units" ], "operationId": "listUnits", "summary": "The units the organisation has access to", "security": [ { "apiKey": [ "units:read" ] } ], "parameters": [ { "name": "site_id", "in": "query", "description": "Only units at this site.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Only units with this status, `active` or `decommissioned`.", "schema": { "type": "string", "enum": [ "active", "decommissioned" ] } }, { "name": "updated_since", "in": "query", "description": "Only units changed at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of units, without components.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitList" } } } } } }, "post": { "tags": [ "Units" ], "operationId": "createUnit", "summary": "Create a unit", "description": "The unit is created at one of the organisation's sites. A service company can create at a customer's site when its grant includes creation.", "security": [ { "apiKey": [ "units:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitCreate" } } } }, "responses": { "201": { "description": "The unit that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" } } } } } } }, "/units/{unit}": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "get": { "tags": [ "Units" ], "operationId": "getUnit", "summary": "Master data, refrigerant, charge and active components", "security": [ { "apiKey": [ "units:read" ] } ], "responses": { "200": { "description": "The unit with its active components.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" }, "example": { "id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11", "public_id": "MC-0482", "name": "Cold room 2", "category": "cold_room", "status": "active", "site_id": "5d0c7e52-8a0b-4c3e-b1a4-7c1f6a2d9e30", "refrigerant": "R449A", "charge_kg": 42, "co2e_tonnes": 58.7, "components": [ { "id": "c2a9d7f4-1b7e-4e0a-8f55-3a9b1d2c4e66", "type": "compressor", "label": "Compressor 1", "manufacturer": "Example Ltd", "model": "K-100", "status": "active", "attributes": { "rated_current_a": 9.8, "motor_power_kw": 3.7 } } ] } } } } } }, "patch": { "tags": [ "Units" ], "operationId": "updateUnit", "summary": "Change master data", "description": "Send only the fields to change.", "security": [ { "apiKey": [ "units:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitInput" } } } }, "responses": { "200": { "description": "The unit after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" } } } } } } }, "/units/{unit}/components": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "get": { "tags": [ "Components" ], "operationId": "listComponents", "summary": "The components of a unit", "security": [ { "apiKey": [ "units:read" ] } ], "parameters": [ { "name": "include_replaced", "in": "query", "description": "`true` includes earlier components.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of components.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentList" } } } } } }, "post": { "tags": [ "Components" ], "operationId": "createComponent", "summary": "Add a component", "security": [ { "apiKey": [ "units:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentCreate" }, "example": { "type": "fan", "label": "Evaporator fan 1", "quantity": 2, "attributes": { "placement": "evaporator", "motor_type": "EC", "power_w": 38 } } } } }, "responses": { "201": { "description": "The component that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Component" } } } } } } }, "/components/{component}": { "parameters": [ { "$ref": "#/components/parameters/component" } ], "patch": { "tags": [ "Components" ], "operationId": "updateComponent", "summary": "Change a component", "description": "Send only the fields to change. A component that is replaced or removed cannot be changed (409).", "security": [ { "apiKey": [ "units:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentInput" } } } }, "responses": { "200": { "description": "The component after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Component" } } } } } } }, "/components/{component}/replace": { "parameters": [ { "$ref": "#/components/parameters/component" } ], "post": { "tags": [ "Components" ], "operationId": "replaceComponent", "summary": "Replace a component", "description": "The new component gets the type of the old one. The old one is kept with the status `replaced`, and the replacement is in the service history.", "security": [ { "apiKey": [ "units:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentReplace" } } } }, "responses": { "201": { "description": "The new component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Component" } } } } } } }, "/units/{unit}/photos": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "get": { "tags": [ "Photos" ], "operationId": "listPhotos", "summary": "Photos of a unit", "description": "The unit's nameplates, labels and overviews, with the status of each reading. The photos themselves are seen in the app.", "security": [ { "apiKey": [ "units:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of photos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoList" } } } } } }, "post": { "tags": [ "Photos" ], "operationId": "createPhoto", "summary": "Send a photo", "description": "A nameplate or a label is read in the background into suggestions. Nothing on the unit changes until the suggestions are saved with the calls for units and components. An overview is never read.", "security": [ { "apiKey": [ "units:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "kind", "photo" ], "properties": { "kind": { "type": "string", "enum": [ "nameplate", "label", "overview" ] }, "label_kind": { "type": [ "string", "null" ], "enum": [ "service", "refrigerant", "ce", "leak_check", "other", null ], "description": "For a label: which kind." }, "component_id": { "type": [ "string", "null" ], "format": "uuid", "description": "A photo of one of the unit's components." }, "photo": { "type": "string", "format": "binary", "description": "JPEG, PNG or WebP of at most 10 MB." } } } } } }, "responses": { "201": { "description": "The photo that was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } } } } }, "/photos/{photo}/reading": { "parameters": [ { "name": "photo", "in": "path", "required": true, "description": "The ID of the photo.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Photos" ], "operationId": "getPhotoReading", "summary": "What was read on a photo", "description": "The newest reading, with each field's value in SI units, the text it was read from, the confidence (high, medium or low) and where it stands in the photo.", "security": [ { "apiKey": [ "units:read" ] } ], "responses": { "200": { "description": "The reading.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoReading" } } } } } } }, "/units/{unit}/service-entries": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "get": { "tags": [ "Service" ], "operationId": "listServiceEntries", "summary": "Service history", "security": [ { "apiKey": [ "service:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of service notes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntryList" } } } } } }, "post": { "tags": [ "Service" ], "operationId": "createServiceEntry", "summary": "New service note", "security": [ { "apiKey": [ "service:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntryCreate" } } } }, "responses": { "201": { "description": "The service note that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } } } } }, "/units/{unit}/fgas-entries": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "get": { "tags": [ "F-gas log" ], "operationId": "listFGasEntries", "summary": "Entries in the F-gas log", "description": "The logbook is kept on the unit that holds the refrigerant. For a unit on a central system it is the logbook of that system.", "security": [ { "apiKey": [ "fgas:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FGasEntryList" } } } } } }, "post": { "tags": [ "F-gas log" ], "operationId": "createFGasEntry", "summary": "New entry in the F-gas log", "description": "Takes the certificates of the company and of the person. An entry cannot be changed afterwards. The unit has to have Premium.", "security": [ { "apiKey": [ "fgas:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FGasEntryCreate" } } } }, "responses": { "201": { "description": "The entry that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FGasEntry" } } } } } } }, "/units/{unit}/fgas-status": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "get": { "tags": [ "F-gas log" ], "operationId": "getFGasStatus", "summary": "CO2 equivalent, check interval, latest and next leak check", "security": [ { "apiKey": [ "fgas:read" ] } ], "responses": { "200": { "description": "Where the unit stands today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FGasStatus" } } } } } } }, "/subscriptions": { "get": { "tags": [ "Subscriptions" ], "operationId": "listSubscriptions", "summary": "The organisation's Maci Service subscriptions", "description": "Each subscription is on one unit (`unit_id`) or unassigned (`unit_id` is null). Unassigned subscriptions are paid for like the others. Subscriptions are bought in the app.", "security": [ { "apiKey": [ "subscriptions:read" ] } ], "parameters": [ { "name": "unassigned", "in": "query", "description": "`true` for only the unassigned subscriptions, `false` for only those on a unit.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of subscriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/units/{unit}/subscription": { "parameters": [ { "$ref": "#/components/parameters/unit" } ], "put": { "tags": [ "Subscriptions" ], "operationId": "assignSubscription", "summary": "Give the unit Maci Service from an unassigned subscription", "description": "The unit has to be one of the organisation's own units, in use. Without `subscription_id` the oldest unassigned subscription is used. A unit that already has one answers with it. To move a subscription from another unit, take it off that unit first. 409 when the organisation has no unassigned subscription.", "security": [ { "apiKey": [ "subscriptions:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "format": "uuid", "description": "An unassigned subscription of the organisation's." } } } } } }, "responses": { "200": { "description": "The subscription, now on the unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } } }, "delete": { "tags": [ "Subscriptions" ], "operationId": "unassignSubscription", "summary": "Take the unit's subscription off it", "description": "The subscription stays the organisation's, paid as before, and can be given to another unit. The unit's F-gas log can still be read, but nothing can be added to it.", "security": [ { "apiKey": [ "subscriptions:write" ] } ], "responses": { "200": { "description": "The subscription, now unassigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } } } }, "/alarms": { "get": { "tags": [ "Alarms" ], "operationId": "listAlarms", "summary": "The alarms of the units the organisation owns or watches", "description": "Raised since `since`, by default the last 30 days. The owner's key sees the alarms of its own units; a refrigeration firm's key the alarms of the units where the owner has chosen it as the watch.", "security": [ { "apiKey": [ "alarms:read" ] } ], "parameters": [ { "name": "open", "in": "query", "description": "`true` for only the alarms not yet closed, `false` for only the closed ones.", "schema": { "type": "boolean" } }, { "name": "unit_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of alarms.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alarm" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/alarms/{alarm}": { "parameters": [ { "$ref": "#/components/parameters/alarm" } ], "get": { "tags": [ "Alarms" ], "operationId": "getAlarm", "summary": "One alarm", "security": [ { "apiKey": [ "alarms:read" ] } ], "responses": { "200": { "description": "The alarm.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alarm" } } } } } } }, "/alarms/{alarm}/acknowledge": { "parameters": [ { "$ref": "#/components/parameters/alarm" } ], "post": { "tags": [ "Alarms" ], "operationId": "acknowledgeAlarm", "summary": "Take the alarm", "description": "Someone is on it, so the alarm does not go on to the next recipients. Taking an alarm already taken changes nothing. The card shows the key's name as who took it.", "security": [ { "apiKey": [ "alarms:write" ] } ], "responses": { "200": { "description": "The alarm, taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alarm" } } } } } } }, "/alarms/{alarm}/close": { "parameters": [ { "$ref": "#/components/parameters/alarm" } ], "post": { "tags": [ "Alarms" ], "operationId": "closeAlarm", "summary": "Close the alarm as real or false", "description": "Takes it first if nobody has. What was found helps tune the alarm rules. 409 when it is closed already.", "security": [ { "apiKey": [ "alarms:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "string", "enum": [ "real", false ] }, "note": { "type": "string", "maxLength": 2000, "description": "What was found on the unit. Write no names of people." } } } } } }, "responses": { "200": { "description": "The alarm, closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alarm" } } } } } } }, "/invoice-drafts": { "get": { "tags": [ "Invoicing" ], "operationId": "listInvoiceDrafts", "summary": "The organisation's invoice basis", "description": "For an accounting system: `status=approved&exported=false` gives what is ready to invoice and not yet taken.", "security": [ { "apiKey": [ "invoices:read" ] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "approved" ] } }, { "name": "exported", "in": "query", "description": "`false` for only those not marked exported, `true` for only those marked.", "schema": { "type": "boolean" } }, { "name": "since", "in": "query", "description": "Only those changed at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of invoice bases with their lines.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDraft" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/invoice-drafts/mark-exported": { "post": { "tags": [ "Invoicing" ], "operationId": "markInvoiceDraftsExported", "summary": "Mark invoice bases exported", "description": "Only approved ones are marked, and only the first time; calling it again with the same IDs is no error.", "security": [ { "apiKey": [ "invoices:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "maxItems": 500, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "How many were marked now, the bases as they are, and the IDs not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "marked": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDraft" } }, "not_found": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } } } }, "/invoice-drafts/{draft}": { "parameters": [ { "name": "draft", "in": "path", "required": true, "description": "The ID of the invoice basis.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Invoicing" ], "operationId": "getInvoiceDraft", "summary": "One invoice basis with all its lines and sources", "security": [ { "apiKey": [ "invoices:read" ] } ], "responses": { "200": { "description": "The invoice basis.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraft" } } } } } } }, "/price-list-items": { "get": { "tags": [ "Invoicing" ], "operationId": "listPriceListItems", "summary": "The organisation's catalogue", "security": [ { "apiKey": [ "price-list:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceListItem" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } }, "put": { "tags": [ "Invoicing" ], "operationId": "putPriceListItems", "summary": "Create or update items from the accounting system", "description": "Each item is found by its item number, whatever its case or punctuation, and created when it is new.", "security": [ { "apiKey": [ "price-list:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 1000, "items": { "type": "object", "required": [ "item_number", "description", "price_excl_vat" ], "properties": { "item_number": { "type": "string", "maxLength": 60 }, "description": { "type": "string", "maxLength": 300 }, "unit_of_measure": { "type": "string", "maxLength": 20 }, "price_excl_vat": { "type": "number", "description": "In the currency's main unit, such as 2450.00 kroner." }, "kind": { "type": "string", "enum": [ "part", "refrigerant", "labour", "travel", "other" ] }, "active": { "type": "boolean" } } } } } } } } }, "responses": { "200": { "description": "How many were created, updated and skipped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" } } } } } } } } }, "/refrigerants": { "get": { "tags": [ "Other" ], "operationId": "listRefrigerants", "summary": "The refrigerant table with GWP", "description": "Open to every key.", "responses": { "200": { "description": "All refrigerants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refrigerant" } } } } } } } } } }, "/usage": { "get": { "tags": [ "Other" ], "operationId": "getUsage", "summary": "What the key and the organisation have used this month", "description": "Open to every key.", "responses": { "200": { "description": "The usage in the current month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } } } } } }, "webhooks": { "alarm": { "post": { "tags": [ "Alarms" ], "operationId": "alarmWebhook", "summary": "An alarm's event, posted to the organisation's webhook address for alarms", "description": "Set the address and get the secret under **API keys** in the app. `X-Maci-Event` is `alarm.raised`, `alarm.cleared`, `alarm.acknowledged` or `alarm.closed`, and `data` is the alarm as `GET /alarms/{alarm}` gives it at the moment it is sent. Answer with a 2xx within 10 seconds; anything else is tried again after 10 seconds, 30 seconds, 2 minutes, 10 minutes and 30 minutes. The SMS and mail to the recipients do not depend on the webhook, and the alarms can always be fetched with `GET /alarms`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "created_at", "data" ], "properties": { "event": { "type": "string", "enum": [ "alarm.raised", "alarm.cleared", "alarm.acknowledged", "alarm.closed" ], "description": "The same as the header `X-Maci-Event`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event was sent." }, "data": { "$ref": "#/components/schemas/Alarm" } } }, "example": { "event": "alarm.raised", "created_at": "2026-10-30T02:14:07Z", "data": { "id": "7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18", "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11", "unit_public_id": "MC-0482", "unit": "Cold room 2", "site": "Main store", "type": "rum-for-varmt", "name": "Room too warm", "severity": "HIGH", "state": "raised", "open": true, "values": { "room_temp_c": "9.4" }, "raised_at": "2026-10-30T02:14:05Z", "cleared_at": null, "level": 0, "watch": null, "acknowledged_at": null, "acknowledged_by": null, "closed_at": null, "closed_by": null, "result": null, "note": null } } } } }, "responses": { "200": { "description": "Received." } } } }, "invoiceDraft": { "post": { "tags": [ "Invoicing" ], "operationId": "invoiceDraftWebhook", "summary": "An approved invoice basis, posted to the service company's webhook address", "description": "Set the address and get the secret under **Invoice basis**, Settings, in the app. `X-Maci-Event` is `invoice_draft.approved`, and `data` is the invoice basis as `GET /invoice-drafts/{draft}` gives it. Answer with a 2xx within 10 seconds; anything else is tried again after 1 minute, 5 minutes, 30 minutes and 2 hours. The bases can always be fetched with `GET /invoice-drafts` as well.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "created_at", "data" ], "properties": { "event": { "type": "string", "enum": [ "invoice_draft.approved" ], "description": "The same as the header `X-Maci-Event`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event was sent." }, "data": { "$ref": "#/components/schemas/InvoiceDraft" } } }, "example": { "event": "invoice_draft.approved", "created_at": "2026-10-30T14:02:51Z", "data": { "id": "3c8d2a71-6e0b-4f95-a2d4-8b1e7c5f0a93", "status": "approved", "service_report_id": "9a4f0e2b-7c13-4d68-b5e1-2d9c6a3f8b07", "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11", "unit_public_id": "MC-0482", "unit": "Cold room 2", "customer": { "name": "Example Foods ApS", "cvr": "12345678", "vat_number": null }, "visit_date": "2026-10-30", "technician": "Jonas L.", "currency": "DKK", "total_excl_vat": 1890, "approved_at": "2026-10-30T14:02:49Z", "exported_at": null, "lines": [ { "type": "labour", "item_number": "1000", "description": "Labour", "quantity": 1.5, "unit_of_measure": "hours", "unit_price": 700, "amount_excl_vat": 1050, "source": "speech", "match_sure": true }, { "type": "travel", "item_number": "1010", "description": "Call-out", "quantity": 1, "unit_of_measure": "pcs", "unit_price": 840, "amount_excl_vat": 840, "source": "speech", "match_sure": true } ] } } } } }, "responses": { "200": { "description": "Received." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key. It starts with `maci_live_` for production and `maci_sandbox_` for the sandbox." } }, "parameters": { "alarm": { "name": "alarm", "in": "path", "required": true, "description": "The ID of the alarm.", "schema": { "type": "string", "format": "uuid" } }, "unit": { "name": "unit", "in": "path", "required": true, "description": "The ID of the unit.", "schema": { "type": "string", "format": "uuid" } }, "component": { "name": "component", "in": "path", "required": true, "description": "The ID of the component.", "schema": { "type": "string", "format": "uuid" } }, "limit": { "name": "limit", "in": "query", "description": "Records per page. At most 100, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "cursor": { "name": "cursor", "in": "query", "description": "The value of `next_cursor` from the page before.", "schema": { "type": "string" } }, "idempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "A value of your own choosing, so that a repeated call does not create two records.", "schema": { "type": "string", "maxLength": 255 } } }, "schemas": { "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A fixed code, such as `unauthenticated`, `missing_scope`, `forbidden`, `subscription_inactive`, `blocked`, `not_found`, `conflict`, `validation_failed` or `rate_limited`." }, "message": { "type": "string", "description": "An explanation for a person." }, "errors": { "type": "object", "description": "Only at 422. One field per error, each with a list of messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SiteList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "UnitInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "The name of the unit." }, "category": { "type": "string", "enum": [ "display_case", "freezer_case", "plug_in_cabinet", "cold_room", "freezer_room", "blast_chiller", "condensing_unit", "compressor_rack", "chiller", "heat_pump", "other" ] }, "manufacturer": { "type": [ "string", "null" ], "maxLength": 120 }, "model": { "type": [ "string", "null" ], "maxLength": 120 }, "serial_no": { "type": [ "string", "null" ], "maxLength": 120 }, "production_year": { "type": [ "integer", "null" ], "minimum": 1950 }, "installation_year": { "type": [ "integer", "null" ], "minimum": 1950 }, "system_type": { "type": [ "string", "null" ], "enum": [ "plug_in", "split", "central", null ] }, "parent_unit_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The central system the unit is connected to. It has to be one of the owner's units." }, "refrigerant": { "type": [ "string", "null" ], "description": "The designation of the refrigerant, such as `R449A`. See GET /refrigerants." }, "refrigerant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the refrigerant. Can be used instead of `refrigerant`." }, "charge_kg": { "type": [ "number", "null" ], "minimum": 0, "description": "The charge in kg." }, "hermetically_sealed": { "type": "boolean" }, "leak_detection_system": { "type": "boolean" }, "temp_min_c": { "type": [ "number", "null" ] }, "temp_max_c": { "type": [ "number", "null" ] }, "supply_voltage_v": { "type": [ "integer", "null" ] }, "supply_phases": { "type": [ "integer", "null" ], "enum": [ 1, 3, null ] }, "supply_frequency_hz": { "type": [ "integer", "null" ], "enum": [ 50, 60, null ] }, "rated_current_a": { "type": [ "number", "null" ], "description": "Rated current in A, from the nameplate." }, "power_kw": { "type": [ "number", "null" ], "description": "Power in kW, from the nameplate." }, "ps_high_bar": { "type": [ "number", "null" ], "description": "Allowable pressure PS on the high side, in bar." }, "ps_low_bar": { "type": [ "number", "null" ], "description": "Allowable pressure PS on the low side, in bar." }, "climate_class": { "type": [ "string", "null" ] } } }, "UnitCreate": { "allOf": [ { "type": "object", "required": [ "site_id", "name", "category" ], "properties": { "site_id": { "type": "string", "format": "uuid", "description": "The site the unit is at." }, "tag_code": { "type": [ "string", "null" ], "description": "The code on a pre-printed label that is not in use. The unit gets the Maci ID of the label. Not in the sandbox." } } }, { "$ref": "#/components/schemas/UnitInput" } ] }, "Unit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "public_id": { "type": "string", "description": "The Maci ID, such as `MC-0482`." }, "name": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "decommissioned" ] }, "organization_id": { "type": "string", "format": "uuid", "description": "The owner." }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_unit_id": { "type": [ "string", "null" ], "format": "uuid" }, "manufacturer": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "serial_no": { "type": [ "string", "null" ] }, "production_year": { "type": [ "integer", "null" ] }, "installation_year": { "type": [ "integer", "null" ] }, "system_type": { "type": [ "string", "null" ] }, "refrigerant": { "type": [ "string", "null" ], "description": "The designation of the refrigerant." }, "charge_kg": { "type": [ "number", "null" ] }, "co2e_tonnes": { "type": [ "number", "null" ], "description": "The charge in tonnes of CO2 equivalent." }, "charge_is_on_parent": { "type": "boolean", "description": "`true` when refrigerant and charge are those of the central system." }, "premium": { "type": "boolean", "description": "Whether the unit has Premium. The API only reaches units that have it." }, "hermetically_sealed": { "type": "boolean" }, "leak_detection_system": { "type": "boolean" }, "temp_min_c": { "type": [ "number", "null" ] }, "temp_max_c": { "type": [ "number", "null" ] }, "supply_voltage_v": { "type": [ "integer", "null" ] }, "supply_phases": { "type": [ "integer", "null" ] }, "supply_frequency_hz": { "type": [ "integer", "null" ] }, "rated_current_a": { "type": [ "number", "null" ], "description": "Rated current in A, from the nameplate." }, "power_kw": { "type": [ "number", "null" ], "description": "Power in kW, from the nameplate." }, "ps_high_bar": { "type": [ "number", "null" ], "description": "Allowable pressure PS on the high side, in bar." }, "ps_low_bar": { "type": [ "number", "null" ], "description": "Allowable pressure PS on the low side, in bar." }, "climate_class": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "components": { "type": "array", "description": "Active components. Only there when one unit is fetched.", "items": { "$ref": "#/components/schemas/Component" } } } }, "UnitList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ComponentInput": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120, "description": "The name of the component, such as `Compressor 1`." }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 }, "manufacturer": { "type": [ "string", "null" ], "maxLength": 120 }, "model": { "type": [ "string", "null" ], "maxLength": 120 }, "serial_no": { "type": [ "string", "null" ], "maxLength": 120 }, "installed_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 2000 }, "attributes": { "type": [ "object", "null" ], "description": "The type's own fields, such as `rated_current_a` and `motor_power_kw` for a compressor. Unknown fields are refused with 422." }, "custom_fields": { "type": [ "object", "null" ], "description": "Fields of your own, as name and text. At most 20.", "additionalProperties": { "type": "string", "maxLength": 200 } } } }, "ComponentCreate": { "allOf": [ { "type": "object", "required": [ "type", "label" ], "properties": { "type": { "type": "string", "enum": [ "compressor", "condenser", "evaporator", "fan", "expansion_device", "controller", "defrost_heater", "sensor", "valve", "vessel", "cabinet", "maci_sensor", "other" ] } } }, { "$ref": "#/components/schemas/ComponentInput" } ] }, "ComponentReplace": { "allOf": [ { "type": "object", "required": [ "label" ] }, { "$ref": "#/components/schemas/ComponentInput" }, { "type": "object", "properties": { "service_text": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Text for the service note about the replacement." } } } ] }, "Component": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "label": { "type": "string" }, "quantity": { "type": "integer" }, "manufacturer": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "serial_no": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "replaced", "removed" ] }, "installed_at": { "type": [ "string", "null" ], "format": "date" }, "removed_at": { "type": [ "string", "null" ], "format": "date" }, "replaces_component_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The component this one replaced." }, "attributes": { "type": "object" }, "custom_fields": { "type": [ "object", "null" ] }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ComponentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ServiceEntryCreate": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "service", "repair", "inspection", "other" ], "description": "Replacements and additions are written by the system when a component changes." }, "text": { "type": "string", "maxLength": 2000 }, "performed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the work was done. The default is now." } } }, "Photo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "component_id": { "type": [ "string", "null" ], "format": "uuid" }, "kind": { "type": "string", "enum": [ "nameplate", "label", "overview" ] }, "label_kind": { "type": [ "string", "null" ] }, "reading_status": { "type": [ "string", "null" ], "enum": [ "queued", "running", "done", "failed", null ], "description": "`null` when the photo is not read." }, "taken_at": { "type": "string", "format": "date-time" } } }, "PhotoList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "PhotoField": { "type": "object", "properties": { "key": { "type": "string", "description": "The field: a unit's field such as `charge_kg`, or a component's." }, "value": { "description": "The value in SI units." }, "raw_text": { "type": "string", "description": "The text it was read from." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "bbox": { "type": [ "object", "null" ], "description": "Where the value stands, as shares of the photo's width and height.", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } } } } }, "PhotoReading": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "photo_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "readable": { "type": [ "boolean", "null" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoField" } }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoField" } } } } }, "service_label": { "type": [ "object", "null" ], "properties": { "date": { "type": "string" }, "company": { "type": "string" }, "certificate_no": { "type": "string" }, "next_service": { "type": "string" } } }, "model": { "type": [ "string", "null" ] }, "prompt_version": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ServiceEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "component_id": { "type": [ "string", "null" ], "format": "uuid" }, "type": { "type": "string", "enum": [ "service", "repair", "replacement", "addition", "inspection", "other" ] }, "performed_at": { "type": "string", "format": "date-time" }, "text": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ], "description": "The company that did the work." }, "created_at": { "type": "string", "format": "date-time" } } }, "ServiceEntryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEntry" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "FGasEntryCreate": { "type": "object", "required": [ "type", "performed_at", "company_name", "company_certificate_no", "person_name", "person_certificate_no" ], "properties": { "type": { "type": "string", "enum": [ "installation", "top_up", "recovery", "leak_check", "leak_repair", "detection_system_check", "decommissioning" ] }, "performed_at": { "type": "string", "format": "date", "description": "The date of the work." }, "company_name": { "type": "string", "description": "The company that did the work." }, "company_certificate_no": { "type": "string", "description": "The certificate number of the company." }, "person_name": { "type": "string", "description": "The person who did the work." }, "person_certificate_no": { "type": "string", "description": "The certificate number of the person." }, "company_cvr": { "type": [ "string", "null" ] }, "refrigerant": { "type": "string", "description": "The designation of the refrigerant. Needed for `installation` and `top_up`." }, "refrigerant_id": { "type": "string", "format": "uuid", "description": "Can be used instead of `refrigerant`." }, "quantity_kg": { "type": "number", "description": "The quantity in kg. Needed for `installation`, `top_up`, `recovery` and `decommissioning`." }, "reason": { "type": "string", "enum": [ "service", "leakage" ], "description": "Needed for `top_up`." }, "gas_origin": { "type": "string", "enum": [ "virgin", "recycled", "reclaimed" ], "description": "Needed for `top_up`." }, "origin_facility_name": { "type": "string", "description": "Needed for recycled or reclaimed gas." }, "origin_facility_address": { "type": "string", "description": "Needed for recycled or reclaimed gas." }, "origin_certificate_no": { "type": "string", "description": "Needed for recycled or reclaimed gas." }, "method": { "type": "string", "enum": [ "direct", "indirect" ], "description": "Needed for `leak_check`." }, "result": { "type": "string", "description": "For `leak_check`: `tight` or `leak_found`. For `leak_repair`: `repaired` or `not_repaired`. For `detection_system_check`: `ok` or `fault`." }, "leak_location": { "type": "string", "description": "Needed when a leak check finds a leak." }, "description": { "type": "string", "description": "Needed for `leak_repair`." }, "disposal": { "type": "string", "description": "What happened to the refrigerant. Needed for `decommissioning`." } } }, "FGasEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "performed_at": { "type": "string", "format": "date" }, "refrigerant": { "type": [ "string", "null" ] }, "quantity_kg": { "type": [ "number", "null" ] }, "reason": { "type": [ "string", "null" ] }, "gas_origin": { "type": [ "string", "null" ] }, "origin_facility_name": { "type": [ "string", "null" ] }, "origin_facility_address": { "type": [ "string", "null" ] }, "origin_certificate_no": { "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ] }, "result": { "type": [ "string", "null" ] }, "leak_location": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "disposal": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_cvr": { "type": [ "string", "null" ] }, "company_certificate_no": { "type": [ "string", "null" ] }, "person_name": { "type": [ "string", "null" ] }, "person_certificate_no": { "type": [ "string", "null" ] }, "corrects_entry_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The entry this one corrects." }, "is_corrected": { "type": "boolean", "description": "`true` when a later entry has corrected this one." }, "created_at": { "type": "string", "format": "date-time" } } }, "FGasEntryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FGasEntry" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Alarm": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_public_id": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit's name." }, "site": { "type": [ "string", "null" ] }, "type": { "type": "string", "description": "The alarm's type from the rule engine, e.g. `rum-for-varmt`. New types can come at any time." }, "name": { "type": "string", "description": "The type's name, in English, or in Danish with `Accept-Language: da`." }, "severity": { "type": "string", "description": "`HIGH` (SMS and mail, and on to the next recipients when nobody takes it) or `MEDIUM` (mail)." }, "state": { "type": "string", "enum": [ "raised", "cleared" ], "description": "`cleared` when the rule engine sees the cause gone." }, "open": { "type": "boolean", "description": "Not yet closed by a person." }, "values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The readings the rule saw." }, "raised_at": { "type": "string", "format": "date-time" }, "cleared_at": { "type": [ "string", "null" ], "format": "date-time" }, "level": { "type": "integer", "description": "How far it has gone: 0 the watch (or the owner without a watch), 1 the owner, 2 Maci." }, "watch": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_by": { "type": [ "string", "null" ], "description": "The person, or the key's name with (API)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_by": { "type": [ "string", "null" ] }, "result": { "type": [ "string", "null" ], "enum": [ "real", false, null ] }, "note": { "type": [ "string", "null" ] } } }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "product": { "type": "string", "enum": [ "service" ] }, "status": { "type": "string", "enum": [ "active", "cancelling", "suspended" ], "description": "`cancelling` stops at `cancel_at`; `suspended` is on hold for an unpaid invoice." }, "unit_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The unit it is on, or null when it is unassigned." }, "interval": { "type": "string", "enum": [ "month", "year" ] }, "paid_through": { "type": [ "string", "null" ], "format": "date-time" }, "cancel_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceDraft": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "approved" ] }, "service_report_id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_public_id": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "cvr": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] } } }, "visit_date": { "type": "string", "format": "date" }, "technician": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "total_excl_vat": { "type": "number" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "exported_at": { "type": [ "string", "null" ], "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "part", "refrigerant", "labour", "travel" ] }, "item_number": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_of_measure": { "type": "string" }, "unit_price": { "type": [ "number", "null" ] }, "amount_excl_vat": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "speech", "photo", "both", "manual" ], "description": "What the line was made from." }, "match_sure": { "type": "boolean", "description": "Whether the catalogue item was matched surely." } } } } } }, "PriceListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_number": { "type": "string" }, "description": { "type": "string" }, "unit_of_measure": { "type": "string" }, "price_excl_vat": { "type": "number" }, "kind": { "type": "string", "enum": [ "part", "refrigerant", "labour", "travel", "other" ] }, "active": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "FGasStatus": { "type": "object", "properties": { "unit_id": { "type": "string", "format": "uuid", "description": "The unit that holds the refrigerant." }, "refrigerant": { "type": [ "string", "null" ] }, "covered": { "type": "boolean", "description": "Whether the unit is covered by leak checks." }, "co2e_tonnes": { "type": [ "number", "null" ] }, "interval_months": { "type": [ "integer", "null" ], "description": "Months between leak checks." }, "last_leak_check_at": { "type": [ "string", "null" ], "format": "date" }, "next_leak_check_due_at": { "type": [ "string", "null" ], "format": "date" }, "follow_up_check": { "type": [ "object", "null" ], "description": "The follow-up check after a repaired leak.", "properties": { "earliest_at": { "type": "string", "format": "date" }, "due_at": { "type": "string", "format": "date" } } }, "state": { "type": "string", "description": "Where the unit stands towards the next check." }, "detection_system_missing": { "type": "boolean", "description": "`true` when a leak detection system is required but missing." } } }, "Refrigerant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "designation": { "type": "string", "description": "Such as `R449A`." }, "group": { "type": "string", "enum": [ "hfc", "hfc_blend", "hfc_hfo_blend", "hfo", "natural" ] }, "gwp": { "type": "number" }, "is_fgas": { "type": "boolean" } } }, "Usage": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "production", "sandbox" ], "description": "Where the key works." }, "month": { "type": "string", "description": "The month as `YYYY-MM`." }, "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "The first 8 characters of the key after its prefix." }, "calls": { "type": "integer" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "calls": { "type": "integer", "description": "Production calls this month. These count towards the limit." }, "monthly_limit": { "type": "integer" } } }, "rate_limit_per_minute": { "type": "integer" } } } } } }