{
  "openapi": "3.0.3",
  "info": {
    "title": "即合智能C1视觉盒子 对外接口",
    "version": "2.0.0",
    "description": "第一期客户集成接口。事件视频暂不提供。"
  },
  "servers": [{"url": "/api/integration/v2"}],
  "security": [{"ApiKey": []}],
  "paths": {
    "/device": {
      "get": {
        "summary": "读取盒子状态",
        "operationId": "getDevice",
        "responses": {"200": {"description": "设备状态"}}
      }
    },
    "/cameras": {
      "get": {
        "summary": "读取摄像头状态",
        "operationId": "listCameras",
        "responses": {"200": {"description": "摄像头列表"}}
      }
    },
    "/capabilities": {
      "get": {
        "summary": "读取开放能力",
        "operationId": "getCapabilities",
        "responses": {"200": {"description": "算法、事件及媒体能力"}}
      }
    },
    "/alarms": {
      "get": {
        "summary": "游标补查告警",
        "operationId": "listAlarms",
        "parameters": [
          {"name": "cursor", "in": "query", "description": "从新到旧继续翻页的 next_cursor；不是新增数据水位", "schema": {"type": "string"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}
        ],
        "responses": {"200": {"description": "告警列表及 next_cursor"}, "400": {"$ref": "#/components/responses/Error"}}
      }
    },
    "/alarms/{event_id}": {
      "get": {
        "summary": "读取告警详情",
        "operationId": "getAlarm",
        "parameters": [{"$ref": "#/components/parameters/EventId"}],
        "responses": {"200": {"description": "告警详情"}, "404": {"$ref": "#/components/responses/Error"}}
      }
    },
    "/alarms/{event_id}/snapshot": {
      "get": {
        "summary": "读取告警截图",
        "description": "variant=annotated 返回带框图，variant=original 返回原图。可使用 API Key，alarm.media.ready 临时 URL 也可使用15分钟 media_token。",
        "operationId": "getAlarmSnapshot",
        "parameters": [
          {"$ref": "#/components/parameters/EventId"},
          {"name": "variant", "in": "query", "schema": {"type": "string", "enum": ["annotated", "original"], "default": "annotated"}},
          {"name": "media_token", "in": "query", "schema": {"type": "string"}}
        ],
        "security": [{"ApiKey": []}, {"MediaToken": []}],
        "responses": {"200": {"description": "JPEG", "content": {"image/jpeg": {"schema": {"type": "string", "format": "binary"}}}}, "404": {"$ref": "#/components/responses/Error"}}
      }
    },
    "/alarms/{event_id}/ack": {
      "post": {
        "summary": "确认告警",
        "operationId": "ackAlarm",
        "parameters": [{"$ref": "#/components/parameters/EventId"}],
        "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "maxLength": 500}}}}}},
        "responses": {"200": {"description": "确认成功"}, "404": {"$ref": "#/components/responses/Error"}}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {"type": "http", "scheme": "bearer", "bearerFormat": "c1_live_..."},
      "MediaToken": {"type": "apiKey", "in": "query", "name": "media_token", "description": "alarm.media.ready 提供的15分钟临时截图令牌"}
    },
    "parameters": {
      "EventId": {"name": "event_id", "in": "path", "required": true, "schema": {"type": "string"}}
    },
    "responses": {
      "Error": {
        "description": "错误",
        "content": {"application/json": {"schema": {"type": "object", "properties": {"api_version": {"type": "string"}, "request_id": {"type": "string"}, "error": {"type": "object"}}}}}
      }
    }
  },
  "x-c1-webhook": {
    "events": ["alarm.opened", "alarm.active", "alarm.recovered", "alarm.media.ready"],
    "success": "HTTP 2xx",
    "idempotency": "delivery_id",
    "signature": "HMAC-SHA256(timestamp + newline + nonce + newline + POST + newline + path + newline + sha256(body))"
  },
  "x-c1-mqtt": {
    "protocol": "MQTT 3.1.1",
    "qos": 1,
    "topic": "{topic_prefix}/{device_id}/alarms",
    "tls": "recommended and enabled by default"
  },
  "x-c1-modbus": {
    "role": "read-only server",
    "function_codes": ["0x03", "0x04"],
    "registers": {"0": "protocol 0x0200", "1-2": "UTC seconds, low word first", "3": "device online", "10": "unacknowledged alarm flag", "11": "unacknowledged alarm count", "20": "enabled cameras", "21": "online cameras"}
  }
}