모든 엔드포인트는 공용 API 호스트의 /:workspace/devices/v2 아래에 있으며(https://api.roboflow.com), 읽기 엔드포인트에는 범위가 지정된 API 키 가 필요합니다. device:read 범위가 필요합니다. 디바이스를 변경하는 엔드포인트에는 device:update가 필요합니다. 명시적 범위 목록이 없는 워크스페이스 API 키에는 모든 범위가 암묵적으로 부여됩니다(레거시 동작). 명시적 scopes 배열이 있는 키에는 관련 범위가 포함되어야 합니다.

Deployment Manager API를 사용하면 다음을 수행할 수 있습니다:

선택적 엣지 서비스(Event Store, PLC Relay, RTSP Simulator, OPC UA Server)는 api.roboflow.com이 아니라 디바이스 주소에서 자체 HTTP API를 제공합니다. Roboflow API 키를 받지 않으며, 인증 및 오류 형식도 아래의 다른 항목들과 다릅니다. 다음을 참조하세요. 서비스.

인증

모든 엔드포인트는 다음 방법 중 하나로 워크스페이스 API 키를 허용합니다:

쿼리 문자열: ?api_key=YOUR_API_KEY
헤더: Authorization: Bearer YOUR_API_KEY

디바이스 범위 API 키

특정 디바이스용으로 발급된 API 키(예: 설치 중 RFDM이 발급)는 해당 디바이스로 범위가 제한됩니다. 이 키는 경로의 :deviceId 경로 매개변수가 키에 바인딩된 디바이스와 일치하는 라우트만 호출할 수 있습니다. 워크스페이스 전체 목록 및 생성 엔드포인트에서는 403 을 받으며, 일치하지 않는 :deviceId 경로에서도 마찬가지입니다.

워크스페이스 간 격리

워크스페이스 API 키는 해당 워크스페이스에 속한 디바이스만 읽거나 수정할 수 있습니다. 다른 워크스페이스가 소유한 디바이스 ID에 대한 요청은 ID가 유효하더라도 404를 반환합니다.

오류

상태

의미

400

잘못된 쿼리 매개변수(알 수 없는 time_period, 잘못된 cursor 또는 날짜, 잘못된 direction 등) 또는 잘못된 요청 본문.

401

API 키가 없거나 유효하지 않음.

403

다른 디바이스를 대상으로 하는 디바이스 범위 API 키, 워크스페이스 전체 목록/생성 라우트, 복제 중 다른 워크스페이스의 소스 디바이스, 또는 기능 게이팅된 요청 거부(예: AI1 생성 또는 offline_mode 가 해당 워크스페이스에서 활성화되지 않음).

404

디바이스, 스트림, 구성 또는 소스 디바이스를 찾을 수 없습니다. 다른 워크스페이스가 소유한 디바이스 ID에 대한 읽기 요청도 404를 반환합니다.

429

요청 한도를 초과했습니다. 로그는 IP당 분당 5회, 전역적으로 분당 50회로 제한되며, 텔레메트리 읽기는 디바이스당 분당 60회, 10초 동안 10회 버스트로 제한됩니다.

오류 응답은 다음 두 가지 형식 중 하나를 사용합니다:

핸들러 수준 오류(일반적으로 핸들러 자체에서 발생하는 400, 403, 404, 429)는 { "error": "<message>" }.
인증 및 워크스페이스 검증 실패(일반적으로 401)는 구조화된 error 객체를 반환합니다: { "error": { "message": "...", "status": 401, "type": "OAuthException", "hint": "..." } }.

로그 레이트 리미터는 또한 트리거될 때 일반 문자열 본문(JSON 아님)을 반환합니다. 429.

디바이스 목록 및 조회

디바이스 목록 조회

워크스페이스에 등록된 모든 디바이스를 나열합니다. 디바이스 범위 API 키는 이 엔드포인트를 호출할 수 없으며 403.

필수 범위: device:read

List Devices

get

List every device registered in the workspace. Device-scoped API keys cannot call this endpoint and receive 403.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

Responses

200

Devices in the workspace.

application/json

401

Missing or invalid API key.

application/json

403

API key is bound to a different device, or this endpoint is not permitted for device-scoped keys, a source device belongs to another workspace, or a feature gate (for example AI1 creation, roboflowLiteMode) blocks the request.

application/json

get/{workspace}/devices/v2

GET /{workspace}/devices/v2 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "status": "online",
      "last_heartbeat": "2026-08-09T06:22:31.495Z",
      "platform": "text",
      "platform_release": "text",
      "platform_version": "text",
      "architecture": "text",
      "hostname": "text",
      "rfdm_version": "text",
      "type": "text",
      "hardware": {
        "processor": "text",
        "gpu": "text",
        "total_memory_mb": 1,
        "total_disk_space_mb": 1
      },
      "tags": [
        "text"
      ],
      "created_at": "2026-08-09T06:22:31.495Z"
    }
  ]
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2?api_key=$ROBOFLOW_API_KEY"

예시 응답

{
  "data": [
    {
      "id": "abc123",
      "name": "factory-floor-cam-1",
      "status": "online",
      "last_heartbeat": "2026-04-28T12:00:00.000Z",
      "platform": "Linux",
      "platform_release": "5.10.104-tegra",
      "platform_version": "#1 SMP PREEMPT ...",
      "architecture": "aarch64",
      "hostname": "jetson-01",
      "rfdm_version": "1.2.3",
      "type": "jetson",
      "hardware": {
        "processor": "aarch64",
        "gpu": null,
        "total_memory_mb": null,
        "total_disk_space_mb": 124426534912
      },
      "tags": ["production", "line-3"],
      "created_at": "2026-01-15T08:30:00.000Z"
    }
  ]
}

다음 status 필드는 online 은 마지막 5분 이내에 heartbeat를 받은 경우이고, offline 은 더 오래된 경우이며, unknown 은 heartbeat가 한 번도 기록되지 않은 경우입니다. 새로 프로비저닝된 디바이스는 첫 heartbeat 이전에 목록에 나타나며, 그 전까지 status 는 unknown 이고 모니터링에서 파생되는 대부분의 필드는 null.

hardware.total_disk_space_mb 는 디바이스가 보고한 원시 값입니다. _mb 접미사에도 불구하고, RFDM이 보고한 디바이스는 현재 이 값을 바이트 단위로 반환합니다(예: 124426534912 약 124GB 디스크의 경우). 단위를 디바이스 정의 값으로 취급하세요.

디바이스 조회

id로 단일 디바이스를 가져옵니다. 디바이스가 존재하지 않거나 다른 워크스페이스에 속해 있으면 404 를 반환합니다.

필수 범위: device:read

Get a Device

get

Retrieve a single device by ID.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Responses

200

The device.

application/json

idstringOptional

namestring · nullableOptional

statusstring · enumOptional

online if a heartbeat was received within the last 5 minutes, offline if older, unknown if no heartbeat has ever been recorded.

Possible values:

last_heartbeatstring · date-time · nullableOptional

platformstring · nullableOptional

platform_releasestring · nullableOptional

platform_versionstring · nullableOptional

architecturestring · nullableOptional

hostnamestring · nullableOptional

rfdm_versionstring · nullableOptional

Version of the Roboflow Device Manager running on the device.

typestring · nullableOptional

Device type reported by the device (for example "jetson").

tagsstring[]Optional

created_atstring · date-time · nullableOptional

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}

GET /{workspace}/devices/v2/{deviceId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "status": "online",
  "last_heartbeat": "2026-08-09T06:22:31.495Z",
  "platform": "text",
  "platform_release": "text",
  "platform_version": "text",
  "architecture": "text",
  "hostname": "text",
  "rfdm_version": "text",
  "type": "text",
  "hardware": {
    "processor": "text",
    "gpu": "text",
    "total_memory_mb": 1,
    "total_disk_space_mb": 1
  },
  "tags": [
    "text"
  ],
  "created_at": "2026-08-09T06:22:31.495Z"
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}?api_key=$ROBOFLOW_API_KEY"

응답 본문은 목록 엔드포인트의 단일 항목과 동일합니다( data 배열로 감싸지 않음).

디바이스 생성

워크스페이스에 새 디바이스를 생성하고 설치에 필요한 식별자를 반환합니다. 디바이스 범위 API 키는 이 엔드포인트를 호출할 수 없으며 403.

필수 범위: device:update

Create a Device

post

Create a new device in the workspace and return the identifiers needed to install it. Device-scoped API keys cannot call this endpoint and receive 403. Requires the device:update scope.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

Body

device_namestringRequired

Human-readable name for the device. For AI1 devices that are not duplicating an existing device and do not specify a workflow_id, the slugified name must contain at least one alphanumeric character, otherwise the request returns 400.

device_typestringOptional

Device type. Common values are "ai1" and "edge"; any custom string is also accepted. AI1 creation requires the workspace to have the deviceAio feature enabled.

workflow_idstringOptional

Optional initial workflow assignment. For AI1 devices it seeds the default aione stream.

tagsstring[]Optional

Tags to attach to the device. Must be an array of non-empty strings; duplicates are removed and entries are trimmed.

offline_modebooleanOptional

Only valid for AI1 devices, and only if the workspace has the roboflowLiteMode feature.

sourceDeviceIdstringOptional

