---
title: "Provision a new device"
method: POST
path: "/devices"
tags: ["Devices"]
---

# Provision a new device

`POST /devices`

Requests a new device for the authenticated user from the device spec in the request body. Optional query parameters select the canonical device type, target country, billing mode, and a profile to use as the base spec; deprecated device-type aliases remain accepted only during the documented compatibility grace period. The response returns the device and its stream token.

## Query parameters

- `deviceType` 'android_cloud_phone' | 'dedicated_premium_device' | 'dedicated_physical_device' | 'dedicated_ios_device' | 'dedicated_emulated_device' — Deprecated device type aliases are accepted during a compatibility grace period: dedicated_premium_device maps to android_cloud_phone, dedicated_physical_device maps to android_physical_phone, dedicated_ios_device maps to ios_stealth_phone, and dedicated_emulated_device maps to android_emulator.
- `country` string — ISO 3166-1 alpha-2 country code. If omitted the system picks the country with the most availability.
- `profileId` string — Profile ID to use as device spec
- `billing` 'auto' | 'subscription' | 'minute' — Billing mode. 'auto' uses a subscription slot when available and otherwise bills per minute; 'subscription' requires an available subscription slot; 'minute' bills per minute. Only cloud phone and cloud emulator devices support per-minute billing.

## Request body

- DeviceSpec
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `androidVersion` integer
  - `apps` string[], nullable
  - `carrier` DeviceCarrier
    - `GsmOperatorAlpha` string, required
    - `GsmOperatorNumeric` integer, required
    - `GsmSimOperatorAlpha` string, required
    - `GsmSimOperatorIsoCountry` string, required
    - `GsmSimOperatorNumeric` integer, required
    - `PersistSysTimezone` string, required
  - `country` string
  - `files` string[], nullable
  - `identifiers` DeviceIdentifiers
    - `BootloaderSerialNumber` string, required
    - `IdentifierAndroidID` string, required
    - `IdentifierAppSetID` string, required
    - `IdentifierBluetoothMAC` string, required
    - `IdentifierGAID` string, required
    - `IdentifierGSFID` string, required
    - `IdentifierICCID` string, required
    - `IdentifierIMEI` string, required
    - `IdentifierIMSI` string, required
    - `IdentifierMEID` string, required
    - `IdentifierMediaDRMID` string, required
    - `IdentifierPhoneNumber` string, required
    - `IdentifierSerial` string, required
    - `IdentifierWifiMAC` string, required
    - `SerialNumber` string, required
  - `locale` string
  - `location` Location
    - `$schema` string, uri — A URL to the JSON Schema for this object.
    - `latitude` number, double, required
    - `longitude` number, double, required
  - `name` string
  - `proxy` ProxyConfig1
    - `connect` Ref
      - `country` string — ISO 3166-1 alpha-2 country code; provisions (or reuses) a rotating residential Mobilerun Connect proxy for the device.
      - `id` string, uuid — Existing Mobilerun Connect proxy id; its credentials are fetched server-side.
    - `name` string
    - `smartIp` boolean
    - `socks5` SOCKS5
      - `host` string, required
      - `password` string, required
      - `port` integer, required
      - `user` string, required
  - `timezone` string

## Response `200`

OK

- DeviceInfo
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `activeTaskId` string, required
  - `assignedAt` string, date-time, nullable, required
  - `billingStrategy` string
  - `createdAt` string, date-time, required
  - `createdBy` string
  - `id` string, required
  - `name` string, required
  - `ownerId` string
  - `providerId` string
  - `state` string, required
  - `stateMessage` string, required
  - `streamToken` string
  - `streamUrl` string, required
  - `taskCount` integer, required
  - `terminatesAt` string, date-time, nullable, required
  - `type` string, required
  - `updatedAt` string, date-time, required
  - `userId` string — Deprecated: use ownerId/createdBy.

## Other responses

- `default` — Error

## Changes

- **2026-08-13** `02da4f9ce3fd` — 1 breaking, 2 info
  - removed the enum value `ios_simulator` from the `query` request parameter `deviceType`
  - added the new enum value `android_cloud_phone` to the `query` request parameter `deviceType`
  - added the new enum value `dedicated_physical_device` to the `query` request parameter `deviceType`
- **2026-08-01** `cd80ab1b29b0` — 1 info
  - endpoint added
- **2026-08-01** `3183ec3153d1` — 1 breaking
  - api path removed without deprecation
- **2026-07-24** `618bd1cc1aed` — 1 breaking, 1 info
  - removed the enum value `dedicated_physical_device` from the `query` request parameter `deviceType`
  - added the new optional request property `proxy/connect`
- **2026-07-09** `71a7f6cf59a1` — 1 info
  - added the new enum value `ios_simulator` to the `query` request parameter `deviceType`

[Full history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/devices/post.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) · [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/droidrun/droidrun-cloud/revisions/a1453ac769d4/schema)