기기

기기 상태를 확인하고 명령을 보냅니다. 카메라 사진, 루틴 실행, 출입 기록도 여기에 있습니다.

기기 목록 조회

GET

https://api.superplace.so

/device/v1/devices

OAuth 2.0

Bearer (JWT)

매장의 문, 카메라, 키오스크, 스위치, 센서 같은 기기를 연결 상태와 함께 돌려줍니다. 행마다 id, 종류(kind), 이름, 연결 상태(health.state: online, offline, unknown), 받는 명령 묶음(capabilities)이 있습니다. unknown은 아직 한 번도 연결된 적이 없다는 뜻입니다.

필요 권한: 기기 상태·경보 보기(device:status:read)

MCP 도구: device_get_devices

기기 목록 조회 › query Parameters

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

기기 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

기기 상태 조회

GET

https://api.superplace.so

/device/v1/devices/{id}

OAuth 2.0

Bearer (JWT)

기기 한 대의 지금 상태와 설정을 돌려줍니다. 받는 명령 묶음(capabilities)을 확인한 뒤 명령을 보내세요.

필요 권한: 기기 상태·경보 보기(device:status:read)

MCP 도구: device_get_devices_id

기기 상태 조회 › path Parameters

id

string · required

기기 ID입니다. 기기 목록의 id입니다.

기기 상태 조회 › query Parameters

include

string

함께 담을 정보입니다. 필요한 경우에만 보냅니다.

days

integer

기간을 요구하는 정보에 적용할 일수입니다.

기기 상태 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

기기 명령 보내기

POST

https://api.superplace.so

/device/v1/devices/{id}/commands

OAuth 2.0

Bearer (JWT)

기기 하나를 제어합니다. 먼저 기기 상태 조회로 그 기기가 받는 capability를 확인하고, 그 목록에 있는 명령만 보내세요. 주요 명령은 다음과 같습니다. switch.on·switch.off, thermostat.setClimate(mode: off, heat, cool, auto, dry, fan_only와 coolingSetpoint·heatingSetpoint, 섭씨), switchLevel.setLevel(level 0~~100), colorTemperature.setColorTemperature(2000~~6500), windowShade.open·close·stop, door.open·door.close·door.hold(minutes 0~~720, 모두 reason 선택), momentary.push(slot 1~~6, signal on 또는 off, 적외선 리모컨). 기기가 실행했다고 답한 뒤에 응답합니다. 연결이 끊긴 기기는 409(DEVICE.OFFLINE), 기기가 거절하면 502, 답하지 않으면 504입니다. 재시작, 펌웨어 업데이트, 저장장치 포맷 같은 유지보수 명령은 사용자가 분명히 요청했을 때만 보내세요.

필요 권한: 기기 조작(device:control:operate)

MCP 도구: device_post_devices_id_commands

기기 명령 보내기 › path Parameters

id

string · required

기기 ID입니다. 기기 목록의 id입니다.

기기 명령 보내기 › Headers

Idempotency-Key

string · required

요청마다 고유한 문자열입니다. 같은 값으로 다시 보내면 명령을 다시 실행하지 않고 처음 결과를 돌려줍니다.

기기 명령 보내기 › Request Body

capability

string · required

명령 묶음 이름입니다. 예: switch, thermostat, door

command

string · required

명령 이름입니다. 예: on, setClimate, open

args

object

명령 인자입니다. 명령마다 다릅니다. 예: thermostat.setClimate는 mode와 설정 온도를 지정합니다.

기기 명령 보내기 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/device/v1/devices/{id}/commands

curl https://api.superplace.so/device/v1/devices/:id/commands \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1024-open-1' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "capability": "switch",
  "command": "on"
}'

Example Request Body

{
  "capability": "switch",
  "command": "on"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800032",
    "capability": "switch",
    "command": "on",
    "outcome": "reported",
    "state": "on",
    "sentAt": "2026-11-03T05:00:12Z",
    "reportedAt": "2026-11-03T05:00:13Z",
    "operationId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800122"
  }
}

json

application/json

카메라 사진 조회

GET

https://api.superplace.so

/device/v1/devices/{id}/files

OAuth 2.0

