{
  "openapi": "3.1.0",
  "info": {
    "title": "IMSG public agent information",
    "version": "1.0.0",
    "description": "Read-only service, fee and meeting-request information. No calendar or request-submission operation. Clients need their own supported HTTP tools; publishing this specification does not install tools in any assistant."
  },
  "servers": [
    {
      "url": "https://www.imsg.com.hk"
    }
  ],
  "paths": {
    "/agents/services.json": {
      "get": {
        "operationId": "getIMSGServices",
        "summary": "Read IMSG services and public contact routes",
        "description": "Descriptions and scope match the published service pages. Stable service IDs map to the existing form topics.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public read-only information; no request submitted or appointment reserved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Services"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable."
          },
          "503": {
            "description": "Current request policy cannot be applied safely; no fallback dated windows are supplied."
          }
        }
      }
    },
    "/agents/fees.json": {
      "get": {
        "operationId": "getIMSGFeeSchedule",
        "summary": "Read current published IMSG fee schedule",
        "description": "Preserve price modes and conditions. Quote-required amounts are null, not zero. A written quote confirms scope and actual fees.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public read-only information; no request submitted or appointment reserved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Fees"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable."
          },
          "503": {
            "description": "Current request policy cannot be applied safely; no fallback dated windows are supplied."
          }
        }
      }
    },
    "/agents/meeting-policy.json": {
      "get": {
        "operationId": "getIMSGMeetingRequestPolicy",
        "summary": "Read staff-confirmed meeting-request policy",
        "description": "Preparing or submitting a request does not reserve a meeting. Appointments require IMSG confirmation.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public read-only information; no request submitted or appointment reserved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeetingPolicy"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable."
          },
          "503": {
            "description": "Current request policy cannot be applied safely; no fallback dated windows are supplied."
          }
        }
      }
    },
    "/agents/request-windows": {
      "get": {
        "operationId": "getIMSGRequestWindows",
        "summary": "Read fresh preferred HKT request windows",
        "description": "Windows are choices for expressing preferences, not free/busy calendar inventory or meeting duration. Fresh responses have generated_at and expires_at; refetch after expiry. Read policy and review the existing form before submitting.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public read-only information; no request submitted or appointment reserved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestWindows"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable."
          },
          "503": {
            "description": "Current request policy cannot be applied safely; no fallback dated windows are supplied."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LocalizedText": {
        "type": "object",
        "required": [
          "en",
          "zh-Hant",
          "zh-Hans"
        ],
        "properties": {
          "en": {
            "type": "string"
          },
          "zh-Hant": {
            "type": "string"
          },
          "zh-Hans": {
            "type": "string"
          }
        }
      },
      "LocalizedList": {
        "type": "object",
        "required": [
          "en",
          "zh-Hant",
          "zh-Hans"
        ],
        "properties": {
          "en": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "zh-Hant": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "zh-Hans": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Service": {
        "type": "object",
        "required": [
          "id",
          "booking_service_id",
          "name",
          "description",
          "canonical_urls",
          "fee_ids",
          "includes",
          "excludes",
          "conditions"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "booking_service_id": {
            "type": "string",
            "enum": [
              "incorporation",
              "comsec",
              "accounting",
              "tax",
              "cfo",
              "offshore",
              "not-sure"
            ]
          },
          "name": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "canonical_urls": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "fee_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "includes": {
            "$ref": "#/components/schemas/LocalizedList"
          },
          "excludes": {
            "$ref": "#/components/schemas/LocalizedList"
          },
          "conditions": {
            "$ref": "#/components/schemas/LocalizedList"
          }
        }
      },
      "Price": {
        "type": "object",
        "required": [
          "id",
          "service_id",
          "name",
          "mode",
          "amount",
          "currency",
          "unit",
          "charged_by",
          "includes_government_fees",
          "components",
          "limits",
          "conditions"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "service_id": {
            "type": "string"
          },
          "name": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "mode": {
            "type": "string",
            "enum": [
              "fixed",
              "from",
              "quote_required"
            ]
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "currency": {
            "type": "string",
            "const": "HKD"
          },
          "unit": {
            "type": "string",
            "enum": [
              "per_incorporation",
              "per_year",
              "per_return",
              "per_hour",
              "per_call",
              "per_engagement",
              "per_renewal",
              "per_filing"
            ]
          },
          "charged_by": {
            "type": "string",
            "enum": [
              "IMSG",
              "government",
              "independent_cpa",
              "mixed"
            ]
          },
          "includes_government_fees": {
            "type": "boolean"
          },
          "components": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "amount",
                "charged_by",
                "pass_through_at_cost"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "amount": {
                  "type": "number",
                  "minimum": 0
                },
                "charged_by": {
                  "type": "string",
                  "enum": [
                    "IMSG",
                    "government",
                    "independent_cpa"
                  ]
                },
                "pass_through_at_cost": {
                  "type": "boolean"
                }
              }
            }
          },
          "limits": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "conditions": {
            "$ref": "#/components/schemas/LocalizedList"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "mode": {
                  "const": "quote_required"
                }
              },
              "required": [
                "mode"
              ]
            },
            "then": {
              "properties": {
                "amount": {
                  "type": "null"
                }
              }
            },
            "else": {
              "properties": {
                "amount": {
                  "type": "number",
                  "minimum": 0
                }
              }
            }
          }
        ]
      },
      "Services": {
        "type": "object",
        "required": [
          "schema_version",
          "services"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "catalog_revision": {
            "type": "string",
            "format": "date"
          },
          "schedule_revision": {
            "type": "string",
            "format": "date"
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Service"
            }
          }
        }
      },
      "Fees": {
        "type": "object",
        "required": [
          "schema_version",
          "currency",
          "prices"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "catalog_revision": {
            "type": "string",
            "format": "date"
          },
          "schedule_revision": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string",
            "const": "HKD"
          },
          "prices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Price"
            }
          }
        }
      },
      "MeetingPolicy": {
        "type": "object",
        "required": [
          "schema_version",
          "inventory_type",
          "appointment_confirmed",
          "staff_confirmation_required",
          "lanes",
          "constraints",
          "fresh_request_windows_url"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "catalog_revision": {
            "type": "string",
            "format": "date"
          },
          "schedule_revision": {
            "type": "string",
            "format": "date"
          },
          "inventory_type": {
            "const": "preferences"
          },
          "appointment_confirmed": {
            "const": false
          },
          "staff_confirmation_required": {
            "const": true
          },
          "lanes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "fee_id",
                "requires_time_preferences"
              ],
              "properties": {
                "id": {
                  "enum": [
                    "free",
                    "consultation",
                    "written"
                  ]
                },
                "fee_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "requires_time_preferences": {
                  "type": "boolean"
                }
              }
            }
          },
          "constraints": {
            "type": "object",
            "required": [
              "timezone",
              "max_preferences",
              "min_complete_business_days_notice"
            ],
            "properties": {
              "timezone": {
                "const": "Asia/Hong_Kong"
              },
              "max_preferences": {
                "const": 3
              },
              "min_complete_business_days_notice": {
                "const": 2
              }
            }
          },
          "fresh_request_windows_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "RequestWindows": {
        "type": "object",
        "required": [
          "schema_version",
          "policy_revision",
          "generated_at",
          "expires_at",
          "time_zone",
          "inventory_type",
          "appointment_confirmed",
          "lead_time_business_days",
          "maximum_preferences",
          "holiday_calendar_valid_through",
          "windows"
        ],
        "properties": {
          "schema_version": {
            "const": "1.0.0"
          },
          "policy_revision": {
            "type": "string",
            "format": "date"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "time_zone": {
            "const": "Asia/Hong_Kong"
          },
          "inventory_type": {
            "const": "preferences"
          },
          "appointment_confirmed": {
            "const": false
          },
          "lead_time_business_days": {
            "const": 2
          },
          "maximum_preferences": {
            "const": 3
          },
          "holiday_calendar_valid_through": {
            "type": "string",
            "format": "date"
          },
          "windows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "date",
                "start",
                "end",
                "day_index",
                "block_index"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                },
                "day_index": {
                  "type": "integer",
                  "minimum": 0
                },
                "block_index": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 3
                }
              }
            }
          }
        }
      }
    }
  }
}