# Devices

## List devices in a session[​](#list-devices "Direct link to List devices in a session")

GET/api/v1/sessions/{sessionId}/devices

Devices attached to the session, newest first. Visible to every member of the organization that owns the session.

Path parameters

`sessionId`string · uuidrequired

Session UUID

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

`object`stringrequired

`data`arrayrequired

Show child attributes

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

`nextCursor`stringnullable

Cursor for the next page; absent when there are no more results

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/devices \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401403404

Devices attached to the session

```
{

  "object": "list",

  "data": [

    {

      "id": "string",

      "status": "provisioning",

      "info": {

        "platform": "ios",

        "type": "real",

        "name": "string",

        "osVersion": "string",

        "serial": "00008150-001C30842678401C"

      },

      "createdAt": "2026-01-01T00:00:00Z",

      "releasedAt": "2026-01-01T00:00:00Z"

    }

  ],

  "nextCursor": "string"

}
```

## Allocate a device[​](#allocate-device "Direct link to Allocate a device")

POST/api/v1/sessions/{sessionId}/devices

Allocates a device matching the given filters and attaches it to the session. Uses the same filter DSL as the fleet.allocate RPC. Allocation is asynchronous: the device is returned immediately with status "provisioning" or "queued" and becomes usable once its status is "ready". Poll GET /sessions/{sessionId}/devices/{deviceId} to observe readiness.

Path parameters

`sessionId`string · uuidrequired

Session UUID

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Body parameters

`filters`arrayrequired

Show child attributes

`attribute`stringrequired

`operator`stringrequired

Allowed operators depend on the attribute: platform and type accept only EQUALS; name accepts EQUALS, STARTS\_WITH, CONTAINS; version accepts EQUALS and the comparison operators.

`value`stringrequired

Must be non-empty. For platform: 'ios' or 'android'. For type: 'real'.

Returns

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/devices \

  -X POST \

  -H 'Authorization: Bearer mob_...' \

  -H 'Content-Type: application/json' \

  -d '{"filters":[{"attribute":"platform","operator":"EQUALS","value":"ios"}]}'
```

Response

201400401403404409

Device allocated; provisioning has started

```
{

  "id": "string",

  "status": "provisioning",

  "info": {

    "platform": "ios",

    "type": "real",

    "name": "string",

    "osVersion": "string",

    "serial": "00008150-001C30842678401C"

  },

  "createdAt": "2026-01-01T00:00:00Z",

  "releasedAt": "2026-01-01T00:00:00Z"

}
```

## Get a device[​](#get-device "Direct link to Get a device")

GET/api/v1/sessions/{sessionId}/devices/{deviceId}

Returns a device attached to the session. Visible to every member of the organization that owns the session.

Path parameters

`sessionId`string · uuidrequired

Session UUID

`deviceId`stringrequired

The physical device's own id, as returned in SessionDevice.info.serial — a UDID on iOS, a serial on Android. Not the allocation id (SessionDevice.id).

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/devices/{deviceId} \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401403404

Device detail

```
{

  "id": "string",

  "status": "provisioning",

  "info": {

    "platform": "ios",

    "type": "real",

    "name": "string",

    "osVersion": "string",

    "serial": "00008150-001C30842678401C"

  },

  "createdAt": "2026-01-01T00:00:00Z",

  "releasedAt": "2026-01-01T00:00:00Z"

}
```

## Release a device[​](#release-device "Direct link to Release a device")

POST/api/v1/sessions/{sessionId}/devices/{deviceId}/release

Releases a device, stopping billing and returning it to the fleet. Returns the device with its updated status. Idempotent: releasing an already-released device is a no-op.

Path parameters

`sessionId`string · uuidrequired

Session UUID

`deviceId`stringrequired

The physical device's own id, as returned in SessionDevice.info.serial — a UDID on iOS, a serial on Android. Not the allocation id (SessionDevice.id).

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/devices/{deviceId}/release \

  -X POST \

  -H 'Authorization: Bearer mob_...'
```

Response

202401403404

Release accepted; teardown proceeds asynchronously

```
{

  "id": "string",

  "status": "provisioning",

  "info": {

    "platform": "ios",

    "type": "real",

    "name": "string",

    "osVersion": "string",

    "serial": "00008150-001C30842678401C"

  },

  "createdAt": "2026-01-01T00:00:00Z",

  "releasedAt": "2026-01-01T00:00:00Z"

}
```