Maison — Knowledge base

Manage what a hotel's concierge knows: website and document knowledge sources (add, sync, rescrape, disable/reactivate, follow a run and its log and report, rediscover booking links, versions, download, large uploads), curated Q&A pairs (add, update, publish, unpublish, delete, version history), unanswered-question gaps (list, detect, answer, dismiss, reopen) and knowledge quality runs (deduplicate, consistency check, their reports). Use when a hotel's answers are missing, wrong or stale, or when adding new content.

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

• Add a page or site to a hotel's knowledge — add_website_source.
• Upload a PDF/brochure/policy — add_document_source (≤ 64 KiB inline as bytesBase64).
• Upload a document over 64 KiB — create_document_upload, PUT the file to its url with its headers, then add_document_source (or add_document_version) with the uploadId.
• Take a source out of the agent's knowledge without losing it — disable_source; undo with reactivate_source.
• Follow a scrape, sync or ingestion — list_source_runs (the source's id from list_knowledge_sources), then get_source_run_logs with after: lastSeq until finished; get_website_scrape for the step-by-step view of a website run.
• Read what a finished website scrape or sync changed — get_source_run_report (the run's sessionId): the report inline, or format: "pdf" for a download link to the PDF the report email attaches.
• A hotel changed booking engine — discover_booking_links (no full rescrape).
• Fix a specific wrong answer — list_qa_pairs with search, then update_qa_pair.
• Find what guests asked that the concierge could not answer — list_knowledge_gaps, then answer_knowledge_gap.
• Find conflicting or duplicate answers — check_knowledge_consistency or deduplicate_knowledge (each returns a sessionId), then get_knowledge_quality_run until finished for the report; list_knowledge_quality_runs for past runs.

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

Add content and make it live

1. add_website_source (domain URL) or add_document_source (name, filename, mimeType, and bytesBase64 or an uploadId from create_document_upload).
2. Ingestion is queued; list_knowledge_sources shows scrapeStatus / lastSuccessfulIngestAt when it has landed.
3. For hand-written facts use add_qa_pairs — new pairs are published on creation; unpublish_qa_pairs takes one out of answers without deleting it (unpublished pairs are not used).

Close knowledge gaps

1. detect_knowledge_gaps answers 202 { queued: true } at once; poll list_knowledge_gaps (its lastSession) with status: "OPEN".
2. For each gap: answer_knowledge_gap with an answer (optionally a reworded question) to create the Q&A pair — live at once, new pairs are stored published — or with qaId to link a pair that already answers it (nothing is created, its publish state is unchanged); dismiss_knowledge_gap when it is noise (gapIds dismisses many in one call); reopen_knowledge_gap to undo either.
3. Run deduplicate_knowledge and check_knowledge_consistency after a large import; read each report with get_knowledge_quality_run and fix the conflicting pairs with update_qa_pair.

Tips

• Q&A versions are kept: list_qa_versions + restore_qa_version undo a bad edit.
• set_main_website_source marks the website that also drives the preview site; set_source_sync_schedule is Maison-staff only.

Pitfalls

• A sync_source on a document re-ingests the stored file; a scrape_website_source fetches the live site. Do not confuse them.
• list_qa_pairs can return 503 when semantic search is down — retry later rather than concluding the knowledge base is empty.
• Inline base64 uploads over 64 KiB are rejected with 413 too_large — use create_document_upload.
• download_document returns bytesBase64 up to 64 KiB, else downloadUrl + expiresAt (15 minutes).
• update_qa_pair takes question, answer or both; the field left out keeps its stored value.
• sync_source / scrape_website_source / discover_booking_links answer 409 for a disabled source — reactivate_source first.
• add_website_source with a syncSchedule other than NONE needs Maison-staff schedules WRITE (403 otherwise, nothing created).

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/<clientId>/source/document" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{ "name": …, "filename": …, "mimeType": … }'

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

// 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": "add_document_source", "input": { "name": …, "filename": …, "mimeType": … } } }] } } }

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.