Duplicate an existing device's config instead of generating a fresh one. The source device must belong to the same workspace.

Responses

201

Device created.

application/json

deviceIdstringRequired

ID of the newly-created device.

installIdstringRequired

Short-lived install token. Feed it into GET /devices/v2/{installId}/install.sh from the device to bootstrap RFDM.

offlineProvisioningQrPayloadstringOptional

Returned only for AI1 devices created in offline mode. Encodes the QR payload used by the offline RFDM provisioner.

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

post/{workspace}/devices/v2

POST /{workspace}/devices/v2 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 124

{
  "device_name": "text",
  "device_type": "text",
  "workflow_id": "text",
  "tags": [
    "text"
  ],
  "offline_mode": true,
  "sourceDeviceId": "text"
}

{
  "deviceId": "text",
  "installId": "text",
  "offlineProvisioningQrPayload": "text"
}

예시 요청

curl -X POST "https://api.roboflow.com/{workspace}/devices/v2?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_name": "factory-floor-cam-2", "device_type": "edge"}'

예시 응답

{
  "deviceId": "abc456",
  "installId": "inst_xyz789"
}

반환된 installId 를 사용해 Roboflow Deployment Manager 설치 프로그램으로 디바이스를 부트스트랩합니다.

AI1 디바이스 관련 참고 사항

설정 device_type 을 "ai1" 로 지정하려면 워크스페이스에 deviceAio 기능이 활성화되어 있어야 하며, 그렇지 않으면 요청은 403.
offline_mode 는 roboflowLiteMode가 활성화된 워크스페이스의 AI1 디바이스에만 유효합니다. 다른 조합은 400 또는 403.
AI1 디바이스 중 기존 디바이스를 복제하지 않고 workflow_id를 지정하지 않는 경우, 슬러그화된 device_name 에는 최소 하나의 영숫자 문자가 포함되어야 하며, 그렇지 않으면 요청은 400.
AI1 + 오프라인 모드가 적용되면 응답에는 offlineProvisioningQrPayload 필드도 포함되어 오프라인 프로비저닝용 QR 페이로드를 인코딩합니다.

복제 관련 참고 사항

다음이 제공되면 sourceDeviceId 새 디바이스는 소스 디바이스의 구성 복사본으로 생성됩니다. 소스 디바이스는 요청과 같은 워크스페이스에 속해야 하며, 그렇지 않으면 요청은 403를 반환합니다. 존재하지 않는 sourceDeviceId 는 404.

디바이스 구성

워크스페이스 기본 구성 조회

워크스페이스 수준의 기본 디바이스 구성을 반환합니다. 이는 워크스페이스의 구성 패치가 병합된 기본 구성입니다. 새 디바이스를 프로비저닝할 때 POST /:workspace/devices/v2.

필수 범위: device:read

를 호출하기 전에 템플릿으로 사용하세요. 이는 워크스페이스 전체 엔드포인트입니다. 디바이스 범위 API 키는 403 를 받게 되며, 경로에 :deviceId 가 없기 때문입니다.

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/default-config?api_key=$ROBOFLOW_API_KEY"

예시 응답

{
  "config": {
    "version": "1.0.0",
    "config": {
      "inference": { "confidence": 0.7, "threshold": 0.3 },
      "device_type": "edge"
    },
    "services": {}
  },
  "patch": {
    "config": {
      "inference": { "confidence": 0.7 }
    }
  }
}

config -- 병합된 결과(기본값 + 워크스페이스 패치).
patch -- 워크스페이스에 저장된 패치입니다. 사용자 지정 패치가 없으면 빈 객체입니다. {} 워크스페이스에 사용자 지정 패치가 없으면.

구성 조회

디바이스의 현재 런타임 구성을 반환합니다. 응답 형식은 Roboflow Deployment Manager(RFDM) 구성 사양을 따릅니다.

필수 범위: device:read

Get Device Config

get

Returns the device's current runtime configuration. The response includes per-service environment_variables and any integration credentials embedded in the config; treat the body as sensitive.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Responses

200

The current device configuration.

application/json

Full RFDM configuration document.

Other propertiesanyOptional

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}/config

GET /{workspace}/devices/v2/{deviceId}/config HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/config?api_key=$ROBOFLOW_API_KEY"

응답은 전체 구성 문서이며 다음 최상위 필드를 포함합니다(이에 국한되지는 않음):

device_id, device_name
workspace_id
version, last_updated, last_updated_at, created_at
config (디바이스의 런타임 구성 트리, 포함 device_type, stream, 그리고 offline_mode)
services (다음을 포함한 서비스별 컨테이너 정의 image, volumes, 그리고 environment_variables)
environment_variables (서비스별 변수 외에 최상위 환경 변수, services)
production_mode, last_automatic_update, updated, updated_by, $schema, id

RFDM이 기록한 추가 필드가 나타날 수도 있습니다. 응답 형식은 확장 가능하다고 보고 필요한 필드만 의존하세요.

반환 404 디바이스가 존재하지 않거나 워크스페이스에 속하지 않거나, 해당 구성 저장본이 없는 경우.

응답에는 작성된 전체 구성이 포함됩니다. 서비스별 environment_variables 및 구성에 포함된 모든 통합 자격 증명은 마스킹되지 않은 상태로 반환됩니다. 응답 본문은 민감한 정보로 간주하고 평문으로 기록하지 마세요.

구성 기록

디바이스의 이전 구성 리비전을 최신 순으로 나열합니다.

필수 범위: device:read

List Config Revisions

get

List prior configuration revisions for a device, newest first.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Query parameters

limitinteger · min: 1 · max: 500Optional

Number of revisions to return. Clamped to 1-500.

Default: 10

cursorstringOptional

Opaque pagination cursor from a previous response. Pass back next_cursor to fetch the next page.

Responses

200

A page of revisions, newest first.

application/json

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}/config/history

GET /{workspace}/devices/v2/{deviceId}/config/history HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "revision_id": "text",
      "created_at": "2026-08-09T06:22:31.495Z",
      "created_by": "text"
    }
  ],
  "pagination": {
    "next_cursor": "text",
    "has_more": true,
    "limit": 1
  }
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/config/history?api_key=$ROBOFLOW_API_KEY&limit=10"

예시 응답

{
  "data": [
    {
      "revision_id": "rev_abc",
      "created_at": "2026-04-20T14:30:00.000Z",
      "created_by": "user_123"
    }
  ],
  "pagination": {
    "next_cursor": "...",
    "has_more": true,
    "limit": 10
  }
}

잘못된 cursor 는 400 와 함께 {"error": "잘못된 cursor 형식"}.

디바이스 명령

웹 앱에서 시작하는 작업(예: 디바이스 재시작, 스트림 일시 중지, 카메라 검색)은 명령으로 대기열에 추가됩니다. 디바이스는 다음 폴링에서 이를 가져갑니다.

보류 중인 명령 조회

디바이스를 위해 대기 중인 명령을 가장 오래된 것부터 반환합니다. 읽는다고 해서 제거되지는 않습니다. 명령은 디바이스가 실행했다고 보고할 때까지 대기열에 남아 있으므로, 명령 수행 중 재시작된 디바이스는 이를 다시 보게 됩니다. 5분 이상 전에 대기열에 들어간 명령은 만료되어 절대 전달되지 않으며, 나중에 실행하면 요청한 내용과 일치하지 않기 때문입니다.

필수 범위: device:read

Get Pending Commands

get

Returns the commands queued for a device, oldest first. The read does not remove commands: each one stays queued until the device acknowledges it. Commands queued more than 5 minutes ago expire and are not returned.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Responses

200

The commands waiting for the device.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}/commands

GET /{workspace}/devices/v2/{deviceId}/commands HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "commands": [
    {
      "id": "cmd_abc",
      "action": "restart",
      "data": {}
    }
  ]
}

명령 대기열 추가

디바이스가 다음 폴링에서 실행할 명령을 대기열에 넣습니다. 이는 웹 앱에서 디바이스를 재시작하거나 스트림을 시작할 때 수행하는 작업을 API에서 하는 것입니다.

필수 범위: device:update

Queue a Command

post

Queue a command for a device. The device runs it on its next poll. This is the API equivalent of the actions you start from the web app.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Body

actionstring · enumRequired

What the device should do. An action outside this list returns 400.

Example: restartPossible values:

Responses

200

The command was queued.

application/json

idstringOptional

Command ID, used to match the device's acknowledgement.

Example: cmd_abc

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

post/{workspace}/devices/v2/{deviceId}/commands

POST /{workspace}/devices/v2/{deviceId}/commands HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "action": "restart",
  "data": {}
}

{
  "id": "cmd_abc"
}

디바이스 스트림

스트림 목록

디바이스에 구성된 모든 스트림을 나열합니다.

필수 범위: device:read

List Streams

get

List every stream configured on a device, including streams that are set up in the device config but have not reported in yet, which are returned with a provisioning status. Credentials are stripped from URLs and known credential-bearing object keys are removed from each stream's source.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Responses

200

Streams configured on the device.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}/streams

GET /{workspace}/devices/v2/{deviceId}/streams HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "status": "text",
      "provisioning": true,
      "mode": "continuous",
      "pipeline_id": "text",
      "workflow_id": "text",
      "source": "text",
      "configured_source": "text",
      "started_at": "2026-08-09T06:22:31.495Z",
      "last_event_at": "2026-08-09T06:22:31.495Z",
      "camera_fps": 1,
      "inference_fps": 1,
      "sharpness": 1,
      "error": "text",
      "status_events": [
        {
          "id": "text",
          "event": "text",
          "entity_type": "text",
          "entity_id": "text",
          "event_description": "text",
          "error_code": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "device_timestamp": "text",
          "server_timestamp": "text",
          "event_end_timestamp": "text"
        }
      ]
    }
  ]
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/streams?api_key=$ROBOFLOW_API_KEY"

예시 응답

{
  "data": [
    {
      "id": "stream_abc",
      "name": "entrance-cam",
      "status": "running",
      "pipeline_id": "pipe_123",
      "workflow_id": "wf_456",
      "source": "rtsp://192.168.1.100:554/live",
      "started_at": "2026-04-28T10:00:00.000Z",
      "last_event_at": "2026-04-28T12:30:00.000Z",
      "camera_fps": 29.97,
      "inference_fps": 12.4,
      "sharpness": 0.82,
      "error": null
    }
  ]
}

소스 정리

다음 소스 필드는 반환되기 전에 항상 정리기를 거칩니다:

소스가 URL인 경우, 다음의 모든 사용자 정보 (scheme://user:pass@host/...)는 제거됩니다. 예를 들어, rtsp://admin:password@192.168.1.100:554/live 다음과 같이 됩니다 rtsp://192.168.1.100:554/live.
소스가 객체인 경우, 소문자 이름이 다음인 키는 password, passwd, secret, api_key, apikey, auth, authorization, token, 또는 access_token 응답에서 제거됩니다. 다른 모든 키는 유지됩니다.
배열과 중첩 객체는 재귀적으로 정리됩니다.

스트림 가져오기

단일 스트림을 가져옵니다. 반환값은 404 스트림이 디바이스에 존재하지 않거나, 디바이스가 존재하지 않거나 또는 귀하의 워크스페이스에 속하지 않으면.

필수 범위: device:read

Get a Stream

get

Retrieve a single stream on a device. A stream that exists only in the device config is returned as a provisioning entry. Returns 404 when the stream exists neither live nor in the config.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

streamIdstringRequired

Stream ID.

Query parameters

includestring · enumOptional

Set to status_events to attach the stream's 20 most recent lifecycle events from the last 7 days.

Possible values:

Responses

200

The stream.

application/json

idstring · nullableOptional

namestring · nullableOptional

statusstring · nullableOptional

Stream status reported by the streams service (for example "running", "stopped", or transitional states). Streams that exist in the device config but have not reported in yet are returned with status "provisioning".

provisioningbooleanOptional

True when the stream is in the config but has not reported in yet.

modestring · enum · nullableOptional

"triggered" for streams that run their Workflow only when triggered, "continuous" for streams that run all the time. Null when the stream has no config entry.

Possible values:

pipeline_idstring · nullableOptional

workflow_idstring · nullableOptional

sourceone ofOptional

Sanitized source descriptor. URL userinfo is stripped; object keys named password, passwd, secret, api_key, apikey, auth, authorization, token, or access_token are removed.

string · nullableOptional

objectOptional

configured_sourceone of · nullableOptional

Source taken from the device config, sanitized the same way as source. Filled in for provisioning streams that have no live source yet, and null otherwise.

string · nullableOptional

objectOptional

started_atstring · date-time · nullableOptional

last_event_atstring · date-time · nullableOptional

camera_fpsnumber · nullableOptional

Camera frame rate reported by the device heartbeat.

inference_fpsnumber · nullableOptional

Inference pipeline frame rate reported by the device heartbeat.

sharpnessnumber · nullableOptional

Image sharpness score reported by the device heartbeat.

errorstring · nullableOptional

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}/streams/{streamId}

