{ "openapi": "3.1.0", "info": { "title": "DBC Venue Intelligence API", "version": "0.1.0", "description": "Independent Sydney coastal venue visitor-rule, cost and consent-gated quote tools. Demo records are synthetic. No endpoint creates a booking." }, "servers": [ { "url": "https://diamondbayclub.com", "description": "Noindex synthetic-data staging deployment" }, { "url": "http://127.0.0.1:8787", "description": "Local development" } ], "paths": { "/api/v1/status": { "get": { "operationId": "get_data_status", "summary": "Get data status", "description": "Read the current publication view status, dataset version, published record counts, freshness policy and known availability boundaries. Use before relying on venue search results or explaining why a result is empty. Do not interpret published record counts as live inventory or a booking; availability remains unknown without an inventory integration. This read-only tool has no external side effects.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "status": { "type": "string", "const": "operational" }, "mode": { "type": "string", "enum": [ "demo", "production" ] }, "dataset_version": { "type": "string", "minLength": 1 }, "published_records": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "real_records": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "synthetic_records": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventory_integrations": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "availability_status": { "type": "string", "const": "unknown" }, "booking_status": { "type": "string", "const": "not_created" }, "freshness": { "type": "string", "const": "static" }, "checked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "research_queue": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "refresh_completed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "review_due_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "candidate_dataset_version": { "type": "string", "minLength": 1 }, "candidate_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "locality_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "locality_distribution": { "type": "array", "items": { "type": "object", "properties": { "locality": { "type": "string", "minLength": 1 }, "candidate_count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "area_id": { "type": "string", "minLength": 1 } }, "required": [ "locality", "candidate_count" ], "additionalProperties": false } }, "signal_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "signal_distribution": { "type": "array", "items": { "type": "object", "properties": { "signal": { "type": "string", "minLength": 1 }, "candidate_count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "signal", "candidate_count" ], "additionalProperties": false } }, "ready_for_production": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blocked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "review_gates": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "approved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pending", "approved", "rejected" ], "additionalProperties": false }, "facts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "approved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pending", "approved", "rejected" ], "additionalProperties": false }, "rights": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "approved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pending", "approved", "rejected" ], "additionalProperties": false }, "publication": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "approved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pending", "approved", "rejected" ], "additionalProperties": false } }, "required": [ "identity", "facts", "rights", "publication" ], "additionalProperties": false }, "coverage_facets": { "type": "object", "properties": { "waterfront": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sailing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_hire": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "club_facilities": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "waterfront", "sailing", "event_hire", "dining", "club_facilities" ], "additionalProperties": false }, "source_health": { "type": "object", "properties": { "checked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "previous_checked_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "reachable": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "http_errors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "request_errors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "redirects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata_changed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata_reviewed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata_attention_pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "checked_at", "reachable", "http_errors", "request_errors", "redirects" ], "additionalProperties": false } }, "required": [ "generated_at", "refresh_completed_at", "review_due_at", "candidate_dataset_version", "candidate_count", "locality_count", "signal_count", "ready_for_production", "blocked", "review_gates", "coverage_facets", "source_health" ], "additionalProperties": false } }, "required": [ "status", "mode", "dataset_version", "published_records", "real_records", "synthetic_records", "inventory_integrations", "availability_status", "booking_status", "freshness", "checked_at", "research_queue" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "parameters": [] } }, "/api/v1/venues": { "get": { "operationId": "search_coastal_venues", "summary": "Search coastal venues", "description": "Find coastal Sydney venue candidates that match an area, activity, group size and required features. Use it to create a shortlist before inspecting a venue or evaluating a visit. Do not use it as proof of live availability or a confirmed booking; inventory is not connected. Returns stable venue IDs, match reasons, known restrictions and conditions that still require confirmation. This read-only tool has no external side effects.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "name": { "type": "string" }, "slug": { "type": "string" }, "country": { "type": "string", "const": "au" }, "area_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "area_name": { "type": "string" }, "summary": { "type": "string" }, "activities": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "match_reasons": { "type": "array", "items": { "type": "string" } }, "known_restrictions": { "type": "array", "items": { "type": "string" } }, "conditions_to_confirm": { "type": "array", "items": { "type": "string" } }, "is_example": { "type": "boolean" }, "data_class": { "type": "string", "enum": [ "real", "research_only", "synthetic" ] }, "profile_url": { "type": "string" } }, "required": [ "venue_id", "name", "slug", "country", "area_id", "area_name", "summary", "activities", "features", "match_reasons", "known_restrictions", "conditions_to_confirm", "is_example", "data_class", "profile_url" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "returned": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total_matching": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "data_summary": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "demo", "production" ] }, "real_records": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "synthetic_records": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "mode", "real_records", "synthetic_records" ], "additionalProperties": false }, "research_coverage": { "type": "object", "properties": { "scope": { "type": "string", "const": "aggregate_only" }, "candidate_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "locality_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "locality_distribution": { "type": "array", "items": { "type": "object", "properties": { "locality": { "type": "string", "minLength": 1 }, "candidate_count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "area_id": { "type": "string", "minLength": 1 } }, "required": [ "locality", "candidate_count" ], "additionalProperties": false } }, "signal_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ready_for_production": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blocked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "generated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "refresh_completed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "review_due_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "source_health": { "type": "object", "properties": { "checked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "previous_checked_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "reachable": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "http_errors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "request_errors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "redirects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata_changed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata_reviewed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata_attention_pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "checked_at", "reachable", "http_errors", "request_errors", "redirects" ], "additionalProperties": false } }, "required": [ "scope", "candidate_count", "locality_count", "signal_count", "ready_for_production", "blocked", "generated_at", "refresh_completed_at", "review_due_at", "source_health" ], "additionalProperties": false } }, "required": [ "items", "next_cursor", "returned", "total_matching", "data_summary" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "parameters": [ { "name": "area_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } }, { "name": "activity_type", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } }, { "name": "group_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "required_features", "in": "query", "required": true, "schema": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } } ] } }, "/api/v1/venues/{venue_id}": { "get": { "operationId": "get_venue_profile", "summary": "Get venue profile", "description": "Read the current authorised profile for one venue by stable ID, including activity-specific policies, price structure, provenance and review dates. Use after search or when the exact venue ID is known. Do not use it to infer live availability, merchant acceptance or booking status. This read-only tool returns only fields permitted for the current distribution view.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "name": { "type": "string" }, "slug": { "type": "string" }, "country": { "type": "string", "const": "au" }, "area_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "area_name": { "type": "string" }, "summary": { "type": "string" }, "activities": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "spaces": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "policies": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "price_structure": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "membership_plan": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "official_entry_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "name": { "type": "string" }, "locator": { "type": "string" }, "retrieved_at": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "review_due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "locator", "retrieved_at", "verified_at", "review_due_at" ], "additionalProperties": false } }, "is_example": { "type": "boolean" }, "data_class": { "type": "string", "enum": [ "real", "research_only", "synthetic" ] }, "publication_status": { "type": "string", "enum": [ "draft", "published", "withdrawn" ] }, "availability_status": { "type": "string", "const": "unknown" }, "booking_status": { "type": "string", "const": "not_created" }, "dataset_version": { "type": "string" } }, "required": [ "venue_id", "name", "slug", "country", "area_id", "area_name", "summary", "activities", "features", "spaces", "policies", "price_structure", "membership_plan", "official_entry_url", "sources", "is_example", "data_class", "publication_status", "availability_status", "booking_status", "dataset_version" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "parameters": [ { "name": "venue_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } }, { "name": "fields", "in": "query", "required": false, "schema": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "identity", "location", "activities", "features", "policies", "prices", "sources", "official_entry" ] } } } ] } }, "/api/v1/visit-evaluations": { "post": { "operationId": "evaluate_visit_constraints", "summary": "Evaluate visit constraints", "description": "Evaluate known visitor, activity, space, age, date and feature rules for a venue. Use when a concrete group and date need an evidence-backed eligibility result. Do not use it to claim the venue is open, has capacity or accepted a booking. Returns eligible, conditional, not_eligible or unknown with each check and missing evidence. Read-only with no external side effects.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "eligibility": { "type": "string", "enum": [ "eligible", "conditional", "not_eligible", "unknown" ] }, "availability_status": { "type": "string", "const": "unknown" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "outcome": { "type": "string", "enum": [ "pass", "fail", "conditional", "unknown" ] }, "explanation": { "type": "string" }, "source_id": { "type": [ "string", "null" ] } }, "required": [ "rule", "outcome", "explanation", "source_id" ], "additionalProperties": false } }, "missing_conditions": { "type": "array", "items": { "type": "string" } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "venue_id", "eligibility", "availability_status", "checks", "missing_conditions", "limitations" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "activity_type": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "space_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "event_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "timezone": { "default": "Australia/Sydney", "type": "string", "const": "Australia/Sydney" }, "group_size": { "type": "integer", "minimum": 1, "maximum": 500 }, "age_bands": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "minimum_age": { "type": "integer", "minimum": 0, "maximum": 125 }, "maximum_age": { "type": "integer", "minimum": 0, "maximum": 125 }, "count": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "minimum_age", "maximum_age", "count" ], "additionalProperties": false } }, "required_features": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } } }, "required": [ "venue_id", "activity_type", "event_date", "timezone", "group_size", "age_bands", "required_features" ], "additionalProperties": false } } } } } }, "/api/v1/event-cost-estimates": { "post": { "operationId": "estimate_event_cost", "summary": "Estimate event cost", "description": "Calculate an AUD event cost from an authorised venue rule or a user-supplied rule using integer minor units. Use for transparent line-item estimates, minimum-spend treatment, credited deposits and refundable bonds. Do not treat a user rule as an official quote or fill unknown mandatory fees with zero. Returns a complete total only when mandatory cost and tax treatment are known. Read-only with no external side effects.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "currency": { "type": "string", "const": "AUD" }, "status": { "type": "string", "enum": [ "complete", "quote_required", "not_applicable" ] }, "price_type": { "type": "string", "enum": [ "synthetic_fixture", "venue_published", "user_supplied" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "amount_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "treatment": { "type": "string", "enum": [ "included", "credited_prepayment", "refundable_security" ] } }, "required": [ "code", "label", "amount_minor", "treatment" ], "additionalProperties": false } }, "known_subtotal_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total_minor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "prepaid_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "non_refundable_remaining_minor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "refundable_bond_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "assumptions": { "type": "array", "items": { "type": "string" } }, "unknown_items": { "type": "array", "items": { "type": "string" } } }, "required": [ "currency", "status", "price_type", "line_items", "known_subtotal_minor", "total_minor", "prepaid_minor", "non_refundable_remaining_minor", "refundable_bond_minor", "assumptions", "unknown_items" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "user_supplied_price_rule": { "type": "object", "properties": { "currency": { "type": "string", "const": "AUD" }, "per_person_activity_minor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000000 }, "venue_hire_minor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000000 }, "expected_food_beverage_minor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000000 }, "minimum_spend_minor": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "null" } ] }, "minimum_spend_scope": { "default": null, "anyOf": [ { "type": "string", "enum": [ "food_beverage", "venue_total" ] }, { "type": "null" } ] }, "mandatory_surcharge_minor": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "null" } ] }, "deposit_minor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000000 }, "deposit_credited_to_total": { "default": true, "type": "boolean" }, "refundable_bond_minor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxes_included": { "default": null, "type": [ "boolean", "null" ] }, "other_mandatory_fees_known": { "default": true, "type": "boolean" } }, "required": [ "currency", "per_person_activity_minor", "venue_hire_minor", "expected_food_beverage_minor", "minimum_spend_minor", "minimum_spend_scope", "mandatory_surcharge_minor", "deposit_minor", "deposit_credited_to_total", "refundable_bond_minor", "taxes_included", "other_mandatory_fees_known" ], "additionalProperties": false }, "group_size": { "type": "integer", "minimum": 1, "maximum": 500 }, "event_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "type": "string", "const": "AUD" }, "consumption_plan": { "default": {}, "type": "object", "properties": { "expected_food_beverage_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000 } }, "additionalProperties": false } }, "required": [ "group_size", "event_date", "currency", "consumption_plan" ], "additionalProperties": false } } } } } }, "/api/v1/venue-comparisons": { "post": { "operationId": "compare_venue_options", "summary": "Compare venue options", "description": "Compare two to five venues against one identical activity requirement. Use after choosing candidate IDs to see hard exclusions, unknown conditions, comparable cost and explainable ordering. Do not compare mismatched dates, currencies or group requirements, and do not rank missing prices as cheapest. Read-only with no external side effects.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "comparable_currency": { "type": "string", "const": "AUD" }, "ranking_basis": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "items": { "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "name": { "type": "string" }, "eligibility": { "type": "string", "enum": [ "eligible", "conditional", "not_eligible", "unknown" ] }, "hard_constraint_excluded": { "type": "boolean" }, "total_minor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "price_status": { "type": "string", "enum": [ "complete", "quote_required", "not_applicable" ] }, "pending_confirmations": { "type": "array", "items": { "type": "string" } }, "rank": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "explanation": { "type": "array", "items": { "type": "string" } } }, "required": [ "venue_id", "name", "eligibility", "hard_constraint_excluded", "total_minor", "price_status", "pending_confirmations", "rank", "explanation" ], "additionalProperties": false } } }, "required": [ "comparable_currency", "ranking_basis", "options" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "venue_ids": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } }, "activity_type": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "event_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "timezone": { "default": "Australia/Sydney", "type": "string", "const": "Australia/Sydney" }, "group_size": { "type": "integer", "minimum": 1, "maximum": 500 }, "age_bands": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "minimum_age": { "type": "integer", "minimum": 0, "maximum": 125 }, "maximum_age": { "type": "integer", "minimum": 0, "maximum": 125 }, "count": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "minimum_age", "maximum_age", "count" ], "additionalProperties": false } }, "required_features": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } }, "currency": { "type": "string", "const": "AUD" }, "consumption_plan": { "default": { "expected_food_beverage_minor": 0 }, "type": "object", "properties": { "expected_food_beverage_minor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000000 } }, "required": [ "expected_food_beverage_minor" ], "additionalProperties": false } }, "required": [ "venue_ids", "activity_type", "event_date", "timezone", "group_size", "age_bands", "required_features", "currency", "consumption_plan" ], "additionalProperties": false } } } } } }, "/api/v1/membership-break-even": { "post": { "operationId": "calculate_membership_break_even", "summary": "Calculate membership break-even", "description": "Calculate how many comparable visits are needed to recover an AUD membership and joining fee. Use only when the member and non-member per-visit benefits are stable and measured on the same basis. Do not assign value to complex or unknown benefits. Returns not_economical when savings are non-positive and notes plan or validity limits. Read-only with no external side effects.", "tags": [ "Public tools" ], "security": [], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "currency": { "type": "string", "const": "AUD" }, "status": { "type": "string", "enum": [ "break_even_possible", "not_economical", "insufficient_information", "outside_validity" ] }, "net_saving_per_visit_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "break_even_visits": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "planned_visits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "planned_net_saving_minor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "breaks_even_within_plan": { "type": "boolean" }, "validity_limit_visits": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "explanation": { "type": "string" } }, "required": [ "currency", "status", "net_saving_per_visit_minor", "break_even_visits", "planned_visits", "planned_net_saving_minor", "breaks_even_within_plan", "validity_limit_visits", "explanation" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "membership_fee_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "joining_fee_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "non_member_cost_per_visit_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "member_cost_per_visit_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "membership_validity_visits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "planned_visits": { "type": "integer", "minimum": 0, "maximum": 10000 }, "currency": { "type": "string", "const": "AUD" }, "benefits_are_comparable_and_stable": { "default": true, "type": "boolean" } }, "required": [ "membership_fee_minor", "joining_fee_minor", "non_member_cost_per_visit_minor", "member_cost_per_visit_minor", "membership_validity_visits", "planned_visits", "currency", "benefits_are_comparable_and_stable" ], "additionalProperties": false } } } } } }, "/api/v1/quote-requests/drafts": { "post": { "operationId": "prepare_quote_request", "summary": "Prepare quote request", "description": "Create or update a private quote draft for one to three user-selected venues. Use after the user has chosen recipients and supplied event requirements. Do not use it to send a message or create a booking. Persists a private draft and returns a browser confirmation URL; requires user authentication and quotes:draft.", "tags": [ "Consent-gated quote tools" ], "security": [ { "oidc": [ "quotes:draft" ] } ], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "quote_request_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "draft_version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "channel_type": { "type": "string", "enum": [ "email", "webhook" ] }, "display_label": { "type": "string" }, "address_display": { "type": "string" } }, "required": [ "venue_id", "channel_type", "display_label", "address_display" ], "additionalProperties": false } }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "confirmation_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "const": "draft" }, "booking_status": { "type": "string", "const": "not_created" }, "external_effect": { "type": "boolean", "const": false } }, "required": [ "quote_request_id", "draft_version", "recipients", "missing_fields", "confirmation_url", "status", "booking_status", "external_effect" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "private_persistence", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "venue_ids": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } }, "event_requirements": { "type": "object", "properties": { "activity_type": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "event_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "timezone": { "type": "string", "const": "Australia/Sydney" }, "group_size": { "type": "integer", "minimum": 1, "maximum": 500 }, "age_bands": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "minimum_age": { "type": "integer", "minimum": 0, "maximum": 125 }, "maximum_age": { "type": "integer", "minimum": 0, "maximum": 125 }, "count": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "minimum_age", "maximum_age", "count" ], "additionalProperties": false } }, "required_features": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } } }, "required": [ "activity_type", "event_date", "timezone", "group_size", "age_bands", "required_features" ], "additionalProperties": false }, "message": { "type": "string", "minLength": 20, "maxLength": 4000 } }, "required": [ "venue_ids", "event_requirements", "message" ], "additionalProperties": false } } } } } }, "/api/v1/quote-requests/{id}/submit": { "post": { "operationId": "submit_quote_request", "summary": "Submit quote request", "description": "Consume a server-recorded, unexpired human confirmation and queue the matching quote request exactly once. Use only after the protected browser confirmation shows recipients, complete content and shared contact data. Do not pass a boolean or model assertion as consent. May cause external delivery only when production identity, verified merchant channels and the delivery provider are explicitly enabled; booking_status remains not_created.", "tags": [ "Consent-gated quote tools" ], "security": [ { "oidc": [ "quotes:submit" ] } ], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "quote_request_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "quote_status": { "type": "string", "enum": [ "draft", "awaiting_consent", "queued", "dispatched", "awaiting_venue_response", "quoted", "declined", "expired", "delivery_failed", "reconciliation_required" ] }, "booking_status": { "type": "string", "const": "not_created" }, "task_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "task_status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "delivery_status": { "type": "string", "enum": [ "queued", "simulation_recorded", "provider_accepted", "failed" ] }, "delivery_mode": { "type": "string", "enum": [ "simulation", "external" ] }, "external_effect": { "type": "boolean" } }, "required": [ "quote_request_id", "quote_status", "booking_status", "task_id", "task_status", "delivery_status", "delivery_mode", "external_effect" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "external_action", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "quote_request_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "consent_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "draft_version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "idempotency_key": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "quote_request_id", "consent_id", "draft_version", "idempotency_key" ], "additionalProperties": false } } } } } }, "/api/v1/quote-requests/{id}": { "get": { "operationId": "get_quote_request_status", "summary": "Get quote request status", "description": "Read the authenticated owner's private quote workflow, recipient delivery states and verified venue response receipts. Use after preparing or submitting a known request. Do not expose it as public data and do not interpret provider acceptance as a venue quote or booking. Requires quotes:read and object ownership; it has no new external side effect.", "tags": [ "Consent-gated quote tools" ], "security": [ { "oidc": [ "quotes:read" ] } ], "responses": { "200": { "description": "The tool executed. Domain outcomes may still be unknown or conditional.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "result", "sources", "generated_at", "schema_version", "dataset_version", "limitations", "next_actions" ], "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "result": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "quote_request_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "status": { "type": "string", "enum": [ "draft", "awaiting_consent", "queued", "dispatched", "awaiting_venue_response", "quoted", "declined", "expired", "delivery_failed", "reconciliation_required" ] }, "booking_status": { "type": "string", "const": "not_created" }, "submitted_at": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "venue_id": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" }, "channel_type": { "type": "string", "enum": [ "email", "webhook" ] }, "display_label": { "type": "string" }, "delivery_status": { "type": "string", "enum": [ "not_queued", "queued", "simulation_recorded", "provider_accepted", "delivered", "failed", "unknown", "cancelled" ] }, "venue_response_status": { "type": "string", "enum": [ "none", "received", "quoted", "declined" ] }, "provider_message_id": { "type": [ "string", "null" ] } }, "required": [ "venue_id", "channel_type", "display_label", "delivery_status", "venue_response_status", "provider_message_id" ], "additionalProperties": false } } }, "required": [ "quote_request_id", "status", "booking_status", "submitted_at", "recipients" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string", "format": "date-time" }, "schema_version": { "type": "string" }, "dataset_version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-side-effect": "read_only", "parameters": [ { "name": "quote_request_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$" } } ] } } }, "components": { "securitySchemes": { "oidc": { "type": "openIdConnect", "openIdConnectUrl": "https://REPLACE_WITH_APPROVED_ISSUER/.well-known/openid-configuration", "description": "Production private routes stay disabled until an approved OIDC issuer is configured." } }, "responses": { "BadRequest": { "description": "Malformed request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "Unauthenticated": { "description": "User authentication is required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "Forbidden": { "description": "The caller lacks scope or object ownership.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "NotFound": { "description": "The object is absent or not visible in this publication view.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "Conflict": { "description": "Idempotency, version or workflow conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "InvalidRequest": { "description": "Schema validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "RateLimited": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "Unavailable": { "description": "A configured external dependency is unavailable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "request_id", "error", "generated_at", "schema_version", "dataset_version" ], "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }