Sessions API: Create, Control, Install

Create, start, stop and control simulator sessions, install apps or builds on a live device, and export session history as CSV.

These endpoints create and control simulator sessions, install apps on a live device, and read session history. Authentication, error shapes and rate limits are covered in the REST API overview.

Sessions represent live simulator/emulator instances. The lifecycle is: create -> start -> use -> stop.

Session lifetime. An active session stays up while something is using it: a browser tab connected to it, a vibeview dev connection, or API calls that act on the device (/control, /install-app, /install-build, /launch-app, /agent/tools). A session driven only through the API ends when it has had no such call for your organization’s idle timeout (Settings › Session defaults; 30 minutes by default, and never less than five minutes). A session that was started but never used by any of these is ended a few minutes after it comes up. Polling GET /sessions/{id} does not count as use.

Create Session

POST /api/v1/sessions/

Auth: Bearer token required.

Request body:

Field	Type	Required	Description
`device_type`	string	Yes	`ios` or `android`
`device_category`	string	No	`phone`, `tablet`, or `tv`. Omit for any handheld.
`specific_device_id`	string	No	Request a specific device by its UUID
`app_id`	string	No	Public id of an app to install before the session becomes usable
`build_id`	int	No	Install this exact build of `app_id` instead of the latest
`launch_params`	object	No	Flat JSON object applied when the pinned app launches. Ignored without a resolvable `app_id`.

Response:

{
  "id": 1,
  "session_id": "uuid-string",
  "device_type": "ios",
  "device_category": "phone",
  "status": "pending",
  "device_id": null,
  "device_name": null,
  "os_version": null,
  "user_email": null,
  "webrtc_room_id": null,
  "stream_url": null,
  "start_time": null,
  "end_time": null,
  "duration_minutes": null
}

Note: webrtc_room_id is deprecated and always null. It will be removed in a future API version.

Errors:

404 — Specific device not found.
409 — Specific device is not available.

Start Session

Boot the simulator and begin streaming. Must be called after creating a session.

POST /api/v1/sessions/{session_id}/start

Auth: Bearer token required.

Request body (optional):

Field	Type	Required	Description
`device_id`	string	No	Specific device UUID to use

Response: Same shape as the create response, with status updated to starting and device fields populated.

If no matching device is free, the request returns 202 Accepted and the session is queued:

{
  "status": "queued",
  "queue_entry_id": 42,
  "position": 2,
  "session_id": "uuid-string"
}

The session starts automatically when a device frees up. Use the queue endpoints below to leave the queue.

Errors:

400 — Session already started.
404 — Session not found.

Leave Device Queue

Remove a queued session start from the device queue. Two equivalent forms are provided; the POST variant exists for navigator.sendBeacon compatibility (leaving the queue on page unload).

DELETE /api/v1/sessions/queue/{queue_entry_id}
POST   /api/v1/sessions/queue/{queue_entry_id}/leave

Auth: Bearer token required. Only the user who queued the entry can remove it.

queue_entry_id is the integer returned in the 202 queued response from Start Session.

Response:

{
  "status": "ok"
}

Errors:

404 — Queue entry not found or already processed.

Get Session

GET /api/v1/sessions/{session_id}

Auth: Bearer token required.

Response: Session object.

List Sessions

GET /api/v1/sessions/

Auth: Bearer token required.

Query parameters:

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `starting`, `active`, `stopped`, `failed`
`device_type`	string	Filter by `ios` or `android`
`user_id`	int	Filter by user ID
`time_range`	string	One of `last-hour`, `last-day`, `last-week`, `last-month`
`search`	string	Search filter
`limit`	int	Max results (default 50, max 200)
`offset`	int	Pagination offset (default 0)

Response: Array of session objects.

Stop Session

Stop the simulator and release the device.

DELETE /api/v1/sessions/{session_id}

Auth: Bearer token required.

Response:

{
  "status": "ok"
}

Export Sessions (CSV)

GET /api/v1/sessions/export/csv

Auth: Bearer token required.

Returns a CSV file download with session history.

Control Session

Send input commands to the running simulator.

POST /api/v1/sessions/{session_id}/control

Auth: Bearer token required.

Request body:

Field	Type	Required	Description
`action`	string	Yes	One of: `tap`, `swipe`, `rotate`, `button`, `key`, `screenshot`, `touch_start`, `touch_move`, `touch_end`
`x`	float	No	X coordinate in pixels of the streamed video (0 - 10000)
`y`	float	No	Y coordinate in pixels of the streamed video (0 - 10000)
`x2`	float	No	End X coordinate in pixels (for swipe)
`y2`	float	No	End Y coordinate in pixels (for swipe)
`duration`	int	No	Duration in milliseconds
`rotation`	int	No	Rotation angle: `0`, `90`, `180`, `270`
`button`	string	No	iOS button: `HOME`, `LOCK`, `SIRI`
`keycode`	string	No	Android keycode: `BACK`, `HOME`, `MENU`, `DPAD_UP`, etc.

Response:

{
  "status": "ok"
}

Install App (Upload)

Upload and install an app binary directly into the running session.

POST /api/v1/sessions/{session_id}/install-app

Auth: Bearer token required.

Request: multipart/form-data

Field	Type	Required	Description
`file`	file	Yes	App binary (.zip/.tar.gz/.tgz iOS simulator bundle, .apk for Android)
`launch_after_install`	boolean	No	Launch app after install (default: false)

Install Build

Install an app from an existing build record (no file upload needed).

POST /api/v1/sessions/{session_id}/install-build

Auth: Bearer token required.

Request body:

Field	Type	Required	Description
`build_id`	int	Yes	ID of the build to install
`launch_after_install`	boolean	No	Launch app after install (default: true)
`grant_permissions`	boolean	No	Auto-grant permissions (default: true)
`params`	object	No	Flat JSON object applied when the app launches

Launch App

Launch an already-installed app on the device.

POST /api/v1/sessions/{session_id}/launch-app

Auth: Bearer token required.

Request body:

Field	Type	Required	Description
`package_name`	string	Yes	App package identifier
`activity_name`	string	No	Android activity to launch
`params`	object	No	Flat JSON object applied when the app launches

List Installed Apps

Request the list of installed apps on the device. The result is delivered asynchronously via WebSocket.

GET /api/v1/sessions/{session_id}/apps

Auth: Bearer token required.

Uninstall App

DELETE /api/v1/sessions/{session_id}/apps/{package_name}

Auth: Bearer token required.

Response:

{
  "status": "ok",
  "message": "Uninstalling com.example.myapp"
}