GET /{workspace}/devices/v2/{deviceId}/streams/{streamId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "status": "text",
  "provisioning": true,
  "mode": "continuous",
  "pipeline_id": "text",
  "workflow_id": "text",
  "source": "text",
  "configured_source": "text",
  "started_at": "2026-08-09T06:22:31.495Z",
  "last_event_at": "2026-08-09T06:22:31.495Z",
  "camera_fps": 1,
  "inference_fps": 1,
  "sharpness": 1,
  "error": "text",
  "status_events": [
    {
      "id": "text",
      "event": "text",
      "entity_type": "text",
      "entity_id": "text",
      "event_description": "text",
      "error_code": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "device_timestamp": "text",
      "server_timestamp": "text",
      "event_end_timestamp": "text"
    }
  ]
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/streams/{streamId}?api_key=$ROBOFLOW_API_KEY"

응답 본문은 목록 엔드포인트의 단일 항목과 동일합니다( data 배열로 감싸지 않음).

파이프라인 상태 보고

디바이스가 실행 중인 인퍼런스 파이프라인을 보고합니다. 보고된 각 파이프라인은 해당 스트림과 그 FPS 및 선명도 지표를 함께 업데이트합니다. 디바이스 구성에 선언된 스트림은 스트림 키로 매칭되므로, 디바이스가 이를 보고하면 더 이상 프로비저닝 중으로 표시되지 않습니다.

RFDM은 device-manager 컨테이너 없이 실행되는 디바이스에 대해 이를 전송합니다. 해당 컨테이너를 실행하는 디바이스는 healthcheck에서 동일한 데이터를 보고하므로 이 엔드포인트가 필요하지 않습니다.

필수 범위: device:update

Report Pipeline Status

post

Report the inference pipelines a device is running. Each reported pipeline updates the matching stream, including its FPS and sharpness metrics. A stream that was declared in the device config is matched by its stream key and stops showing as provisioning. Devices running the device-manager container report the same data inside their healthcheck instead.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Body

timestampone ofOptional

When the status was measured, as a Unix timestamp in seconds or an ISO 8601 string. Defaults to the time the request is received.

Example: 2026-04-28T10:00:00Z

integerOptional

stringOptional

Responses

200

The reported pipelines were applied.

application/json

successbooleanOptionalExample: true

updatedintegerOptional

How many reported pipelines had a pipeline_id.

Example: 1

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

post/{workspace}/devices/v2/{deviceId}/pipelines-status

POST /{workspace}/devices/v2/{deviceId}/pipelines-status HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 227

{
  "pipelines": [
    {
      "pipeline_id": "entrance-cam",
      "status": "RUNNING",
      "camera_fps": 30,
      "inference_fps": 14.5,
      "sharpness": 0.82,
      "params": {
        "video_reference": "rtsp://192.168.1.100:554/live",
        "max_fps": 5
      }
    }
  ],
  "timestamp": "2026-04-28T10:00:00Z"
}

{
  "success": true,
  "updated": 1
}

인퍼런스 서버의 /inference_pipelines/list 응답을 변경 없이 그대로, {"success": true, "data": {"pipelines": [...]}}. 해당 본문이 "success": false, 디바이스가 파이프라인 목록을 가져오지 못한 것이므로, 요청은 아무 작업도 하지 않으며 기존 스트림은 그대로 둡니다.

디바이스 로그 및 텔레메트리

로그

페이지네이션된 디바이스 로그를 반환합니다.

필수 범위: device:read

Get Device Logs

get

Returns paginated device logs. Rate-limited to 5 requests per minute per IP and 50 per minute globally.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Query parameters

limitinteger · min: 1 · max: 1000Optional

Number of log entries to return. Clamped to 1-1000.

Default: 100

start_timestring · date-timeOptional

ISO 8601 timestamp lower bound. Returns 400 if not parseable.

end_timestring · date-timeOptional

ISO 8601 timestamp upper bound. Returns 400 if not parseable.

servicestringOptional

Comma-separated list of service names to filter by.

severitystringOptional

Comma-separated list of severity levels to filter by (for example "INFO,WARN,ERROR").

cursorstring · date-timeOptional

Pass back next_cursor from the previous response to fetch the next page (older logs). Returns 400 if not parseable.

Responses

200

A page of logs.

application/json

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

429

Rate limit exceeded. Most rate-limited responses are JSON; the device logs limiter can return a plain string response.

get/{workspace}/devices/v2/{deviceId}/logs

GET /{workspace}/devices/v2/{deviceId}/logs HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "timestamp": "text",
      "service": "text",
      "severity": "text",
      "message": "text"
    }
  ],
  "pagination": {
    "next_cursor": "text",
    "has_more": true,
    "limit": 1
  }
}

예시 요청

속도 제한: 워크스페이스당 분당 120개 요청. 로그 읽기와 로그 수집은 별도의 속도 제한 버킷을 사용하므로, 로그를 폴링해도 수집 할당량에 영향을 주지 않습니다(반대의 경우도 마찬가지입니다).

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/logs?api_key=$ROBOFLOW_API_KEY&limit=50"

예시 응답

{
  "data": [
    {
      "timestamp": "2026-04-28T12:01:00.000Z",
      "service": "inference",
      "severity": "INFO",
      "message": "Model loaded successfully"
    }
  ],
  "pagination": {
    "next_cursor": "2026-04-28T12:01:00.000Z",
    "has_more": true,
    "limit": 50
  }
}

속도 제한

