--- name: "maison-clients" description: "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. Tools: create_client, deploy_preview_site, disable_client, enable_client, get_client, get_client_activity, get_client_metrics, get_client_overview, get_clients_summary, get_live_clients_report, list_client_jobs, list_clients, rescrape_client_website, stop_client_job, update_client." license: "Proprietary. Use with a Maison API key under the Maison terms of service." metadata: author: "maison-labs" version: "1.0.0" category: "clients" api-base: "https://maison-labs.com" openapi: "https://maison-labs.com/api/v1/openapi.json" docs: "https://docs.maison-labs.com/skills/maison-clients/" --- # 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: ` 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 | Tool | What it does | REST | Needs | | --- | --- | --- | --- | | `create_client` | Provision a hotel in one call: creates the client on its feature plan, links its website as the main knowledge source, seeds the default hotel configuration and chatbot tone, queues the first website scrape (or property discovery for a multi-property group), and deploys the demo preview site. | `POST /api/v1/client` | clients WRITE (global) | | `deploy_preview_site` | Create or recreate the hosted demo page that embeds the client's chat widget, and return its URL. | `POST /api/v1/client/{clientId}/previewsite` | clients EXECUTE (client); plan: `update-client` | | `disable_client` | Switch a hotel off as if its account were deleted; nothing is deleted. | `POST /api/v1/client/{clientId}/disable` | clients WRITE (global); destructive | | `enable_client` | Switch a disabled hotel back on: its chat widget, chats, channels, agents, jobs, webhooks and public API access resume, and it appears in active listings again. | `POST /api/v1/client/{clientId}/enable` | clients WRITE (global) | | `get_client` | The full client record (settings, website, scrape state, schedules, IANA timezone, computed flags) and its automatic live status: `live_status` (LIVE = the chat widget loaded on the hotel's own website in the last 7 days; CHURN_RISK = no load for 14 days; NOT_LIVE; MANUAL_NOT_LIVE = the override in Settings), `live_since`, `live_last_seen_at`, `live_last_seen_host`, `live_manual_not_live`. | `GET /api/v1/client/{clientId}` | clients READ (client); read-only | | `get_client_activity` | The audit/activity timeline for a hotel (knowledge, configuration, brand, connections, access, reports, account, health, notes), newest first, with cursor paging (`direction: newer` pages towards the present) and filters: one category or all but one (`excludeCategory`), failed only, a date range, one knowledge source (`source`), or one event by its `MX-…` support reference. | `GET /api/v1/client/{clientId}/activity` | client-activity READ (client); plan: `client-activity`; read-only | | `get_client_metrics` | Headline numbers for one hotel: conversations, knowledge size, last scrape, channel counts. | `GET /api/v1/client/{clientId}/metrics` | clients READ (client); read-only | | `get_client_overview` | The client workspace Overview in one read: identity (name, website, demo site), setup progress, scheduled and recent jobs, knowledge, people, group (parent/children), latest activity, latest note and a timeline. | `GET /api/v1/client/{clientId}/overview` | clients READ (client); read-only | | `get_clients_summary` | Counts of active, disabled, demo and recently created clients across the caller's portfolio. | `GET /api/v1/clients/summary` | clients READ (any); read-only | | `get_live_clients_report` | For one month (`YYYY-MM`, UTC), the clients that were LIVE at any point in it and how many were still LIVE at month end, optionally limited to the clients under one hierarchy node (`nodeId`: every descendant in `client_hierarchy`, the node itself excluded). | `GET /api/v1/clients/livereport` | clients READ (global); read-only | | `list_client_jobs` | Pipeline jobs (scrapes, ingests, reports) currently running for a hotel, with task ids usable by `stop_client_job`. | `GET /api/v1/client/{clientId}/jobs` | jobs EXECUTE (global); read-only | | `list_clients` | Page through the hotels the caller can see, with search, status filter and sort. | `GET /api/v1/clients` | clients READ (any); read-only | | `rescrape_client_website` | Queue a fresh scrape of the client's main website into its knowledge base. | `POST /api/v1/client/{clientId}/rescrape` | document-source EXECUTE (client) | | `stop_client_job` | Stop one running pipeline job for a hotel (a stopped scrape is marked canceled). | `DELETE /api/v1/client/{clientId}/job/{taskId}` | jobs EXECUTE (global); destructive | | `update_client` | Partial update of the client record: name, description, demo flag, website, scrape language, manual-knowledge and multi-property flags, report schedules, and the hotel's IANA timezone (400 `invalid_timezone` for a zone outside the runtime's Intl list). | `PUT /api/v1/client/{clientId}` | update-client WRITE (client); plan: `update-client` | Full input fields for every tool: [references/tools.md](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`. ```bash # 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": … }' ``` ```json // 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": … } } } ``` ```json // 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.