Maison — Clients (hotels)

Create and manage hotels on Maison: provision a new client in one call (website, default configuration, first scrape, preview site), read or update a client record, disable or re-enable it, rescrape its website, deploy its demo preview site, read its workspace overview, metrics and activity timeline, and inspect or stop running background jobs. Use for onboarding a hotel, changing its settings, or operating it day to day.

Part of the Maison public API. Read the maison-public-api skill first for authentication, discovery and transport details (https://docs.maison-labs.com/skills/maison-public-api/SKILL.md).

When to use

• Onboard a new hotel — create_client does the whole provisioning in one call, plan included.
• Look a hotel up by name or list a portfolio — list_clients, get_client.
• Find live hotels without conversations (or any live/activity mix) in one call — list_clients with liveStatus and activity (conversations in the last activityDays days, default 30), sorted by last activity date (orderBy); read the total, never page the whole portfolio.
• See a hotel at a glance (setup, jobs, knowledge, people, group, latest activity) — get_client_overview, the workspace Overview in one read.
• Change name, description, demo flag, website, scrape language, manual-knowledge or multi-property flag, or report schedules — update_client.
• Diagnose what happened to a hotel — get_client_activity, list_client_jobs.
• Tell whether a hotel is live (the chat widget loads on its own website) — the live_status field on get_client / list_clients; count live hotels for a month, optionally under one group — get_live_clients_report.

Before you start

1. Send x-api-key: <key> on every call; the key only reaches /api/v1.
2. GET /api/v1/tools (or MCP tools/list) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
3. Client-scoped tools take clientId (a hotel id). whoami lists the ids you can act on.

Tools

Full input fields for every tool: references/tools.md.

Recommended workflows

Count live member hotels for an invoice

1. get_live_clients_report with month (YYYY-MM) and the group's nodeId (the group client id; get_client_hierarchy shows its tree).
2. Bill on liveDuringMonthCount (LIVE at any point in the month) or liveAtMonthEndCount, as the contract says; clients lists each hotel with its status at month end.

Onboard a hotel

1. create_client with name and the public website URL (a bare domain is stored as https). Put it on a plan in the same call: planTemplateId (with optional featureOverrides), or noTemplate: true with exactly features. Leave scrapeWebsite true unless the knowledge base will be curated by hand.
2. Set multiProperty: true ONLY for a group/brand site with several properties; it switches the first run to property discovery (see the maison-hierarchy skill) and the site is never scraped whole.
3. Poll list_client_jobs (Maison staff) or get_client_activity until the first scrape finishes; then get_client_metrics to confirm the knowledge base has content.
4. Share the preview site from deploy_preview_site (or the client.previewUrl returned) and the embed code from get_widget_embed_code (platform skill).

Refresh a hotel's knowledge from its website

1. rescrape_client_website (optionally force: true to re-ingest unchanged pages).
2. Track progress with get_client_activity filtered to category: "knowledge".

Tips

• list_clients returns only hotels the key's user may read; a Maison admin sees all.
• update_client changes the client record; hotel configuration (address, hours, policies) lives in the maison-configuration skill (update_hotel_config).
• disable_client is a soft disable — nothing is deleted and enable_client reverses it.
• get_client_activity filters by category (or all but one with excludeCategory), knowledge source, date range and failures; reference resolves an MX-… support reference to its event.
• Every client write (including update_client and stop_client_job) is recorded in the hotel's activity feed, exactly as a console change.

Pitfalls

• Do not call create_client twice for the same hotel; it provisions a new client each time. list_clients with search first.
• create_client, disable_client and enable_client need a GLOBAL clients WRITE grant (Maison staff). A hotel user updating their own hotel uses update_client.
• update_client changes a report schedule only with the Maison-only schedules WRITE grant (403 otherwise, nothing written).
• live_status is recomputed once a day; a widget load shows up the next day. MANUAL_NOT_LIVE is an override set in the console and wins until it is cleared. get_live_clients_report needs a GLOBAL clients READ grant.

Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send x-api-key.

# REST
curl -X POST "https://maison-labs.com/api/v1/client" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{ "name": …, "website": … }'

// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_client", "arguments": { "name": …, "website": … } } }

// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "create_client", "input": { "name": …, "website": … } } }] } } }

Errors are the same everywhere: 401 no/invalid key; 403 forbidden with details.missing (the grants you lack — fall back to the composite's parts or stop); 403 not_entitled (the hotel's plan lacks the feature); 404, 409, 413 too_large, 503. Inputs that fail validation return 400 invalid_input with the Zod issues — fix and retry once.