이 엔드포인트의 속도 제한은 IP 주소당 분당 5개 요청 및 전역적으로 분당 50개 요청. 초과 요청은 반환됩니다 429.

텔레메트리

고정된 시간 창 동안 버킷화된 디바이스의 집계 하드웨어 지표(CPU, 메모리, 디스크, GPU)와 스트림별 FPS를 반환합니다.

필수 범위: device:read

Get Device Telemetry

get

Returns device health data: hardware metrics (CPU, memory, disk, GPU, network) bucketed across the requested time window, plus Docker and NTP health, per-service container status, per-stream FPS, hardware, and network interfaces. Rate-limited to 60 requests per minute per device with a 10-request burst over 10 seconds.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Query parameters

time_periodstring · enumOptional

Time window to aggregate over.

Default: 24hPossible values:

includestringOptional

Comma-separated sections to return: metrics, system_status, services, service_history, stream_fps, hardware, network_interfaces. Every section except service_history is returned by default, and service_history implies services. Smaller requests return faster. An unknown section returns 400 with the valid values.

Default: metrics,system_status,services,stream_fps,hardware,network_interfaces

Responses

200

Aggregated telemetry buckets.

application/json

Sections are selected with the include query parameter. Every section except service_history is returned by default.

time_periodstring · enumOptionalPossible values:

bucket_intervalstringOptional

Human-readable bucket size (for example "30 MINUTE", "4 HOUR").

fill_interval_secondsintegerOptional

services_truncatedbooleanOptional

Present when the service query hit its cap. Gaps in service history may come from the cap rather than a real outage.

stream_fps_truncatedbooleanOptional

Present when the stream FPS query hit its row cap, so some buckets are missing.

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

429

Rate limit exceeded. Most rate-limited responses are JSON; the device logs limiter can return a plain string response.

get/{workspace}/devices/v2/{deviceId}/telemetry

