---
name: "maison-public-api"
description: "Operate Maison, the AI hotel concierge platform, through its public tool API: one-shot tools for provisioning hotels, managing knowledge, talking to a hotel's concierge, users and access, analytics and reports, channels, integrations, configuration, plans, groups and quality. The same tools are callable over REST, MCP and A2A with an API key. Use whenever a task involves Maison hotels, their concierge, or the Maison admin console. 340 tools in 19 groups."
license: "Proprietary. Use with a Maison API key under the Maison terms of service."
metadata:
  author: "maison-labs"
  version: "1.0.0"
  api-base: "https://maison-labs.com"
  openapi: "https://maison-labs.com/api/v1/openapi.json"
  agent-card: "https://maison-labs.com/.well-known/agent.json"
  docs: "https://docs.maison-labs.com/skills/"
---

# Maison public API

Operate Maison, the AI hotel concierge platform, through its public tool API: one-shot tools for provisioning hotels, managing knowledge, talking to a hotel's concierge, users and access, analytics and reports, channels, integrations, configuration, plans, groups and quality. The same tools are callable over REST, MCP and A2A with an API key. Use whenever a task involves Maison hotels, their concierge, or the Maison admin console.

## Why use these skills instead of guessing

- Every tool completes a whole intent; chaining low-level calls is unnecessary and usually wrong.
- Permissions are all-or-nothing per tool and the catalogue is filtered per key — discover before you plan.
- Each category skill lists the workflow order, the pitfalls and the exact input fields, so the first call succeeds.

## Authentication

- Header `x-api-key: mx_<env>_…` on every request. Keys are created in the Maison admin console (profile → API keys) and reach only `https://maison-labs.com/api/v1`.
- No login endpoint, no cookies, no bearer tokens. OAuth is planned.

## Discover before you plan

1. `GET https://maison-labs.com/api/v1/me` (`whoami`) — who the key is, grants, reachable hotel ids.
2. `GET https://maison-labs.com/api/v1/tools` — the catalogue filtered to this key (name, description, REST binding, grants, input schema).
3. Pick the category skill below and follow its workflow.

## Skill groups

| Skill | Covers | Tools |
| --- | --- | --- |
| [`maison-account`](https://docs.maison-labs.com/skills/maison-account/SKILL.md) | Account and discovery | 8 |
| [`maison-clients`](https://docs.maison-labs.com/skills/maison-clients/SKILL.md) | Clients (hotels) | 15 |
| [`maison-knowledge`](https://docs.maison-labs.com/skills/maison-knowledge/SKILL.md) | Knowledge base | 41 |
| [`maison-conversations`](https://docs.maison-labs.com/skills/maison-conversations/SKILL.md) | Conversations and the concierge | 16 |
| [`maison-users`](https://docs.maison-labs.com/skills/maison-users/SKILL.md) | Users and invitations | 23 |
| [`maison-access`](https://docs.maison-labs.com/skills/maison-access/SKILL.md) | Roles, policies and groups | 56 |
| [`maison-analytics`](https://docs.maison-labs.com/skills/maison-analytics/SKILL.md) | Analytics and reports | 13 |
| [`maison-channels`](https://docs.maison-labs.com/skills/maison-channels/SKILL.md) | Messaging channels | 9 |
| [`maison-integrations`](https://docs.maison-labs.com/skills/maison-integrations/SKILL.md) | Integrations (PMS, payments, events) | 10 |
| [`maison-configuration`](https://docs.maison-labs.com/skills/maison-configuration/SKILL.md) | Hotel configuration, branding and content | 40 |
| [`maison-features`](https://docs.maison-labs.com/skills/maison-features/SKILL.md) | Feature plans and entitlements (Maison staff) | 30 |
| [`maison-hierarchy`](https://docs.maison-labs.com/skills/maison-hierarchy/SKILL.md) | Multi-property groups (Maison staff) | 10 |
| [`maison-quality`](https://docs.maison-labs.com/skills/maison-quality/SKILL.md) | Quality: tests and Guest Agent quality review | 11 |
| [`maison-hubspot`](https://docs.maison-labs.com/skills/maison-hubspot/SKILL.md) | HubSpot company links (Maison staff) | 5 |
| [`maison-platform`](https://docs.maison-labs.com/skills/maison-platform/SKILL.md) | Platform, documentation and diagnostics | 7 |
| [`maison-agents`](https://docs.maison-labs.com/skills/maison-agents/SKILL.md) | Agents | 15 |
| [`maison-usage`](https://docs.maison-labs.com/skills/maison-usage/SKILL.md) | LLM usage | 2 |
| [`maison-webhooks`](https://docs.maison-labs.com/skills/maison-webhooks/SKILL.md) | Incoming webhooks | 13 |
| [`maison-apps`](https://docs.maison-labs.com/skills/maison-apps/SKILL.md) | Developer apps | 16 |

## Rules of thumb

- One tool per intent. `create_client` provisions everything; do not chain lower-level calls first.
- Read before write: list/get tools are cheap and give you the exact ids and field names.
- Destructive tools (disable, delete, remove, archive, cancel) — confirm with the user unless they asked explicitly.
- Never print or store the API key, integration credentials or tokens; the API never returns them either.
- Pagination: list tools take `limit` (≤ 100) and return a cursor (`after`/`cursor`); loop until it is null.

## References

- [references/transports.md](references/transports.md) — exact REST, MCP and A2A request shapes.
- [references/errors.md](references/errors.md) — status codes, error codes and the authorization model.
- OpenAPI document: https://maison-labs.com/api/v1/openapi.json · Agent card: https://maison-labs.com/.well-known/agent.json · Skills index: https://docs.maison-labs.com/.well-known/agent-skills/index.json