---
title: "Create a device (charged to the account of the API key)"
method: POST
path: "/devices"
tags: ["Devices"]
---

# Create a device (charged to the account of the API key)

`POST /devices`

## Request

- Base URL: `https://api.clousd.com/v1`
- URL: `https://api.clousd.com/v1/devices`
- Auth: HTTP bearer

One device per call. The account is charged as in the dashboard (creation fee, plus the first month for plan monthly); a paid network exit (mobile, residential, isp, datacenter) is metered per GB. Idempotency-Key (header, or idempotency_key / name in the body) is required - a retry with the same key within 10 minutes returns the same answer and is not charged twice. The device boots in one to three minutes: poll GET /devices/{name}.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `profile` string, required: model id from GET /models
  - `network` object
    - `type` string
    - `country` string: ISO-2 for paid exits
    - `url` string: socks5:// or http:// for byo
  - `plan` 'metered' | 'monthly'
  - `region` string: where the device itself runs (ISO-2); default - the exit country
  - `burner` boolean: disposable - stopping deletes it
  - `idempotency_key` string

## Response `202`

Creating

- object
  - `ok` boolean
  - `name` string
  - `ext_id` string
  - `state` 'starting'
  - `poll` string
  - `charged_cents` integer
  - `android` string

## Other responses

- `400`: bad_profile | bad_network | bad_request
- `402`: insufficient_funds - add funds in the dashboard
- `403`: only account API keys can create devices
- `409`: limit (50 devices per account) | processing (same Idempotency-Key still running)
- `502`: the device service did not answer - nothing was charged

---

[API](https://skmtc.dev/clousd/apis/clousd-api.md) · [All operations](https://skmtc.dev/clousd/apis/clousd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clousd/apis/clousd-api/revisions/0291ffd26ae3?raw)