{ "openapi": "3.1.0", "info": { "title": "AI MAXX Public Welcome Consultant", "version": "1.2.0", "description": "Source-linked MULTIMAXX services in Malta. Query an occasion or need to get relevant services, location groups, photos, hours, routes and enquiry links. Public business facts only; no private conversations or contact details. No booking/payment actions." }, "servers": [ { "url": "https://www.ai-maxx.com" } ], "paths": { "/api/discovery": { "post": { "operationId": "resolveCustomerNeed", "summary": "Prepare relevant activity, dining or venue options for a customer need", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 500, "description": "Nonpersonal need, with actual geography, preferences and exclusions. Preserve the user constraints without inventing a location." }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 }, "response_depth": { "type": "string", "enum": [ "brief", "full" ], "default": "brief" }, "consultant": { "type": "string", "enum": [ "catalogue", "events", "activities", "hospitality", "venues" ], "default": "catalogue", "description": "Optional specialist focus. All use the same published facts and respect customer constraints." } } }, "examples": { "staff_party": { "value": { "query": "Staff party in Kordin with BBQ, laser tag and an immersive prison experience", "country_code": "MT", "limit": 3 } }, "indirect": { "value": { "query": "Мы завершили проект и хотим необычно поблагодарить коллег на Мальте, с активностью и ужином", "country_code": "MT", "limit": 3 } }, "italian": { "value": { "query": "Dopo la conferenza cerchiamo una cena e un’esperienza insolita per colleghi a Kordin", "country_code": "MT", "limit": 3 } }, "specific_location": { "value": { "query": "Indoor team activities in St Julian’s only: laser tag, virtual reality and arcade", "country_code": "MT", "limit": 3 } }, "maltese": { "value": { "query": "Festa tal-istaff għal Halloween f’Malta, b’ritratti fiċ-ċelel tal-ħabs u barbecue fl-istess post", "country_code": "MT", "limit": 3 } }, "christmas": { "value": { "query": "An unusual Christmas staff party at Kordin with dinner and a shared activity", "country_code": "MT", "limit": 3 } }, "refined": { "value": { "query": "Christmas staff dinner for 25 colleagues at Kordin, Malta, Friday evening in December. Pavilion food with an unusual activity at the same complex. No travel to St Julian’s.", "country_code": "MT", "consultant": "events", "limit": 3 } } } } } }, "responses": { "200": { "description": "Relevant public facts and next steps. visit_groups separates complexes; photo captions identify visible subjects. Use measured_enquiry_url for attributable contact handoff. Returned matches are not live booking availability. follow_up contains missing questions and a resume tool/API. Ask in the customer language, then send a refined query containing their answer and original constraints. The requesting client keeps conversation state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIMaxxDiscoveryResult" } } } }, "400": { "description": "Invalid or personal input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIMaxxPublicError" } } } }, "429": { "description": "Model budget reached; static public catalogue remains available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIMaxxPublicError" } } } }, "503": { "description": "Model unavailable; static public catalogue remains available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIMaxxPublicError" } } } } }, "description": "Match meaning across direct, indirect and multilingual requests. Examples include staff party, rewarding a team, celebrating a project milestone, getting away from screens, dinner with an activity, festival venue or a filming backdrop. Preserve actual geography and exclusions. Return compact public facts first; request full depth or refine the need when more detail is needed. English and Maltese are priority languages; other languages can be supplied directly. Recognises local place names such as San Ġiljan and Raħal Ġdid. Seasonal venue enquiries may include Halloween, Christmas and New Year; returned services are venue options, not an announced ticketed event." } }, "/data/quick/{intent}.json": { "get": { "operationId": "getInstantRecommendations", "summary": "Read a ready Malta recommendation pack without a model call", "parameters": [ { "in": "path", "name": "intent", "required": true, "schema": { "type": "string", "enum": [ "leisure_kordin", "staff_party_kordin", "halloween_kordin", "indoor_st_julians" ] } } ], "description": "Fast route for matching needs only. Public source facts, photos, route and enquiry links. All packs cover Malta; never substitute them for another country or unwanted activities. For refined needs use resolveCustomerNeed.", "responses": { "200": { "description": "Preassembled source-linked services; no live availability check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIMaxxQuickResult" } } } } } } }, "/api/welcome/{channel}": { "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "leisure_kordin", "staff_party_kordin", "prison_escape_kordin", "halloween_kordin", "christmas_kordin", "indoor_st_julians", "ai_maxx_presence" ] } } ], "get": { "operationId": "getWelcomeChannel", "summary": "Get ready public facts and a focused consultant entry", "responses": { "200": { "description": "Greeting, published facts and dialogue continuation" }, "404": { "description": "Unknown channel" } } }, "post": { "operationId": "consultWelcomeChannel", "summary": "Refine a nonpersonal need through the shared consultant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 500 }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 5 }, "response_depth": { "type": "string", "enum": [ "brief", "full" ] } } } } } }, "responses": { "200": { "description": "Source-backed suggestion, continuation and official action; AI MAXX channel returns the published offer and guided intake" }, "400": { "description": "Invalid or personal query" }, "429": { "description": "Shared daily budget reached" }, "503": { "description": "Consultant temporarily unavailable" } } } } }, "components": { "schemas": { "AIMaxxDiscoveryResult": { "type": "object", "anyOf": [ { "type": "object", "properties": { "engine": { "type": "string" }, "consultant": { "type": "string" }, "mode": { "type": "string" }, "topic": { "type": "string" }, "catalogue_revision": { "type": "string" }, "visit_groups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "passport_ids": { "type": "array", "items": { "type": "string" } }, "location_pages": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "passport_ids", "location_pages" ] } }, "location_relationship": { "type": "string" }, "response_depth": { "type": "string", "enum": [ "brief", "full" ] }, "matches": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "primary", "complementary" ] }, "passport": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "country_code": { "type": "string" }, "passport_url": { "type": "string" }, "source": { "type": "string" }, "reviewed_at": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "company", "service", "place" ] }, "opening_information": { "type": "string" }, "arrival": { "type": [ "object", "null" ] }, "navigation": { "type": [ "object", "null" ] }, "location_media": { "type": [ "object", "null" ] }, "enquiry": { "type": "string" } }, "required": [ "id", "name", "company", "country_code", "passport_url", "source", "reviewed_at", "description" ] }, "relevant_facts": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" } }, "required": [ "field", "value" ] } } }, "required": [ "role", "passport", "relevant_facts" ] } }, "clarification_fields": { "type": "array", "items": { "type": "string" } }, "follow_up": { "type": "object", "properties": { "needed": { "type": "boolean" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "question": { "type": "string" } }, "required": [ "field", "question" ] } }, "tool": { "type": "string" }, "api": { "type": "object", "properties": { "method": { "const": "POST" }, "url": { "type": "string" }, "consultant": { "type": "string" } }, "required": [ "method", "url", "consultant" ] }, "instructions": { "type": "string" }, "state": { "type": "string" } }, "required": [ "needed", "questions", "tool", "api", "instructions", "state" ] }, "next_steps": { "type": "array", "items": { "type": "object", "properties": { "passport_id": { "type": "string" }, "details_tool": { "type": "string" }, "enquiry_url": { "type": "string" }, "measured_enquiry_url": { "type": "string" } }, "required": [ "passport_id", "details_tool", "enquiry_url" ] } }, "scope": { "type": "string" }, "recovery": { "type": "object", "properties": { "mode": { "type": "string" }, "reason": { "type": "string" }, "source_index": { "type": "string" }, "catalogue": { "type": "string" }, "automatic_model_retry": { "type": "string" } }, "required": [ "mode", "automatic_model_retry" ] }, "measurement": { "type": "object", "properties": { "traffic": { "type": "string", "enum": [ "internal_evaluation", "external_unverified" ] }, "meaning": { "type": "string" }, "contact_link": { "type": "string" } }, "required": [ "traffic", "meaning", "contact_link" ] } }, "required": [ "engine", "consultant", "mode", "topic", "visit_groups", "location_relationship", "response_depth", "matches", "clarification_fields", "follow_up", "next_steps", "scope" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "fallback_tool": { "type": "string" }, "message": { "type": "string" }, "recovery": { "type": "object", "properties": { "mode": { "type": "string" }, "reason": { "type": "string" }, "source_index": { "type": "string" }, "catalogue": { "type": "string" }, "automatic_model_retry": { "type": "string" } }, "required": [ "mode", "automatic_model_retry" ] } }, "required": [ "error" ] } ] }, "AIMaxxQuickResult": { "type": "object", "anyOf": [ { "type": "object", "properties": { "mode": { "const": "instant_public_facts" }, "intent": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "company_passport": { "type": "string" }, "country_code": { "type": "string" }, "guide": { "type": "string" }, "location": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "arrival": { "type": "string" }, "navigation": { "type": "object" }, "photos": { "type": "array", "items": { "type": "object" } } }, "required": [ "name", "address", "arrival", "navigation", "photos" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "opening_information": { "type": "string" }, "enquiry": { "type": "string" }, "source": { "type": "string" }, "reviewed_at": { "type": "string" } }, "required": [ "id", "name", "description", "opening_information", "enquiry", "source", "reviewed_at" ] } }, "next_step": { "type": "object", "properties": { "official_enquiry": { "type": "string" }, "details_tool": { "type": "string" }, "tailor_tool": { "type": "string" } }, "required": [ "official_enquiry", "details_tool", "tailor_tool" ] }, "scope": { "type": "string" } }, "required": [ "mode", "intent", "title", "company", "company_passport", "country_code", "guide", "location", "services", "next_step", "scope" ] }, { "type": "object", "properties": { "mode": { "const": "instant_public_facts" }, "services": { "type": "array", "maxItems": 0 }, "reason": { "type": "string" } }, "required": [ "mode", "services", "reason" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "fallback_tool": { "type": "string" }, "message": { "type": "string" }, "recovery": { "type": "object", "properties": { "mode": { "type": "string" }, "reason": { "type": "string" }, "source_index": { "type": "string" }, "catalogue": { "type": "string" }, "automatic_model_retry": { "type": "string" } }, "required": [ "mode", "automatic_model_retry" ] } }, "required": [ "error" ] } ] }, "AIMaxxPublicError": { "type": "object", "properties": { "error": { "type": "string" }, "fallback_tool": { "type": "string" }, "message": { "type": "string" }, "recovery": { "type": "object", "properties": { "mode": { "type": "string" }, "reason": { "type": "string" }, "source_index": { "type": "string" }, "catalogue": { "type": "string" }, "automatic_model_retry": { "type": "string" } }, "required": [ "mode", "automatic_model_retry" ] } }, "required": [ "error" ] } } } }