Create a Device

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

Required scope: 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

bearerAuthapiKeyQuery

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

workspacestringRequired

Workspace ID (URL slug).

Body

application/json

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

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

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

HTTPcURLJavaScriptPython

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"
}

Example Request

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"}'

Example Response

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

Use the returned installId to bootstrap the device with the Roboflow Device Manager installer.

Notes on AI1 devices

• Setting device_type to "ai1" requires the workspace to have the deviceAio feature enabled, otherwise the request returns 403.

• offline_mode is only valid for AI1 devices on workspaces with roboflowLiteMode. Other combinations return 400 or 403.

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

• When AI1 + offline mode applies, the response also includes an offlineProvisioningQrPayload field encoding the QR payload for offline provisioning.

Notes on duplication

When sourceDeviceId is supplied, the new device is created from a copy of the source device's config. The source device must belong to the same workspace as the request, otherwise the request returns 403. A non-existent sourceDeviceId returns 404.