openapi: 3.1.0
info:
  title: 造物云业务接入 API
  version: 0.1.0
  description: 深脑、球球老师与业务运营系统使用的统一北向接口
servers:
  - url: https://api.device.zaowuyun.com
    description: 规划中的生产入口
paths:
  /v1/devices:
    get:
      summary: 查询调用方有权访问的设备
      responses:
        '200':
          description: 设备列表
  /v1/devices/{deviceId}:
    get:
      summary: 查询统一设备详情
      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            type: string
            pattern: '^DVC_'
      responses:
        '200':
          description: 设备详情
        '404':
          description: 设备不存在或不可见
  /v1/devices/{deviceId}/commands:
    post:
      summary: 创建受约束的设备命令
      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../device/v1/schemas/command.schema.json
      responses:
        '202':
          description: 命令进入队列
        '409':
          description: 所有权代次过期或命令被策略拒绝
  /v1/events:
    get:
      summary: 按游标读取规范化事件
      responses:
        '200':
          description: 事件页
