{ "openapi": "3.1.0", "info": { "title": "Home Pulse App API", "version": "1.2.0", "description": "App SDK 负责设备连接和执行;本 API 负责任务、模型、状态与闭环。会话为共享空间凭据;生产账户登录和成员角色另行接入。所有时间为 UTC ISO 8601,界面按家庭时区显示。" }, "servers": [ { "url": "https://loveaa-onealign.hf.space" }, { "url": "http://127.0.0.1:7101" } ], "components": { "schemas": { "Draft": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "maxLength": 60 }, "taskKind": { "type": "string", "enum": [ "dog_boundary", "keys_check", "general" ] }, "targetName": { "type": "string", "maxLength": 80 }, "targetDescriptionEn": { "type": "string", "minLength": 3, "maxLength": 600 }, "regionName": { "type": "string", "minLength": 1, "maxLength": 80 }, "regionDescriptionEn": { "type": "string", "minLength": 3, "maxLength": 500 }, "targetBox": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0.02, "maximum": 1 }, "h": { "type": "number", "minimum": 0.02, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, { "type": "null" } ] }, "regionBox": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0.02, "maximum": 1 }, "h": { "type": "number", "minimum": 0.02, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, { "type": "null" } ] }, "summary": { "type": "string", "maxLength": 500 }, "questions": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 30 }, "question": { "type": "string", "maxLength": 180 }, "options": { "maxItems": 4, "type": "array", "items": { "type": "string", "maxLength": 120 } } }, "required": [ "id", "question", "options" ], "additionalProperties": false } }, "viewAdvice": { "type": "string", "maxLength": 250 }, "recommendation": { "type": "object", "properties": { "capturePolicy": { "type": "object", "properties": { "mode": { "default": "event", "type": "string", "enum": [ "event", "scheduled", "manual" ] }, "intervalSeconds": { "default": 300, "type": "integer", "minimum": 60, "maximum": 86400 }, "comparisonMaxAgeSeconds": { "default": 86400, "type": "integer", "minimum": 60, "maximum": 172800 } }, "required": [ "mode", "intervalSeconds", "comparisonMaxAgeSeconds" ], "additionalProperties": false }, "category": { "type": "string", "enum": [ "security", "care", "memory", "routine" ] }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "reasonZh": { "type": "string", "minLength": 1, "maxLength": 400 }, "locationAlerts": { "type": "object", "properties": { "notSeen": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "outside": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "excludeCarried": { "default": true, "type": "boolean" } }, "required": [ "notSeen", "outside", "excludeCarried" ], "additionalProperties": false } }, "required": [ "capturePolicy", "category", "attentionLevel", "reasonZh" ], "additionalProperties": false } }, "required": [ "title", "taskKind", "targetName", "targetDescriptionEn", "regionName", "regionDescriptionEn", "targetBox", "regionBox", "summary", "questions", "viewAdvice" ], "additionalProperties": false }, "DraftResponse": { "type": "object", "required": [ "draft", "latencyMs" ], "properties": { "draft": { "$ref": "#/components/schemas/Draft" }, "latencyMs": { "type": "number" }, "model": { "type": "string" } } }, "Recommendation": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capturePolicy": { "type": "object", "properties": { "mode": { "default": "event", "type": "string", "enum": [ "event", "scheduled", "manual" ] }, "intervalSeconds": { "default": 300, "type": "integer", "minimum": 60, "maximum": 86400 }, "comparisonMaxAgeSeconds": { "default": 86400, "type": "integer", "minimum": 60, "maximum": 172800 } }, "required": [ "mode", "intervalSeconds", "comparisonMaxAgeSeconds" ], "additionalProperties": false }, "category": { "type": "string", "enum": [ "security", "care", "memory", "routine" ] }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "reasonZh": { "type": "string", "minLength": 1, "maxLength": 400 }, "locationAlerts": { "type": "object", "properties": { "notSeen": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "outside": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "excludeCarried": { "default": true, "type": "boolean" } }, "required": [ "notSeen", "outside", "excludeCarried" ], "additionalProperties": false } }, "required": [ "capturePolicy", "category", "attentionLevel", "reasonZh" ], "additionalProperties": false }, "Client": { "type": "object", "required": [ "id", "platform", "lastSeen", "sdkReady" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "enum": [ "ios", "android", "web", "test" ] }, "lastSeen": { "type": [ "string", "null" ], "format": "date-time" }, "foreground": { "type": "boolean" }, "sdkReady": { "type": "boolean" } } }, "Device": { "type": "object", "required": [ "id", "clientId", "name", "model", "capabilities", "online", "viewRevision" ], "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "model": { "type": "string" }, "online": { "type": "boolean" }, "viewRevision": { "type": "integer", "minimum": 1 }, "lastSeen": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "type": "object", "additionalProperties": true }, "capabilities": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "live": { "type": "boolean" }, "frames": { "type": "boolean" }, "events": { "type": "boolean" }, "scheduledCapture": { "default": false, "type": "boolean" }, "actions": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "night_vision.set", "ptz.preset.goto", "alarm.set", "light.set", "motion_detection.set" ] } }, "nightVisionModes": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "key", "label" ], "additionalProperties": false } }, "presetIndices": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 255 } }, "detectionTypes": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "alarmTypes": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "SOUND_ONLY", "LIGHT_ONLY", "SOUND_AND_LIGHT" ] } } }, "required": [ "live", "frames", "events", "scheduledCapture", "actions", "nightVisionModes", "presetIndices", "detectionTypes", "alarmTypes" ], "additionalProperties": false } } }, "Setup": { "type": "object", "required": [ "id", "plan", "binding", "deviceId", "viewRevision" ], "properties": { "id": { "type": "string" }, "request": { "type": "string" }, "plan": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "status": { "type": "string", "enum": [ "ready", "needs_clarification", "unsupported" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "summary_zh": { "type": "string", "maxLength": 800 }, "clarification_questions": { "maxItems": 4, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "assumptions": { "maxItems": 6, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "observers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "question_en": { "type": "string", "minLength": 10, "maxLength": 1400 }, "input": { "type": "string", "enum": [ "single", "pair", "reference" ] }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 400 } }, "labels_zh": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": [ "id", "title", "question_en", "input", "options", "labels_zh" ], "additionalProperties": false } }, "rules": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "now", "occurrence", "change", "duration", "window_summary", "sequence" ] }, "condition": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "all", "any" ] }, "terms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "observer": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "required": [ "observer", "values" ], "additionalProperties": false } } }, "required": [ "operator", "terms" ], "additionalProperties": false }, "then": { "anyOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "all", "any" ] }, "terms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "observer": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "required": [ "observer", "values" ], "additionalProperties": false } } }, "required": [ "operator", "terms" ], "additionalProperties": false }, { "type": "null" } ] }, "recovery": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "all", "any" ] }, "terms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "observer": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "required": [ "observer", "values" ], "additionalProperties": false } } }, "required": [ "operator", "terms" ], "additionalProperties": false }, "duration_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "within_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "time_window": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ], "additionalProperties": false }, { "type": "null" } ] }, "exclude_window": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ], "additionalProperties": false }, { "type": "null" } ] }, "requires": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "away", "rain", "doorbell" ] } }, "notify": { "type": "string", "enum": [ "realtime", "summary", "silent" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 3 }, "confirmation_frames": { "type": "integer", "minimum": 1, "maximum": 3 }, "cooldown_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } }, "required": [ "id", "title", "mode", "condition", "then", "duration_seconds", "within_seconds", "time_window", "exclude_window", "requires", "notify", "level", "confirmation_frames", "cooldown_seconds" ], "additionalProperties": false } } }, "required": [ "version", "status", "title", "summary_zh", "clarification_questions", "assumptions", "observers", "rules" ], "additionalProperties": false }, "binding": { "type": "object", "additionalProperties": true }, "capturePolicy": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mode": { "default": "event", "type": "string", "enum": [ "event", "scheduled", "manual" ] }, "intervalSeconds": { "default": 300, "type": "integer", "minimum": 60, "maximum": 86400 }, "comparisonMaxAgeSeconds": { "default": 86400, "type": "integer", "minimum": 60, "maximum": 172800 } }, "required": [ "mode", "intervalSeconds", "comparisonMaxAgeSeconds" ], "additionalProperties": false }, "locationAlerts": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "notSeen": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "outside": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "excludeCarried": { "default": true, "type": "boolean" } }, "required": [ "notSeen", "outside", "excludeCarried" ], "additionalProperties": false }, "recommendationReason": { "type": "string" }, "deviceId": { "type": "string" }, "viewRevision": { "type": "integer" }, "trial": { "$ref": "#/components/schemas/Trial" } } }, "Trial": { "type": "object", "required": [ "passed", "checks", "at", "latencyMs" ], "properties": { "passed": { "type": "boolean" }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "latencyMs": { "type": "number" }, "checks": { "type": "array", "items": { "type": "object", "required": [ "label", "passed" ], "properties": { "label": { "type": "string" }, "passed": { "type": "boolean" }, "usable": { "type": "integer" }, "needed": { "type": "integer" } } } } } }, "Watch": { "type": "object", "required": [ "id", "deviceId", "title", "plan", "binding", "state", "observationStatus", "sourceOnline", "attentionLevel" ], "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "title": { "type": "string" }, "request": { "type": "string" }, "plan": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "status": { "type": "string", "enum": [ "ready", "needs_clarification", "unsupported" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "summary_zh": { "type": "string", "maxLength": 800 }, "clarification_questions": { "maxItems": 4, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "assumptions": { "maxItems": 6, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "observers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "question_en": { "type": "string", "minLength": 10, "maxLength": 1400 }, "input": { "type": "string", "enum": [ "single", "pair", "reference" ] }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 400 } }, "labels_zh": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": [ "id", "title", "question_en", "input", "options", "labels_zh" ], "additionalProperties": false } }, "rules": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "now", "occurrence", "change", "duration", "window_summary", "sequence" ] }, "condition": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "all", "any" ] }, "terms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "observer": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "required": [ "observer", "values" ], "additionalProperties": false } } }, "required": [ "operator", "terms" ], "additionalProperties": false }, "then": { "anyOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "all", "any" ] }, "terms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "observer": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "required": [ "observer", "values" ], "additionalProperties": false } } }, "required": [ "operator", "terms" ], "additionalProperties": false }, { "type": "null" } ] }, "recovery": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "all", "any" ] }, "terms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "observer": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "required": [ "observer", "values" ], "additionalProperties": false } } }, "required": [ "operator", "terms" ], "additionalProperties": false }, "duration_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "within_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "time_window": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ], "additionalProperties": false }, { "type": "null" } ] }, "exclude_window": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ], "additionalProperties": false }, { "type": "null" } ] }, "requires": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "away", "rain", "doorbell" ] } }, "notify": { "type": "string", "enum": [ "realtime", "summary", "silent" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 3 }, "confirmation_frames": { "type": "integer", "minimum": 1, "maximum": 3 }, "cooldown_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } }, "required": [ "id", "title", "mode", "condition", "then", "duration_seconds", "within_seconds", "time_window", "exclude_window", "requires", "notify", "level", "confirmation_frames", "cooldown_seconds" ], "additionalProperties": false } } }, "required": [ "version", "status", "title", "summary_zh", "clarification_questions", "assumptions", "observers", "rules" ], "additionalProperties": false }, "binding": { "type": "object", "additionalProperties": true }, "state": { "enum": [ "active", "paused", "replaced" ] }, "observationStatus": { "enum": [ "recently_checked", "waiting_event", "ready_for_check", "waiting_schedule", "awaiting_evidence", "needs_reconfirmation", "connection_interrupted", "paused", "replaced" ] }, "sourceOnline": { "type": "boolean" }, "needsReconfirmation": { "type": "boolean" }, "viewRevision": { "type": "integer" }, "currentViewRevision": { "type": "integer" }, "lastConfirmedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastObservedAt": { "type": [ "string", "null" ], "format": "date-time" }, "capturePolicy": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mode": { "default": "event", "type": "string", "enum": [ "event", "scheduled", "manual" ] }, "intervalSeconds": { "default": 300, "type": "integer", "minimum": 60, "maximum": 86400 }, "comparisonMaxAgeSeconds": { "default": 86400, "type": "integer", "minimum": 60, "maximum": 172800 } }, "required": [ "mode", "intervalSeconds", "comparisonMaxAgeSeconds" ], "additionalProperties": false }, "locationAlerts": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "notSeen": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "outside": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "excludeCarried": { "default": true, "type": "boolean" } }, "required": [ "notSeen", "outside", "excludeCarried" ], "additionalProperties": false }, "lastResult": { "type": [ "string", "null" ] }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "category": { "enum": [ "security", "care", "memory", "routine" ] }, "memoryId": { "type": [ "string", "null" ] }, "observations": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Event": { "type": "object", "required": [ "id", "watchId", "ruleId", "title", "handlingState", "attentionLevel", "revision" ], "properties": { "id": { "type": "string" }, "watchId": { "type": "string" }, "ruleId": { "type": "string" }, "title": { "type": "string" }, "handlingState": { "enum": [ "unread", "read", "handling", "user_completed", "dismissed" ] }, "category": { "enum": [ "security", "care", "memory", "routine" ] }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "revision": { "type": "integer" }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "visualRecoveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "userCompletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Command": { "type": "object", "required": [ "id", "deviceId", "action", "params", "status", "revision", "expiresAt" ], "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "watchId": { "type": "string" }, "eventId": { "type": "string" }, "action": { "enum": [ "night_vision.set", "ptz.preset.goto", "alarm.set", "light.set", "motion_detection.set" ] }, "params": { "type": "object", "additionalProperties": true }, "status": { "enum": [ "awaiting_confirmation", "queued", "executing", "awaiting_verification", "verified", "verification_failed", "result_unknown", "failed", "cancelled", "expired" ] }, "revision": { "type": "integer" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "executionDeadline": { "type": [ "string", "null" ], "format": "date-time" }, "executionToken": { "type": "string", "description": "仅 claim 响应返回;保存到安全存储,禁止展示与日志记录" }, "receipt": { "type": "object", "additionalProperties": true }, "verification": { "type": "object", "additionalProperties": true } } }, "Observation": { "type": "object", "required": [ "notices", "details", "latencyMs", "engineMs", "outcome" ], "properties": { "answers": { "type": "object", "additionalProperties": true }, "trace": { "type": "object", "additionalProperties": true }, "notices": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "text": { "type": "string" }, "latencyMs": { "type": "number" }, "engineMs": { "type": "number" }, "unknown": { "type": "boolean" }, "pending": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "outcome": { "enum": [ "quiet", "unknown", "attention" ] }, "at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Memory": { "type": "object", "required": [ "id", "targetName", "regionName", "source" ], "properties": { "id": { "type": "string" }, "targetName": { "type": "string" }, "regionName": { "type": "string" }, "source": { "type": "object", "additionalProperties": true }, "targetBox": { "type": "object", "additionalProperties": true }, "regionBox": { "type": "object", "additionalProperties": true }, "targetCrop": { "type": "string" }, "referenceImage": { "type": "string" }, "thumbnail": { "type": "string" }, "active": { "type": "boolean" }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "securitySchemes": { "WorkspaceBearer": { "type": "http", "scheme": "bearer", "description": "Home Pulse 空间令牌;不要使用 HF、Kimi 或 eufy 密钥" } } }, "paths": { "/api/v1/bootstrap": { "get": { "summary": "读取空间和服务能力", "operationId": "get_bootstrap", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/clients": { "post": { "summary": "登记 App 安装实例", "operationId": "post_clients", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Client" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "platform": { "type": "string", "enum": [ "ios", "android", "web", "test" ] }, "appVersion": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name", "platform", "appVersion" ], "additionalProperties": false } } } } } }, "/api/v1/clients/{id}/heartbeat": { "post": { "summary": "更新接入端心跳", "operationId": "post_clients_id_heartbeat", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Client" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "foreground": { "type": "boolean" }, "sdkReady": { "type": "boolean" } }, "required": [ "foreground", "sdkReady" ], "additionalProperties": false } } } } } }, "/api/v1/devices": { "get": { "summary": "查询设备及连接状态", "operationId": "get_devices", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } }, "post": { "summary": "登记设备与实际 SDK 能力", "operationId": "post_devices", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Device" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "capabilities": { "type": "object", "properties": { "live": { "type": "boolean" }, "frames": { "type": "boolean" }, "events": { "type": "boolean" }, "scheduledCapture": { "default": false, "type": "boolean" }, "actions": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "night_vision.set", "ptz.preset.goto", "alarm.set", "light.set", "motion_detection.set" ] } }, "nightVisionModes": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "key", "label" ], "additionalProperties": false } }, "presetIndices": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 255 } }, "detectionTypes": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "alarmTypes": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "SOUND_ONLY", "LIGHT_ONLY", "SOUND_AND_LIGHT" ] } } }, "required": [ "live", "frames", "events", "scheduledCapture", "actions", "nightVisionModes", "presetIndices", "detectionTypes", "alarmTypes" ], "additionalProperties": false } }, "required": [ "deviceId", "clientId", "name", "model", "capabilities" ], "additionalProperties": false } } } } } }, "/api/v1/devices/{id}/status": { "post": { "summary": "上报设备状态和视野变化", "operationId": "post_devices_id_status", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Device" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "online": { "type": "boolean" }, "observedAt": { "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))$" }, "viewChanged": { "default": false, "type": "boolean" }, "state": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string", "maxLength": 120 } } ] } } }, "required": [ "clientId", "online", "observedAt", "viewChanged", "state" ], "additionalProperties": false } } } } } }, "/api/v1/device-events": { "post": { "summary": "上传硬件事件并获取取证建议", "operationId": "post_device_events", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "type": { "type": "string", "enum": [ "motion", "person", "pet", "vehicle", "doorbell", "other" ] }, "occurredAt": { "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))$" }, "summary": { "default": "", "type": "string", "maxLength": 300 } }, "required": [ "clientId", "deviceId", "eventId", "type", "occurredAt", "summary" ], "additionalProperties": false } } } } } }, "/api/v1/setups/draft": { "post": { "summary": "理解需求,提出对象、澄清问题及观察提醒建议", "operationId": "post_setups_draft", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/DraftResponse" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "request": { "type": "string", "minLength": 2, "maxLength": 3000 }, "image": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "camera": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "video", "image", "live" ] } }, "required": [ "id", "name", "camera", "url", "type" ], "additionalProperties": false }, "memoryId": { "type": "string" }, "observationContext": { "type": "object", "properties": { "events": { "type": "boolean" }, "scheduledCapture": { "type": "boolean" }, "continuousRecording": { "default": false, "type": "boolean", "const": false } }, "required": [ "events", "scheduledCapture", "continuousRecording" ], "additionalProperties": false }, "viewRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "request", "image", "source", "viewRevision" ], "additionalProperties": false } } } } } }, "/api/v1/setups/prepare": { "post": { "summary": "按用户确认生成规则", "operationId": "post_setups_prepare", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Setup" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "request": { "type": "string", "minLength": 2, "maxLength": 3000 }, "binding": { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "camera": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "video", "image", "live" ] } }, "required": [ "id", "name", "camera", "url", "type" ], "additionalProperties": false }, "referenceImage": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "annotatedReference": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "targetCrop": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "targetBox": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0.02, "maximum": 1 }, "h": { "type": "number", "minimum": 0.02, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "regionBox": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0.02, "maximum": 1 }, "h": { "type": "number", "minimum": 0.02, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "targetName": { "type": "string", "minLength": 1, "maxLength": 80 }, "regionName": { "type": "string", "minLength": 1, "maxLength": 80 }, "targetDescriptionEn": { "type": "string", "minLength": 3, "maxLength": 600 }, "regionDescriptionEn": { "type": "string", "minLength": 3, "maxLength": 500 }, "referenceMediaTime": { "type": "number", "minimum": 0 }, "memoryId": { "type": "string" }, "matchMode": { "default": "instance", "type": "string", "enum": [ "instance", "category" ] } }, "required": [ "source", "referenceImage", "annotatedReference", "targetCrop", "targetBox", "regionBox", "targetName", "regionName", "targetDescriptionEn", "regionDescriptionEn", "referenceMediaTime", "matchMode" ], "additionalProperties": false }, "taskKind": { "type": "string", "enum": [ "dog_boundary", "keys_check", "general" ] }, "answers": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 200 }, "answer": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "question", "answer" ], "additionalProperties": false } }, "notification": { "type": "string", "enum": [ "auto", "quiet" ] }, "confirmed": { "type": "boolean", "const": true }, "capturePolicy": { "default": { "mode": "event", "intervalSeconds": 300, "comparisonMaxAgeSeconds": 86400 }, "type": "object", "properties": { "mode": { "default": "event", "type": "string", "enum": [ "event", "scheduled", "manual" ] }, "intervalSeconds": { "default": 300, "type": "integer", "minimum": 60, "maximum": 86400 }, "comparisonMaxAgeSeconds": { "default": 86400, "type": "integer", "minimum": 60, "maximum": 172800 } }, "required": [ "mode", "intervalSeconds", "comparisonMaxAgeSeconds" ], "additionalProperties": false }, "locationAlerts": { "type": "object", "properties": { "notSeen": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "outside": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 3 }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "enabled", "confirmations", "attentionLevel" ], "additionalProperties": false }, "excludeCarried": { "default": true, "type": "boolean" } }, "required": [ "notSeen", "outside", "excludeCarried" ], "additionalProperties": false }, "recommendationReason": { "type": "string", "maxLength": 400 }, "viewRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "category": { "type": "string", "enum": [ "security", "care", "memory", "routine" ] }, "attentionLevel": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "request", "binding", "taskKind", "answers", "notification", "confirmed", "capturePolicy", "viewRevision" ], "additionalProperties": false } } } } } }, "/api/v1/setups/{id}": { "get": { "summary": "恢复设置草稿和试观察结果", "operationId": "get_setups_id_", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Setup" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/setups/{id}/trial": { "post": { "summary": "用可用画面试观察当前视野", "operationId": "post_setups_id_trial", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Trial" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frames": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "annotated": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "pairImage": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "mediaTime": { "type": "number", "minimum": 0 }, "capturedAt": { "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))$" }, "frameId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "image", "annotated", "mediaTime", "capturedAt", "frameId", "sourceId" ], "additionalProperties": false } }, "viewRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "frames", "viewRevision" ], "additionalProperties": false } } } } } }, "/api/v1/watches": { "post": { "summary": "确认并启用关注", "operationId": "post_watches", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Watch" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "confirmation": { "type": "object", "properties": { "target": { "type": "boolean", "const": true }, "rule": { "type": "boolean", "const": true } }, "required": [ "target", "rule" ], "additionalProperties": false }, "remember": { "default": false, "type": "boolean" }, "interval": { "default": 300, "type": "number", "minimum": 1, "maximum": 86400 } }, "required": [ "setupId", "confirmation", "remember", "interval" ], "additionalProperties": false } } } } }, "get": { "summary": "查询空间的全部关注", "operationId": "get_watches", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Watch" } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/watches/{id}": { "get": { "summary": "读取关注和最近状态", "operationId": "get_watches_id_", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Watch" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/watches/{id}/observe": { "post": { "summary": "上传一帧并完成视觉与规则判断", "operationId": "post_watches_id_observe", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Observation" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "viewRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "frame": { "type": "object", "properties": { "image": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "annotated": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "pairImage": { "type": "string", "maxLength": 2500000, "pattern": "^data:image\\/(jpeg|png|webp);base64," }, "mediaTime": { "type": "number", "minimum": 0 }, "capturedAt": { "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))$" }, "frameId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "image", "annotated", "mediaTime", "capturedAt", "frameId", "sourceId" ], "additionalProperties": false }, "manual": { "default": false, "type": "boolean" }, "signals": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "away", "rain", "doorbell" ] } } }, "required": [ "clientId", "viewRevision", "frame", "manual", "signals" ], "additionalProperties": false } } } } } }, "/api/v1/watches/{id}/state": { "post": { "summary": "暂停或继续关注", "operationId": "post_watches_id_state", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Watch" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "paused", "active" ] } }, "required": [ "state" ], "additionalProperties": false } } } } } }, "/api/v1/watches/{id}/replace": { "post": { "summary": "确认新设置并替换旧关注", "operationId": "post_watches_id_replace", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Watch" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "confirmation": { "type": "object", "properties": { "target": { "type": "boolean", "const": true }, "rule": { "type": "boolean", "const": true } }, "required": [ "target", "rule" ], "additionalProperties": false }, "remember": { "default": false, "type": "boolean" }, "interval": { "default": 300, "type": "number", "minimum": 1, "maximum": 86400 } }, "required": [ "setupId", "confirmation", "remember", "interval" ], "additionalProperties": false } } } } } }, "/api/v1/watches/{id}/delete": { "post": { "summary": "删除关注与关联证据", "operationId": "post_watches_id_delete", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmed": { "type": "boolean", "const": true }, "deleteMemory": { "default": false, "type": "boolean" } }, "required": [ "confirmed", "deleteMemory" ], "additionalProperties": false } } } } } }, "/api/v1/events": { "get": { "summary": "读取事件及独立处理状态", "operationId": "get_events", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/events/{id}/actions": { "post": { "summary": "记录用户处理动作", "operationId": "post_events_id_actions", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Event" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "action": { "type": "string", "enum": [ "read", "take_over", "user_completed", "dismiss", "reopen" ] }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "note": { "default": "", "type": "string", "maxLength": 240 } }, "required": [ "clientId", "action", "expectedRevision", "note" ], "additionalProperties": false } } } } } }, "/api/v1/commands": { "get": { "summary": "读取设备操作及状态", "operationId": "get_commands", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "deviceId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Command" } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } }, "post": { "summary": "创建待确认的设备操作", "operationId": "post_commands", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" }, { "name": "deviceId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Command" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 240 }, "watchId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "expiresInSeconds": { "default": 60, "type": "integer", "minimum": 10, "maximum": 120 }, "action": { "type": "string", "const": "night_vision.set" }, "params": { "type": "object", "properties": { "modeKey": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "modeKey" ], "additionalProperties": false } }, "required": [ "clientId", "deviceId", "reason", "expiresInSeconds", "action", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 240 }, "watchId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "expiresInSeconds": { "default": 60, "type": "integer", "minimum": 10, "maximum": 120 }, "action": { "type": "string", "const": "ptz.preset.goto" }, "params": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 255 } }, "required": [ "index" ], "additionalProperties": false } }, "required": [ "clientId", "deviceId", "reason", "expiresInSeconds", "action", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 240 }, "watchId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "expiresInSeconds": { "default": 60, "type": "integer", "minimum": 10, "maximum": 120 }, "action": { "type": "string", "const": "alarm.set" }, "params": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "SOUND_ONLY", "LIGHT_ONLY", "SOUND_AND_LIGHT" ] } }, "required": [ "enabled", "type" ], "additionalProperties": false } }, "required": [ "clientId", "deviceId", "reason", "expiresInSeconds", "action", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 240 }, "watchId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "expiresInSeconds": { "default": 60, "type": "integer", "minimum": 10, "maximum": 120 }, "action": { "type": "string", "const": "light.set" }, "params": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } }, "required": [ "clientId", "deviceId", "reason", "expiresInSeconds", "action", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 240 }, "watchId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "expiresInSeconds": { "default": 60, "type": "integer", "minimum": 10, "maximum": 120 }, "action": { "type": "string", "const": "motion_detection.set" }, "params": { "type": "object", "properties": { "types": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "required": [ "types" ], "additionalProperties": false } }, "required": [ "clientId", "deviceId", "reason", "expiresInSeconds", "action", "params" ], "additionalProperties": false } ] } } } } } }, "/api/v1/commands/{id}/decision": { "post": { "summary": "确认或取消具体设备操作", "operationId": "post_commands_id_decision", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Command" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "decision": { "type": "string", "enum": [ "confirm", "cancel" ] }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "clientId", "decision", "expectedRevision" ], "additionalProperties": false } } } } } }, "/api/v1/commands/{id}/claim": { "post": { "summary": "唯一执行端领取操作", "operationId": "post_commands_id_claim", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Command" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "clientId", "expectedRevision" ], "additionalProperties": false } } } } } }, "/api/v1/commands/{id}/receipt": { "post": { "summary": "记录 SDK 执行回执", "operationId": "post_commands_id_receipt", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Command" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "executionToken": { "type": "string", "minLength": 64, "maxLength": 64 }, "outcome": { "type": "string", "enum": [ "succeeded", "failed", "unknown" ] }, "sdkCode": { "default": "", "type": "string", "maxLength": 80 }, "message": { "default": "", "type": "string", "maxLength": 240 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 120000 } }, "required": [ "clientId", "executionToken", "outcome", "sdkCode", "message", "durationMs" ], "additionalProperties": false } } } } } }, "/api/v1/commands/{id}/verify": { "post": { "summary": "验证设备读回状态或重新试观察结果", "operationId": "post_commands_id_verify", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Command" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "executionToken": { "type": "string", "minLength": 64, "maxLength": 64 }, "observedAt": { "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))$" }, "state": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "setupId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-zA-Z0-9_-]+$" }, "targetConfirmed": { "type": "boolean" } }, "required": [ "clientId", "executionToken", "observedAt", "state" ], "additionalProperties": false } } } } } }, "/api/v1/memories": { "get": { "summary": "查询已确认对象记忆", "operationId": "get_memories", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Memory" } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/memories/{id}": { "get": { "summary": "读取对象参考图及确认信息", "operationId": "get_memories_id_", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "$ref": "#/components/schemas/Memory" }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/memories/{id}/delete": { "post": { "summary": "删除记忆并明确处理依赖关注", "operationId": "post_memories_id_delete", "security": [ { "WorkspaceBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "description": "同一次操作重试使用原值;同键不同正文返回 409。保留 24 小时;心跳和未变更视野的状态保留 60 秒。" } ], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmed": { "type": "boolean", "const": true }, "cascade": { "type": "boolean" } }, "required": [ "confirmed", "cascade" ], "additionalProperties": false } } } } } }, "/api/v1/metrics": { "get": { "summary": "读取请求 事件 设备操作统计", "operationId": "get_metrics", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/privacy": { "get": { "summary": "读取保存策略与处理位置", "operationId": "get_privacy", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/export": { "get": { "summary": "导出当前空间的设置与记录", "operationId": "get_export", "security": [ { "WorkspaceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功;设备执行与验证状态在 data.status 中", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId", "serverTime", "apiVersion" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "400": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "401": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "403": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "404": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "409": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "410": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "413": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "422": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "429": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "502": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } }, "503": { "description": "结构化错误", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId", "serverTime", "apiVersion" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": {} } }, "requestId": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/sessions": { "post": { "summary": "建立独立联调空间;将返回的 token 保存在系统安全存储", "security": [], "responses": { "201": { "description": "token 仅在此返回;它是空间访问凭据,不是 eufy 登录凭据", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "token", "workspaceId" ], "properties": { "token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "workspaceId": { "type": "string" } } }, "requestId": { "type": "string" }, "serverTime": { "type": "string" }, "apiVersion": { "type": "string" } } } } } } } } }, "/api/v1/openapi.json": { "get": { "summary": "下载本接口规范", "security": [], "responses": { "200": { "description": "OpenAPI 3.1 JSON" } } } } } }