Maxidomo API
Reach your property’s record from a script, a terminal or another system. Every call acts as the person whose API key it carries, and can do exactly what that person can do in the app — no more.
Endpoints
The machine-readable description lives at /api/v1/openapi.json — OpenAPI 3.1, and the source most client generators want.
Properties and their records
| Endpoint | What it does | Key |
|---|---|---|
| get /properties | Every property you are a member of. | read-only ok |
| get /properties/{id} | One property's summary. | read-only ok |
| patch /properties/{id} | Correct a property's own attributes. | full key |
| get /properties/{id}/facts | Answers to questions about the property. | read-only ok |
| post /properties/{id}/facts | Record a fact. | full key |
| get /properties/{id}/notes | Standing truths about this property. Owner only. | read-only ok |
| post /properties/{id}/notes | Record a note. | full key |
| get /properties/{id}/contacts | People who work on the place. | read-only ok |
| post /properties/{id}/contacts | Record a contact. | full key |
| get /properties/{id}/tasks | To-dos. | read-only ok |
| post /properties/{id}/tasks | Create or update a task. | full key |
| get /properties/{id}/reminders | Dated things that come to you. | read-only ok |
| post /properties/{id}/reminders | Create a reminder. | full key |
| get /properties/{id}/documents | Paperwork on file. Paged by cursor. | read-only ok |
| post /properties/{id}/documents/upload | File a document, or mint an upload ticket for its bytes. | full key |
| get /properties/{id}/members | Who is on this property, and in what role. | read-only ok |
| post /properties/{id}/members | Grant or revoke access. An owner grant needs email confirmation. | full key |
| post /properties/{id}/wiki | Ask a question about this property. Costs money; tightly rate limited. | read-only ok |
| post /properties/{id}/retire | Retire a property. Needs email confirmation. | full key |
| post /properties/{id}/secret-links | Mint a one-time link to read or set a sealed secret. No value ever crosses the wire. | full key |
| get /properties/{id}/webhooks | Where this property's events are delivered. | read-only ok |
| post /properties/{id}/webhooks | Register a delivery endpoint. The signing secret is returned once. | full key |
Reference
| Endpoint | What it does | Key |
|---|---|---|
| get /handbook | What Maxidomo does, in a household's own words. | read-only ok |
Getting a key
Mint one at Settings → Developers. You will need a Maxidomo account and a property. A key is shown once, at the moment you create it, and never again — Maxidomo stores only a hash of it.
A read-only key refuses every write. It is the one to paste into CI, a reporting job, or anywhere you would rather not think too hard about.
Making a call
curl https://app.maxidomo.com/api/v1/properties \ -H "Authorization: Bearer mxd_…"
Start with GET /properties: nearly every other endpoint takes a property id, and that is where you get one.
What comes back
JSON, always. Every response carries an X-Request-Id — quote it if you need to report something that went wrong.
Errors carry a code you can branch on, and a message meant for a person to read:
{ "error": { "code": "VALIDATION", "message": "kind 'fact' requires … missing: evidence" } }The codes are VALIDATION, FORBIDDEN, NOT_FOUND, REQUEST and SERVER. Branch on the code, never on the message.
A record you may not see is a 404, not a 403. That is deliberate: a different answer would let a script work out which properties exist by watching which ones refuse it differently.
Rate limits
Refusals carry Retry-After alongside RateLimit-Limit and RateLimit-Remaining, so a well-behaved client can pace itself rather than waiting to be told off.
Asking the wiki has its own, much tighter budget, because it runs a model and therefore costs real money on every call.
Writes that do not happen immediately
Some acts are too consequential for a credential sitting in a script to perform alone — retiring a property, or making somebody an owner. Those return a pending status and email a confirmation link to a person, who completes the act by opening it. This is the same answer Claude gets over MCP, and it is not a failure: the call worked, and it is waiting on a human.
Secret values never cross this API in either direction. To read or set a door code or a wifi password, mint a one-time link with POST /properties/{id}/secret-links and open it.
Webhooks
Register an endpoint with POST /properties/{id}/webhooks and the record pushes to it instead of you polling. The signing secret is returned once, at registration. Every delivery carries maxidomo-signature: t=<unix seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of <t>.<body> under that secret. The timestamp is inside the signed material, so you can reject a delivery older than your own tolerance.
Coverage is deliberately partial.A webhook fires when something is created or completed — nothing else. Editing a fact’s value, retitling a task, renaming a property, granting somebody access, writing a comment and sending a chat message all fire nothing. Treat the feed as a prompt to re-read, never as a change log.
The payload carries a reference, never record contents — you re-read under your own credential, so a webhook can never show more than the key it was registered with may see. Endpoints must be https; loopback and private addresses are refused.
A 410 Gone from your endpoint is terminal — Maxidomo disables it and stops. Every other failure is transient as far as Maxidomo is concerned, because a 404 is usually a deploy in progress rather than a decision: nine attempts on a widening backoff over about four hours, then the endpoint is disabled.
Paging
Lists that page return a nextCursor. Send it back as ?cursor= to get the next page, and stop when it is null. Treat it as an opaque token — it is not an id and its contents will change.
Changes
— Projects are retired: every task is a to-do. GET …/tasks now returns every to-do on the property, where it returned projects only, and a task no longer carries shape, steps, category, targetDate or parent.