> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt > Use this file to discover all available pages before exploring further. # Provision a new device > Requests a new device from the specification in the request body. Optional query parameters select the canonical device type, country, billing mode, and base profile. Returns the device, its resolved billing strategy, and its stream token. ## OpenAPI ````yaml /api-reference/phones.yaml post /devices openapi: 3.1.0 info: title: Phones version: v1 servers: - description: Droidrun Cloud API url: https://api.mobilerun.ai/v1 security: - bearerAuth: [] paths: /devices: post: tags: - Devices summary: Provision a new device description: >- Requests a new device from the specification in the request body. Optional query parameters select the canonical device type, country, billing mode, and base profile. Returns the device, its resolved billing strategy, and its stream token. operationId: create-device parameters: - description: >- Use android_cloud_phone for a cloud Android phone. Only canonical identifiers are accepted. Other backends are deployment-specific; recognized but unavailable types return DEVICE_TYPE_UNAVAILABLE (422). Retired dedicated_* aliases are rejected with a canonical replacement. example: android_cloud_phone explode: false in: query name: deviceType schema: description: >- Use android_cloud_phone for a cloud Android phone. Only canonical identifiers are accepted. Other backends are deployment-specific; recognized but unavailable types return DEVICE_TYPE_UNAVAILABLE (422). Retired dedicated_* aliases are rejected with a canonical replacement. examples: - android_cloud_phone type: string - description: >- ISO 3166-1 alpha-2 country code. If omitted the system picks the country with the most availability. explode: false in: query name: country schema: description: >- ISO 3166-1 alpha-2 country code. If omitted the system picks the country with the most availability. type: string - description: Profile ID to use as device spec explode: false in: query name: profileId schema: description: Profile ID to use as device spec type: string - description: >- 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. explode: false in: query name: billing schema: default: auto description: >- 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. enum: - auto - subscription - minute type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DeviceSpec' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/DeviceInfo' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: |- import Mobilerun from '@mobilerun/sdk'; const client = new Mobilerun({ apiKey: process.env['MOBILERUN_CLOUD_API_KEY'], // This is the default and can be omitted }); const device = await client.devices.create(); console.log(device.id); - lang: Python source: |- import os from mobilerun_sdk import Mobilerun client = Mobilerun( api_key=os.environ.get("MOBILERUN_CLOUD_API_KEY"), # This is the default and can be omitted ) device = client.devices.create() print(device.id) components: schemas: DeviceSpec: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://example.com/schemas/DeviceSpec.json format: uri readOnly: true type: string androidVersion: format: int64 type: integer apps: items: type: string type: - array - 'null' carrier: $ref: '#/components/schemas/DeviceCarrier' country: type: string files: items: type: string type: - array - 'null' identifiers: $ref: '#/components/schemas/DeviceIdentifiers' locale: type: string location: $ref: '#/components/schemas/Location' name: type: string proxy: $ref: '#/components/schemas/ProxyConfig1' timezone: type: string type: object DeviceInfo: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://example.com/schemas/DeviceInfo.json format: uri readOnly: true type: string activeTaskId: type: string assignedAt: format: date-time type: - string - 'null' billingStrategy: type: string createdAt: format: date-time type: string createdBy: type: string id: type: string name: type: string ownerId: type: string platform: description: Operating system the device runs. enum: - android - ios type: string providerId: type: string state: type: string stateMessage: type: string streamToken: type: string streamUrl: type: string taskCount: format: int64 type: integer terminatesAt: format: date-time type: - string - 'null' type: type: string updatedAt: format: date-time type: string userId: deprecated: true description: 'Deprecated: use ownerId/createdBy.' type: string required: - id - name - state - stateMessage - streamUrl - type - platform - createdAt - updatedAt - assignedAt - terminatesAt - taskCount - activeTaskId type: object ErrorModel: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://example.com/schemas/ErrorModel.json format: uri readOnly: true type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object DeviceCarrier: additionalProperties: false properties: GsmOperatorAlpha: type: string GsmOperatorNumeric: format: int64 type: integer GsmSimOperatorAlpha: type: string GsmSimOperatorIsoCountry: type: string GsmSimOperatorNumeric: format: int64 type: integer PersistSysTimezone: type: string required: - GsmOperatorAlpha - GsmOperatorNumeric - GsmSimOperatorAlpha - GsmSimOperatorNumeric - GsmSimOperatorIsoCountry - PersistSysTimezone type: object DeviceIdentifiers: additionalProperties: false properties: BootloaderSerialNumber: type: string IdentifierAndroidID: type: string IdentifierAppSetID: type: string IdentifierBluetoothMAC: type: string IdentifierGAID: type: string IdentifierGSFID: type: string IdentifierICCID: type: string IdentifierIMEI: type: string IdentifierIMSI: type: string IdentifierMEID: type: string IdentifierMediaDRMID: type: string IdentifierPhoneNumber: type: string IdentifierSerial: type: string IdentifierWifiMAC: type: string SerialNumber: type: string required: - IdentifierSerial - IdentifierAndroidID - IdentifierIMEI - IdentifierMEID - IdentifierIMSI - IdentifierICCID - IdentifierPhoneNumber - IdentifierGAID - IdentifierGSFID - IdentifierAppSetID - IdentifierMediaDRMID - IdentifierWifiMAC - IdentifierBluetoothMAC - SerialNumber - BootloaderSerialNumber type: object Location: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://example.com/schemas/Location.json format: uri readOnly: true type: string latitude: format: double type: number longitude: format: double type: number required: - latitude - longitude type: object ProxyConfig1: additionalProperties: false properties: connect: $ref: '#/components/schemas/Ref' name: type: string smartIp: type: boolean socks5: $ref: '#/components/schemas/SOCKS5' type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Ref: additionalProperties: false properties: country: description: >- ISO 3166-1 alpha-2 country code; provisions (or reuses) a rotating residential Mobilerun Connect proxy for the device. pattern: ^[a-zA-Z]{2}$ type: string id: description: >- Existing Mobilerun Connect proxy id; its credentials are fetched server-side. format: uuid type: string type: object SOCKS5: additionalProperties: false properties: host: type: string password: type: string port: format: int64 type: integer user: type: string required: - host - port - user - password type: object securitySchemes: bearerAuth: bearerFormat: Opaque description: Bearer token via Authorization header scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.