Model Contracts

These contracts describe the Device Park public API request and response payloads used by the official SDKs. Java response models expose fields through record-style accessors such as device.serial() and allocation.allocationId().

Page

interface PageDto<T> {
  size: number;
  page: number;
  totalPages: number;
  totalElements: number;
  data: T[];
}

{
  "size": 20,
  "page": 0,
  "totalPages": 1,
  "totalElements": 1,
  "data": []
}

Device and Pool

interface Device {
  id: number | null;
  serial: string | null;
  marketName: string | null;
  model: string | null;
  manufacturer: string | null;
  platform: string | null;
  platformVersion: string | null;
  version: string | null;
  state: string | null;
  isSimulator: boolean | null;
  isPublic: boolean | null;
}

interface DeviceApp {
  id: number | null;
  bundleIdentifier: string | null;
  installedAt: string | null;
  updatedAt: string | null;
  isDefault: boolean | null;
}

interface Pool {
  id: string | null;
  name: string | null;
  isDefault: boolean | null;
}

interface CreatePoolRequest {
  name: string;
}

Device.state is represented as a string by the SDK. Use the documented API constants such as HEALTHY, ALLOCATED and RUNNING, not interface labels such as Online or Busy. See Device State Values for the complete list and meanings.

DeviceApp and ListDeviceAppsRequest are currently Node.js-only contracts. See List Device Apps for filters, pagination and response behavior.

isSimulator and isPublic were added to the Java and Node.js Device models for master parity. They remain nullable because older or environment-specific responses may omit them.

Pool.isDefault is also nullable response metadata. true means Device Park marks the pool as default, false means it does not and null means the response omitted the status. It is not an availability flag. Use pool.id as devicePoolId when creating an allocation. For default-only listing behavior, see Understanding isDefault.

CreatePoolRequest.name is required, must not be blank and must be unique within the authenticated account. Pool membership methods accept a non-empty list of device serials and return the serials present after the operation. See Manage Pools.

Allocation

Request:

interface DeviceAllocationRequest {
  serial?: string;
  manufacturer?: string;
  model?: string;
  platform?: string;
  platformVersion?: string;
  devicePoolId?: string;
  priority: number;
  removeApps: RemoveAppSelectionType;
}

Response:

interface Allocation {
  allocationId: string | null;
  deviceSerial: string | null;
  requestId: string | null;
  position: number | null;
  expiresAt: string | null;
}

{
  "allocationId": "allocation-123",
  "deviceSerial": null,
  "requestId": "request-456",
  "position": 2,
  "expiresAt": "2026-07-14T12:30:00Z"
}

priority defaults to 3 and accepts 1 through 5. removeApps defaults to NO_REMOVE; use REMOVE_WITHOUT_IS_DEFAULT_APPS to remove non-default applications before allocation. A null deviceSerial means the allocation response does not yet identify an assigned device. Keep the same allocationId while waiting.

Session

Request:

interface DeviceStartSessionRequest {
  allocationId: string;
  companyPoolId?: string;
  videoRecording?: boolean;
  userId: number;
  userEmail: string;
  companyId: number;
  companyName: string;
  customVideoRecordingPath?: string;
  appiumVersion?: string;
}

Device Park generates sessionId; it is present in the Session response and is not accepted as a Start Session request field.

Response:

interface Session {
  id: number | null;
  state: string | null;
  client: string | null;
  sessionId: string | null;
  allocationId: string | null;
  startDate: string | null;
  endDate: string | null;
  latestInteractionTime: string | null;
  userId: number | null;
  userEmail: string | null;
  companyId: number | null;
  companyName: string | null;
  deviceSerial: string | null;
  deviceName: string | null;
  deviceModel: string | null;
  deviceManufacturer: string | null;
  devicePlatform: string | null;
  deviceVersion: string | null;
  videoRecording: boolean | null;
  videoRecordUrl: string | null;
  appiumVersion: string | null;
  createdAt: string | null;
  updatedAt: string | null;
  dataAccessEndDate: string | null;
}

Session.state is represented as a string by the SDK. Use ACTIVE, CLOSING, CLOSED or FAILED_TO_CLOSE when filtering. See Session State Values for their meanings.

Application and Screen Record

interface Application {
  revision: number | null;
  sizeInBytes: number | null;
  version: string | null;
  fileKey: string | null;
  filePath: string | null;
  downloadUrl: string | null;
  createdAt: string | null;
}

interface ScreenRecord {
  fileKey: string | null;
  filePath: string | null;
  downloadUrl: string | null;
  createdAt: string | null;
  updatedAt: string | null;
  duration: number | null;
}

Download URLs can expire. Persist fileKey, not downloadUrl, when a stable application or recording identifier is required.

Each ScreenRecord describes one stored recording segment. The complete RFC 8216 HLS stream is exposed separately as Session.videoRecordUrl; it is not a field of ScreenRecord. See List Screen Records for readiness, authorization and browser playback guidance.

Published Constants

const SortDirection = {
  ASC: "ASC",
  DESC: "DESC"
} as const;

const SearchOperation = {
  EQUAL: "EQUAL",
  NOT_EQUAL: "NOT_EQUAL",
  GREATER_THAN: "GREATER_THAN",
  LESS_THAN: "LESS_THAN"
} as const;

const RemoveAppSelection = {
  NO_REMOVE: "NO_REMOVE",
  REMOVE_WITHOUT_IS_DEFAULT_APPS: "REMOVE_WITHOUT_IS_DEFAULT_APPS"
} as const;

Java exposes the same values as SortDirection, SearchOperation and RemoveAppSelection enums. Filter-key constants and compatibility are documented on each list-operation page and summarized in Pagination and Filtering.