{
  "openapi": "3.1.0",
  "info": {
    "title": "Synch Exhibition Agent API",
    "version": "1.0.0",
    "description": "Agent-native API for Synch Exhibition — the transaction and ROI layer for trade shows, exhibitions, and B2B event meetings. AI agents can discover exhibitions, search exhibitors, match buyers, schedule meetings, track outcomes, and generate ROI reports.\n\n**Business Boundary:** Synch does not guarantee sales, buyer attendance, purchase orders, or ROI. Meeting recommendations are based on structured event data and participant-provided information. Commercial outcomes depend on follow-up and human business decisions.",
    "contact": {
      "name": "Synch Developer Access",
      "email": "support@synch-exhibition.com",
      "url": "https://synch-exhibition.com/agents"
    },
    "license": {
      "name": "Commercial API — Request Access",
      "url": "https://synch-exhibition.com/agents"
    }
  },
  "servers": [
    {
      "url": "https://synch-exhibition.com/api",
      "description": "Production"
    }
  ],
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Synch-API-Key",
        "description": "API key for authenticated write operations. Read-only search endpoints are public. Contact support@synch-exhibition.com to request access."
      }
    },
    "schemas": {
      "Exhibition": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "exh_2026_autotech_taipei" },
          "name": { "type": "string", "example": "台灣自動化技術展 2026" },
          "name_en": { "type": "string", "example": "Taiwan AutoTech Expo 2026" },
          "organizer": { "type": "string", "example": "台灣機械工業同業公會" },
          "industry": { "type": "string", "example": "manufacturing_automation" },
          "location": {
            "type": "object",
            "properties": {
              "venue": { "type": "string", "example": "台北世界貿易中心南港展覽館" },
              "city": { "type": "string", "example": "台北" },
              "country": { "type": "string", "example": "TW" }
            }
          },
          "dates": {
            "type": "object",
            "properties": {
              "start": { "type": "string", "format": "date", "example": "2026-10-15" },
              "end": { "type": "string", "format": "date", "example": "2026-10-18" }
            }
          },
          "exhibitor_count": { "type": "integer", "example": 320 },
          "buyer_count": { "type": "integer", "example": 1850 },
          "agent_operable": { "type": "boolean", "description": "Whether this exhibition has agent-callable meeting scheduling enabled", "example": true },
          "meeting_format": { "type": "string", "enum": ["onsite", "hybrid", "virtual"], "example": "onsite" },
          "status": { "type": "string", "enum": ["upcoming", "active", "post_event", "closed"], "example": "upcoming" }
        }
      },
      "Exhibitor": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "exr_abc_robotics_2026" },
          "company_name": { "type": "string", "example": "旭日機器人科技股份有限公司" },
          "company_name_en": { "type": "string", "example": "Sunrise Robotics Technology Co., Ltd." },
          "booth": { "type": "string", "example": "Hall A, Booth A205" },
          "country": { "type": "string", "example": "TW" },
          "product_categories": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["industrial_robots", "automation_controllers", "vision_systems"]
          },
          "target_buyer_profile": {
            "type": "object",
            "properties": {
              "industries": { "type": "array", "items": { "type": "string" }, "example": ["automotive", "electronics", "food_processing"] },
              "buyer_types": { "type": "array", "items": { "type": "string" }, "example": ["procurement_manager", "plant_manager", "cto"] },
              "company_size": { "type": "string", "example": "50_to_500_employees" },
              "geographies": { "type": "array", "items": { "type": "string" }, "example": ["TW", "JP", "KR", "SG"] }
            }
          },
          "meeting_availability": { "type": "boolean", "example": true },
          "verification_status": { "type": "string", "enum": ["verified", "pending", "unverified"], "example": "verified" },
          "match_score_available": { "type": "boolean", "description": "Whether a buyer-exhibitor match score can be computed for this exhibitor", "example": true }
        }
      },
      "Buyer": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "byr_delta_procurement_2026" },
          "company_name": { "type": "string", "example": "台達電子工業股份有限公司" },
          "procurement_intent": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["industrial_robots", "conveyor_systems", "quality_inspection_equipment"]
          },
          "budget_range": { "type": "string", "example": "5M_to_20M_TWD" },
          "geography": { "type": "string", "example": "TW" },
          "industry": { "type": "string", "example": "electronics_manufacturing" },
          "meeting_slots_available": { "type": "integer", "example": 6 },
          "buyer_type": { "type": "string", "enum": ["procurement_manager", "engineering_manager", "cto", "ceo", "plant_manager"], "example": "procurement_manager" },
          "verification_status": { "type": "string", "enum": ["verified", "pending", "unverified"], "example": "verified" }
        }
      },
      "Meeting": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "mtg_7f3a9b2c" },
          "exhibition_id": { "type": "string", "example": "exh_2026_autotech_taipei" },
          "exhibitor_id": { "type": "string", "example": "exr_abc_robotics_2026" },
          "buyer_id": { "type": "string", "example": "byr_delta_procurement_2026" },
          "match_score": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "example": 0.87, "description": "AI-computed buyer-exhibitor fit score. Higher score = stronger profile alignment. Does not predict commercial outcome." },
          "scheduled_at": { "type": "string", "format": "date-time", "example": "2026-10-16T10:30:00+08:00" },
          "duration_minutes": { "type": "integer", "example": 30 },
          "location": { "type": "string", "example": "Hall A, Meeting Table 12" },
          "status": { "type": "string", "enum": ["pending_confirmation", "confirmed", "cancelled", "completed", "no_show"], "example": "confirmed" },
          "confirmed_at": { "type": "string", "format": "date-time", "nullable": true },
          "confirmation_token": { "type": "string", "example": "conf_a1b2c3d4" },
          "created_by": { "type": "string", "enum": ["organizer", "exhibitor", "buyer", "agent"], "example": "agent" },
          "source_data": {
            "type": "object",
            "description": "Machine-readable proof of match basis",
            "properties": {
              "matched_categories": { "type": "array", "items": { "type": "string" } },
              "match_dimensions": { "type": "array", "items": { "type": "string" } }
            }
          }
        }
      },
      "MeetingOutcome": {
        "type": "object",
        "properties": {
          "meeting_id": { "type": "string" },
          "outcome": { "type": "string", "enum": ["productive", "not_a_fit", "follow_up_needed", "deal_intent", "no_show"], "example": "follow_up_needed" },
          "notes": { "type": "string", "example": "Buyer interested in automation line for Q4 project. Will send spec sheet." },
          "follow_up_action": { "type": "string", "example": "Send product catalog and pricing proposal within 3 business days." },
          "recorded_at": { "type": "string", "format": "date-time" },
          "recorded_by": { "type": "string", "enum": ["exhibitor", "buyer", "organizer", "agent"] }
        }
      },
      "ROIReport": {
        "type": "object",
        "properties": {
          "exhibition_id": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" },
          "report_type": { "type": "string", "enum": ["organizer", "exhibitor", "buyer"] },
          "summary": {
            "type": "object",
            "properties": {
              "total_meetings_scheduled": { "type": "integer" },
              "meetings_completed": { "type": "integer" },
              "no_show_rate": { "type": "number", "format": "float" },
              "match_acceptance_rate": { "type": "number", "format": "float" },
              "exhibitor_satisfaction_avg": { "type": "number", "format": "float" },
              "post_show_follow_up_rate": { "type": "number", "format": "float" }
            }
          },
          "disclaimer": { "type": "string", "example": "This report reflects structured event data and meeting outcomes as reported by participants. It does not guarantee commercial conversion, purchase orders, or revenue." }
        }
      },
      "MatchRecommendation": {
        "type": "object",
        "properties": {
          "exhibitor_id": { "type": "string" },
          "buyer_id": { "type": "string" },
          "match_score": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "example": 0.84 },
          "match_dimensions": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["product_category_overlap", "target_market_alignment", "buyer_procurement_intent", "geography_match"]
          },
          "recommended_meeting_duration": { "type": "integer", "example": 30 },
          "recommendation_basis": { "type": "string", "example": "Buyer stated procurement intent for industrial robots aligns with exhibitor's primary product line. Shared target markets: automotive and electronics manufacturing." },
          "disclaimer": { "type": "string", "example": "Match score reflects profile alignment only. It does not predict sales conversion or commercial outcome." }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "pay_9x7z3k" },
          "type": { "type": "string", "enum": ["meeting_package", "platform_fee", "exhibition_fee"], "example": "meeting_package" },
          "amount": { "type": "number", "format": "float", "example": 15000 },
          "currency": { "type": "string", "example": "TWD" },
          "status": { "type": "string", "enum": ["pending", "paid", "failed", "refunded"], "example": "paid" },
          "mode": { "type": "string", "enum": ["live", "test"], "example": "test" },
          "receipt_url": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "request_id": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/exhibitions/search": {
      "get": {
        "operationId": "search_exhibitions",
        "summary": "Search exhibitions",
        "description": "Search exhibitions by industry, location, date range, meeting format, and agent-operable status.",
        "security": [],
        "parameters": [
          { "name": "industry", "in": "query", "schema": { "type": "string" }, "example": "manufacturing_automation", "description": "Industry category" },
          { "name": "city", "in": "query", "schema": { "type": "string" }, "example": "台北" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "TW" },
          { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" },
          { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" },
          { "name": "agent_operable", "in": "query", "schema": { "type": "boolean" }, "description": "Filter to only exhibitions with agent-callable meeting scheduling" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["upcoming", "active", "post_event"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "List of matching exhibitions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Exhibition" } },
                    "total": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "offset": { "type": "integer" }
                  }
                }
              }
            }
          }
        },
        "tags": ["Exhibitions"]
      }
    },
    "/exhibitions/{exhibitionId}": {
      "get": {
        "operationId": "get_exhibition_profile",
        "summary": "Get exhibition profile",
        "security": [],
        "parameters": [
          { "name": "exhibitionId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Exhibition profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Exhibition" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "tags": ["Exhibitions"]
      }
    },
    "/exhibitions/{exhibitionId}/exhibitors": {
      "get": {
        "operationId": "get_exhibition_exhibitors",
        "summary": "List exhibitors at an exhibition",
        "security": [],
        "parameters": [
          { "name": "exhibitionId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "Exhibitor list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Exhibitor" } }, "total": { "type": "integer" } } } } } }
        },
        "tags": ["Exhibitions"]
      }
    },
    "/exhibitions/{exhibitionId}/buyers": {
      "get": {
        "operationId": "get_exhibition_buyers",
        "summary": "List registered buyers at an exhibition",
        "parameters": [
          { "name": "exhibitionId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "industry", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "Buyer list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Buyer" } }, "total": { "type": "integer" } } } } } }
        },
        "tags": ["Exhibitions"]
      }
    },
    "/exhibitions/{exhibitionId}/policies": {
      "get": {
        "operationId": "get_event_policy",
        "summary": "Get meeting and participation policies",
        "description": "Retrieve cancellation policy, meeting rules, data sharing terms, and agent operation permissions for this exhibition.",
        "security": [],
        "parameters": [
          { "name": "exhibitionId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Event policies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meeting_cancellation_hours": { "type": "integer", "example": 24 },
                    "reschedule_allowed": { "type": "boolean", "example": true },
                    "agent_scheduling_enabled": { "type": "boolean", "example": true },
                    "data_sharing": { "type": "string", "enum": ["full", "anonymized", "none"], "example": "anonymized" },
                    "max_meetings_per_exhibitor": { "type": "integer", "example": 20 },
                    "max_meetings_per_buyer": { "type": "integer", "example": 8 }
                  }
                }
              }
            }
          }
        },
        "tags": ["Exhibitions"]
      }
    },
    "/exhibitors/search": {
      "get": {
        "operationId": "search_exhibitors",
        "summary": "Search exhibitors",
        "description": "Search exhibitors by product category, service type, country, target buyer profile, verification status, and meeting availability.",
        "security": [],
        "parameters": [
          { "name": "exhibition_id", "in": "query", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "example": "industrial_robots" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "TW" },
          { "name": "target_industry", "in": "query", "schema": { "type": "string" } },
          { "name": "meeting_available", "in": "query", "schema": { "type": "boolean" } },
          { "name": "verification_status", "in": "query", "schema": { "type": "string", "enum": ["verified", "pending", "unverified"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "Exhibitor search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Exhibitor" } }, "total": { "type": "integer" } } } } } }
        },
        "tags": ["Exhibitors"]
      }
    },
    "/exhibitors/{exhibitorId}": {
      "get": {
        "operationId": "get_exhibitor_profile",
        "summary": "Get exhibitor profile",
        "security": [],
        "parameters": [
          { "name": "exhibitorId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Exhibitor profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Exhibitor" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "tags": ["Exhibitors"]
      }
    },
    "/exhibitors/{exhibitorId}/products": {
      "get": {
        "operationId": "get_product_categories",
        "summary": "Get exhibitor product and service catalog",
        "description": "Retrieve exhibitor-provided product and service descriptions. This is exhibitor-submitted data and does not represent verified specifications.",
        "security": [],
        "parameters": [
          { "name": "exhibitorId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Product catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exhibitor_id": { "type": "string" },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": { "type": "string" },
                          "name_en": { "type": "string" },
                          "category": { "type": "string" },
                          "description": { "type": "string" },
                          "target_industries": { "type": "array", "items": { "type": "string" } }
                        }
                      }
                    },
                    "last_updated": { "type": "string", "format": "date-time" },
                    "data_source": { "type": "string", "example": "exhibitor_provided" }
                  }
                }
              }
            }
          }
        },
        "tags": ["Exhibitors"]
      }
    },
    "/buyers/search": {
      "get": {
        "operationId": "search_buyers",
        "summary": "Search buyers",
        "description": "Search buyers by procurement intent, industry, budget range, geography, and meeting availability.",
        "parameters": [
          { "name": "exhibition_id", "in": "query", "schema": { "type": "string" } },
          { "name": "procurement_intent", "in": "query", "schema": { "type": "string" }, "example": "industrial_robots" },
          { "name": "industry", "in": "query", "schema": { "type": "string" } },
          { "name": "geography", "in": "query", "schema": { "type": "string" }, "example": "TW" },
          { "name": "meeting_slots_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "buyer_type", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "Buyer search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Buyer" } }, "total": { "type": "integer" } } } } } }
        },
        "tags": ["Buyers"]
      }
    },
    "/buyers/{buyerId}": {
      "get": {
        "operationId": "get_buyer_profile",
        "summary": "Get buyer profile",
        "parameters": [
          { "name": "buyerId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Buyer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Buyer" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "tags": ["Buyers"]
      }
    },
    "/meetings/availability": {
      "get": {
        "operationId": "get_meeting_availability",
        "summary": "Get available meeting slots",
        "description": "Retrieve open meeting time slots for a specific exhibitor or buyer at an exhibition.",
        "parameters": [
          { "name": "exhibition_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "exhibitor_id", "in": "query", "schema": { "type": "string" } },
          { "name": "buyer_id", "in": "query", "schema": { "type": "string" } },
          { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": {
            "description": "Available meeting slots",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exhibition_id": { "type": "string" },
                    "slots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slot_id": { "type": "string" },
                          "start": { "type": "string", "format": "date-time" },
                          "end": { "type": "string", "format": "date-time" },
                          "location": { "type": "string" },
                          "available": { "type": "boolean" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": ["Meetings"]
      }
    },
    "/meetings": {
      "post": {
        "operationId": "schedule_meeting",
        "summary": "Schedule a meeting",
        "description": "Schedule a B2B meeting between an exhibitor and buyer. Requires agent_scheduling_enabled=true on the exhibition. Both parties receive confirmation notifications.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["exhibition_id", "exhibitor_id", "buyer_id", "slot_id"],
                "properties": {
                  "exhibition_id": { "type": "string" },
                  "exhibitor_id": { "type": "string" },
                  "buyer_id": { "type": "string" },
                  "slot_id": { "type": "string" },
                  "created_by": { "type": "string", "default": "agent" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Meeting scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } },
          "409": { "description": "Slot no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "422": { "description": "Agent scheduling not enabled for this exhibition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "tags": ["Meetings"]
      }
    },
    "/meetings/{meetingId}": {
      "get": {
        "operationId": "get_meeting_status",
        "summary": "Get meeting status",
        "description": "Retrieve meeting details including confirmation status, timestamps, and machine-readable source data.",
        "parameters": [
          { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Meeting details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "tags": ["Meetings"]
      }
    },
    "/meetings/{meetingId}/cancel": {
      "patch": {
        "operationId": "cancel_meeting",
        "summary": "Cancel a meeting",
        "description": "Cancel a scheduled meeting. Cancellation must comply with the exhibition's cancellation policy.",
        "parameters": [
          { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": { "type": "string" },
                  "cancelled_by": { "type": "string", "enum": ["exhibitor", "buyer", "organizer", "agent"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Meeting cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } },
          "422": { "description": "Cannot cancel — within policy lock window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "tags": ["Meetings"]
      }
    },
    "/meetings/{meetingId}/reschedule": {
      "patch": {
        "operationId": "reschedule_meeting",
        "summary": "Reschedule a meeting",
        "parameters": [
          { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["new_slot_id"],
                "properties": {
                  "new_slot_id": { "type": "string" },
                  "reason": { "type": "string" },
                  "rescheduled_by": { "type": "string", "enum": ["exhibitor", "buyer", "organizer", "agent"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Meeting rescheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } }
        },
        "tags": ["Meetings"]
      }
    },
    "/meetings/{meetingId}/outcome": {
      "post": {
        "operationId": "record_meeting_outcome",
        "summary": "Record meeting outcome",
        "parameters": [
          { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MeetingOutcome" }
            }
          }
        },
        "responses": {
          "201": { "description": "Outcome recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingOutcome" } } } }
        },
        "tags": ["Meetings"]
      }
    },
    "/meetings/{meetingId}/followup-tasks": {
      "get": {
        "operationId": "generate_follow_up_tasks",
        "summary": "Get AI-generated follow-up tasks for a completed meeting",
        "parameters": [
          { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Follow-up task list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meeting_id": { "type": "string" },
                    "tasks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "task_id": { "type": "string" },
                          "assigned_to": { "type": "string", "enum": ["exhibitor", "buyer"] },
                          "action": { "type": "string", "example": "Send product catalog and pricing proposal" },
                          "due_date": { "type": "string", "format": "date" },
                          "priority": { "type": "string", "enum": ["high", "medium", "low"] }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": ["Meetings"]
      }
    },
    "/matches/recommend": {
      "get": {
        "operationId": "recommend_exhibitor_buyer_matches",
        "summary": "Recommend exhibitor-buyer matches",
        "description": "Get AI-computed match recommendations between exhibitors and buyers. Match score is based on product category overlap, procurement intent, target market alignment, and geography. It does not predict commercial outcome.",
        "parameters": [
          { "name": "exhibition_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "exhibitor_id", "in": "query", "schema": { "type": "string" }, "description": "Get buyers recommended for this exhibitor" },
          { "name": "buyer_id", "in": "query", "schema": { "type": "string" }, "description": "Get exhibitors recommended for this buyer" },
          { "name": "min_score", "in": "query", "schema": { "type": "number", "default": 0.6 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }
        ],
        "responses": {
          "200": {
            "description": "Match recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/MatchRecommendation" } },
                    "disclaimer": { "type": "string", "example": "Match scores reflect profile alignment only and do not predict commercial outcome or buyer intent to purchase." }
                  }
                }
              }
            }
          }
        },
        "tags": ["Matching"]
      }
    },
    "/roi-reports/{exhibitionId}": {
      "get": {
        "operationId": "generate_roi_report",
        "summary": "Get post-event ROI report",
        "description": "Retrieve structured ROI metrics for an exhibition. Reports are available within 24 hours post-event. Includes meeting completion rates, satisfaction scores, and follow-up rates. Does not include sales revenue or commercial conversion data.",
        "parameters": [
          { "name": "exhibitionId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "report_type", "in": "query", "schema": { "type": "string", "enum": ["organizer", "exhibitor", "buyer"], "default": "organizer" } },
          { "name": "exhibitor_id", "in": "query", "schema": { "type": "string" }, "description": "Required when report_type=exhibitor" }
        ],
        "responses": {
          "200": { "description": "ROI report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ROIReport" } } } },
          "425": { "description": "Report not yet available — event still in progress or within post-event processing window" }
        },
        "tags": ["ROI Reports"]
      }
    },
    "/payments": {
      "post": {
        "operationId": "create_payment",
        "summary": "Create a payment (meeting package or platform fee)",
        "description": "Payment abstraction layer. Currently operates in test mode. Live Stripe integration available upon request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "exhibition_id", "payer_id"],
                "properties": {
                  "type": { "type": "string", "enum": ["meeting_package", "platform_fee", "exhibition_fee"] },
                  "exhibition_id": { "type": "string" },
                  "payer_id": { "type": "string" },
                  "amount": { "type": "number" },
                  "currency": { "type": "string", "default": "TWD" },
                  "mode": { "type": "string", "enum": ["live", "test"], "default": "test" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Payment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }
        },
        "tags": ["Payments"]
      }
    },
    "/payments/{paymentId}/receipt": {
      "get": {
        "operationId": "get_receipt",
        "summary": "Get payment receipt",
        "parameters": [
          { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Payment receipt",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          }
        },
        "tags": ["Payments"]
      }
    },
    "/verification/{entityType}/{entityId}": {
      "get": {
        "operationId": "get_verification_status",
        "summary": "Get entity verification status",
        "description": "Check verification status of an exhibitor, buyer, or exhibition.",
        "security": [],
        "parameters": [
          { "name": "entityType", "in": "path", "required": true, "schema": { "type": "string", "enum": ["exhibitor", "buyer", "exhibition"] } },
          { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Verification status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entity_type": { "type": "string" },
                    "entity_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["verified", "pending", "unverified"] },
                    "verified_at": { "type": "string", "format": "date-time", "nullable": true },
                    "verification_method": { "type": "string", "example": "organizer_manual_review" }
                  }
                }
              }
            }
          }
        },
        "tags": ["Verification"]
      }
    }
  },
  "tags": [
    { "name": "Exhibitions", "description": "Search and retrieve exhibition information" },
    { "name": "Exhibitors", "description": "Search exhibitor profiles and product catalogs" },
    { "name": "Buyers", "description": "Search buyer profiles and procurement intent" },
    { "name": "Meetings", "description": "Schedule, manage, and track B2B meetings" },
    { "name": "Matching", "description": "AI-computed exhibitor-buyer match recommendations" },
    { "name": "ROI Reports", "description": "Post-event ROI metrics and outcome reports" },
    { "name": "Payments", "description": "Payment abstraction layer (test mode available)" },
    { "name": "Verification", "description": "Entity verification status" }
  ]
}