카메라의 특정 시점 사진을 돌려줍니다. purpose=storyboard와 at(RFC3339)을 보내면 그 시각이 속한 5분 동안 10초 간격으로 찍은 작은 사진 30장의 모음을 돌려줍니다. 모음은 5분이 끝날 때 올라오므로 지금 상황은 약 5분 전 시각으로 요청하세요. purpose=cameraFrame과 at은 카메라 이벤트가 시작될 때의 정지 사진입니다. 사진은 녹화 허브에 연결된 카메라만 있습니다. 그 시각 근처에 사진이 없으면 404입니다. 내보낸 영상(purpose=cameraClip, fileId)은 사진이 아니라 동영상입니다. 응답의 url은 한시적인 주소입니다.

필요 권한: 카메라 영상 보기(device:video:read)

MCP 도구: device_get_devices_id_files

카메라 사진 조회 › path Parameters

id

string · required

카메라 기기 ID입니다.

카메라 사진 조회 › query Parameters

purpose

string · enum · required

가져올 파일 종류입니다. cameraFrame(이벤트 시작 정지 사진), storyboard(5분 모음), cameraClip(내보낸 영상)입니다.

Enum values:

cameraFrame

storyboard

cameraClip

at

string · date-time

볼 시각입니다. RFC3339 형식이고 cameraFrame과 storyboard에서 필수입니다.

fileId

string · uuid

영상 내보내기로 받은 파일 ID입니다. cameraClip에서 필수입니다.

카메라 사진 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

출입 기록 조회

GET

https://api.superplace.so

/device/v1/entry-log

OAuth 2.0

문이 열린 기록을 최신순으로 돌려줍니다. 어느 문이 언제 어떤 방법으로 열렸는지 담깁니다. method는 phone(전화), gate(QR), link(입장 링크), kiosk, exit_button, api, console, auto 등입니다. result는 opened(열림), closed(닫힘), unconfirmed(확인되지 않음) 같은 결과입니다.

필요 권한: 문 열림 기록 보기(device:entry-log:read)

MCP 도구: device_get_entry_log

출입 기록 조회 › query Parameters

limit

integer · min: 1 · max: 200

돌려줄 최대 건수입니다. 1~200, 기본 50입니다.

Default: 50

deviceId

string · uuid

문 ID입니다. 그 문의 기록만 돌려줍니다.

from

string · date-time

조회 시작 시각입니다. RFC3339 형식입니다.

to

string · date-time

조회 끝 시각입니다. RFC3339 형식입니다.

result

string

결과로 거릅니다. 예: opened

filter

string

매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 조직 계정으로 연결했을 때 필수입니다.

출입 기록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

루틴 목록 조회

GET

https://api.superplace.so

/device/v1/scenarios

OAuth 2.0

자동화 루틴을 시작 조건, 조건, 동작과 함께 돌려줍니다. 루틴마다 사용 여부(enabled), 마지막 실행 시각(lastRunAt), 마지막 결과(lastResult)가 있습니다.

필요 권한: 자동화 루틴 보기(device:routines:read)

MCP 도구: device_get_scenarios

루틴 목록 조회 › query Parameters

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

루틴 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

GET/device/v1/scenarios

curl https://api.superplace.so/device/v1/scenarios \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800191",
      "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
      "name": "퇴실 후 전체 끄기",
      "enabled": true,
      "starters": [
        {
          "kind": "time",
          "at": "22:00",
          "days": [
            "mon",
            "tue",
            "wed",
            "thu",
            "fri"
          ]
        }
      ],
      "conditions": [],
      "actions": [
        {
          "kind": "device",
          "deviceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800032",
          "action": "off"
        }
      ],
      "cooldownSec": 0,
      "createdAt": "2026-10-10T00:00:00Z",
      "lastRunAt": "2026-11-02T13:00:00Z"
    }
  ],
  "total": 1
}

json

application/json

루틴 실행

POST

https://api.superplace.so

/device/v1/scenarios/{id}/run

OAuth 2.0

저장된 루틴을 시작 조건과 조건을 건너뛰고 지금 실행합니다. 예를 들어 3호실 전체 끄기 같은 루틴입니다. 루틴 ID는 루틴 목록에서 찾습니다. 응답에 기기별 결과가 담깁니다. 루틴에 지연이 있으면 outcome이 started이고 나머지는 나중에 끝납니다. 요청이 있을 때 도는 루틴과 조건이 참인 동안 유지되는 루틴은 실행할 수 없고 409입니다.

필요 권한: 자동화 루틴 수정(device:routines:write)

MCP 도구: device_post_scenarios_id_run

루틴 실행 › path Parameters

id

string · uuid · required

루틴 ID입니다. 루틴 목록의 id입니다.

루틴 실행 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

직원 파트너 키(레거시)