GET /{workspace}/devices/v2/{deviceId}/telemetry HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "time_period": "1h",
  "bucket_interval": "text",
  "fill_interval_seconds": 1,
  "buckets": [
    {
      "bucket_start": "2026-08-09T06:22:31.495Z",
      "cpu_pct": 1,
      "used_memory_mb": 1,
      "total_memory_mb": 1,
      "used_disk_space_mb": 1,
      "total_disk_space_mb": 1,
      "gpu_pct": 1,
      "network_upload_bytes_per_sec": 1,
      "network_download_bytes_per_sec": 1
    }
  ],
  "system_status": {
    "docker": [
      {
        "bucket_start": "2026-08-09T06:22:31.495Z",
        "status": "up",
        "availability_pct": 1,
        "version": "text",
        "server": "text"
      }
    ],
    "ntp": [
      {
        "bucket_start": "2026-08-09T06:22:31.495Z",
        "status": "up",
        "availability_pct": 1,
        "version": "text",
        "server": "text"
      }
    ]
  },
  "services": [
    {
      "name": "text",
      "current_status": "up",
      "latest": {
        "container_id": "text",
        "container_name": "text",
        "image": "text",
        "cpu_pct": 1,
        "mem_usage_mb": 1,
        "sample_count": 1,
        "last_seen": "2026-08-09T06:22:31.495Z"
      },
      "history": [
        {
          "bucket_start": "2026-08-09T06:22:31.495Z",
          "status": "text",
          "cpu_pct": 1,
          "mem_usage_mb": 1
        }
      ]
    }
  ],
  "services_truncated": true,
  "stream_fps": [
    {
      "pipeline_id": "text",
      "stream_name": "text",
      "stream_id": "text",
      "buckets": [
        {
          "bucket_start": "2026-08-09T06:22:31.495Z",
          "camera_fps": 1,
          "inference_fps": 1
        }
      ]
    }
  ],
  "stream_fps_truncated": true,
  "hardware": {
    "rfdm_version": "text",
    "os_name": "text",
    "os_version": "text",
    "cpu_model": "text",
    "cpu_cores": 1,
    "jetson_model": "text",
    "jetpack_version": "text",
    "l4t_version": "text",
    "jetson_power_mode": "text",
    "nvidia_gpu": "text",
    "nvidia_driver": "text",
    "system_uptime_seconds": 1,
    "ntp_server": "text",
    "ntp_server_available": true,
    "reported_at": "2026-08-09T06:22:31.495Z",
    "additional": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "network_interfaces": [
    {
      "name": "text",
      "mac_address": "text",
      "ip_addresses": [
        "text"
      ]
    }
  ],
  "metadata": {
    "data_points": 1,
    "time_range": {
      "start": "2026-08-09T06:22:31.495Z",
      "end": "2026-08-09T06:22:31.495Z"
    }
  }
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/telemetry?api_key=$ROBOFLOW_API_KEY&time_period=24h"

버킷 크기는 시간 구간마다 고정됩니다:

time_period

버킷 간격

채움 간격(초)

1h

2 MINUTE

120

24h

30 MINUTE

1800

7d

4 HOUR

14400

14d

8 HOUR

28800

예시 응답

{
  "time_period": "24h",
  "bucket_interval": "30 MINUTE",
  "fill_interval_seconds": 1800,
  "buckets": [
    {
      "bucket_start": "2026-04-28T00:00:00.000Z",
      "cpu_pct": 42.5,
      "used_memory_mb": 3200,
      "total_memory_mb": 7860,
      "used_disk_space_mb": 15000,
      "total_disk_space_mb": 29000,
      "gpu_pct": 78.2
    }
  ]
}

요청한 기간에서 텔레메트리를 받지 못한 버킷도 반환되며, 각 지표 필드는 null.

속도 제한

이 엔드포인트는 디바이스당 속도 제한이 적용되어 분당 60개 요청 추가로 10초당 10개 요청 버스트 제한기. 초과 요청은 반환됩니다 429. 동일한 디바이스별 텔레메트리 할당량은 디바이스의 텔레메트리 수집 경로와 공유되므로, 과도한 읽기 요청은 동일한 디바이스의 수집에 영향을 줄 수 있습니다.

디바이스 이벤트

디바이스 및 스트림 라이프사이클 이벤트(예: 디바이스 부팅, 스트림 시작 및 중지, 오류, 구성 변경)를 반환합니다.

필수 범위: device:read

Get Device Events

get

Returns device and stream lifecycle events (for example device boots, stream starts and stops, errors, config changes).

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

deviceIdstringRequired

Device ID.

Query parameters

limitinteger · min: 1 · max: 1000Optional

Number of events to return. Clamped to 1-1000.

Default: 100

entity_typestringOptional

Filter to events for a single entity type (for example "device", "stream").

entity_idstringOptional

Filter to events for a single entity ID.

eventstringOptional

Filter to events with this event name.

start_timestring · date-timeOptional

ISO 8601 timestamp lower bound. Returns 400 if not parseable.

end_timestring · date-timeOptional

ISO 8601 timestamp upper bound. Returns 400 if not parseable.

cursorstringOptional

Opaque pagination cursor from a previous response. Pass back next_cursor or prev_cursor. Malformed cursors return 400.

directionstring · enumOptional

Pagination direction. Other values return 400.

Default: backwardPossible values:

Responses

200

A page of events.

application/json

400

Invalid query parameter or request body.

application/json

401

Missing or invalid API key.

application/json

403

application/json

404

Device, stream, configuration, or source device not found. Read requests for devices owned by another workspace also return 404.

application/json

get/{workspace}/devices/v2/{deviceId}/events

GET /{workspace}/devices/v2/{deviceId}/events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "event": "text",
      "entity_type": "text",
      "entity_id": "text",
      "event_description": "text",
      "error_code": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "device_timestamp": "text",
      "server_timestamp": "text",
      "event_end_timestamp": "text"
    }
  ],
  "pagination": {
    "next_cursor": "text",
    "prev_cursor": "text",
    "has_more": true,
    "limit": 1
  }
}

예시 요청

curl "https://api.roboflow.com/{workspace}/devices/v2/{deviceId}/events?api_key=$ROBOFLOW_API_KEY&limit=50"

예시 응답

{
  "data": [
    {
      "id": "evt_abc123",
      "event": "device.boot",
      "entity_type": "device",
      "entity_id": "abc123",
      "event_description": "디바이스가 시작되었습니다",
      "error_code": null,
      "metadata": { "source": "boot-loop" },
      "device_timestamp": "2026-04-28 10:00:00",
      "server_timestamp": "2026-04-28 10:00:01",
      "event_end_timestamp": null
    }
  ],
  "pagination": {
    "next_cursor": "...",
    "prev_cursor": "...",
    "has_more": true,
    "limit": 50
  }
}

다음 디바이스 타임스탬프, 서버 타임스탬프, 그리고 이벤트 종료 타임스탬프 필드는 다음 형식으로 포맷됩니다 YYYY-MM-DD HH:MM:SS[.SSS] UTC 기준입니다. 이 API의 다른 타임스탬프처럼 ISO-8601으로 정규화되지 않습니다.

이벤트 종료 타임스탬프 또한 epoch-zero 문자열로 반환될 수 있습니다 "1970-01-01 00:00:00.000" (대신 null) 이벤트에 기록된 종료 타임스탬프가 없을 때.

이전스트림 관리 API 다음설정

마지막 업데이트 2일 전

도움이 되었나요?