Sessions API

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.

Whose session. A session belongs to the member who started it. Every endpoint below that acts on a session or shows what is on it (start, control, install, launch, uninstall, list installed apps, /agent/tools, presence, and AI test or suite runs against it) answers 403 to other members of your organization. Organization admins may act on any session in the organization. A teammate the owner has sent a collaboration link can act on that session within the link’s role by sending the link’s token (the part after /collab/) in an X-Collab-Token header alongside their own credentials: View only allows screenshots, the UI tree, logs and the installed-apps list; Can control allows everything except opening links. GET /sessions/{id} stays readable to every member, but it leaves out worker_stream_url for anyone who can’t watch the session and tunnel_url for anyone who can’t control it. Only the owner or an admin can stop a session. Sessions started from a share link or an embed key work differently: every member can watch them, only Developers and Admins can control them, and only the link’s or key’s creator (as a Developer or Admin) or an admin can stop one. See Team.

Session lifetime. A session stays up while something holds it (a browser tab, vibeview dev, the MCP server, API calls, or a test run) and someone is using it. Use is an action on the device: /control, /install-app, /install-build, /launch-app, uninstalling an app, the debug endpoints, /agent/tools calls that drive the device (taps, swipes, typing, buttons, opening links, rotating, relaunching the app, and so on), test steps, app reloads from vibeview dev, and speaking into the microphone. POST /sessions/{id}/presence and the /agent/tools reads (ui_tree, screenshot, logs, find_element and wait) only show that a client is there: they keep a session held but are not use. GET /sessions/{id} is neither: it doesn’t hold a session, so a script that only watches a session should poll POST /sessions/{id}/presence instead. A session nobody uses ends after your organization’s idle timeout (Settings › Session defaults; 15 minutes by default, and never less than five minutes for a session with no browser tab open), whatever holds it. A session that was started but never reached by any client is ended a few minutes after it comes up. A session held by vibeview dev (in the foreground or with --detach) or by the MCP server’s dev_start also ends within about 90 seconds once that process stops checking in (it was killed or crashed, or the computer went to sleep), unless a browser tab or a test run is still holding it. From about a minute before an idle end, the session’s responses carry idle_warning (about a minute before the end; see Session Timeout).

Create Session

POST /api/v1/sessions/

Auth: Bearer token required.

Request body:

Response: A session object with status: "pending" and no device yet.

Errors:

• 400 — app_id is an app for another platform than device_type (for example an iOS app on an android session), or specific_device_id is a device of another platform. A TV app (Apple TV, Android TV) on a phone or tablet, or a phone app on a TV, is refused the same way, whether the device is named or asked for with device_category. The message names both.
• 404 — Specific device not found.
• 409 — Specific device is not available.
• 410 — build_id is a build of app_id that has expired under your plan’s build retention. detail.error is build_expired; message and newer_build_id name the app’s newest build that hasn’t expired (see Build retention). The session isn’t created, and the latest build is never installed instead.
• 422 — model or os_version matches no device (or os_version is ambiguous). The message lists the valid values.

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):

Without device_id, the session starts on the specific_device_id it was created with, if any. Otherwise any free device matching the session’s device_type and device_category (or its model and os_version, if you created it with them) is used.

Response: A session object with status updated to starting and the device fields filled in.

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

{
  "status": "queued",
  "queue_entry_id": 42,
  "position": 2,
  "priority": "low",
  "session_id": "uuid-string",
  "queue_reason": "devices_busy"
}

priority is high on paid plans and low on Free. When every device is busy, paid plans’ requests start first, so a Free request’s position can go up.

queue_reason says why the session is waiting, or is null when that can’t be told:

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

Errors:

• 400 — Session already started, or device_id is a device of another platform than the session’s.
• 404 — Session not found, or no device has that device_id.

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: A session object.

Session Object

Every endpoint that returns a session uses this shape. Fields that don’t apply yet (for example the device fields before the session starts) are null.

{
  "id": 1,
  "session_id": "uuid-string",
  "device_type": "ios",
  "device_category": "phone",
  "status": "active",
  "device_id": 42,
  "device_name": "iPhone 16",
  "device_udid": "ABCD1234-...",
  "device_model": "iPhone 16",
  "os_version": "iOS 18.0",
  "user_email": "dev@example.com",
  "origin": "user",
  "worker_stream_url": "wss://...",
  "tunnel_url": null,
  "start_time": "2026-09-25T10:00:00",
  "end_time": null,
  "duration_minutes": null,
  "failure_reason": null,
  "end_reason_code": null,
  "idle_timeout_s": null,
  "warnings": null,
  "pinned_install_dispatched": true,
  "pinned_install_confirmed": true,
  "app_installed_at": null,
  "app_install_pending": false,
  "idle_warning": null,
  "pinned_app_public_id": "my-app-x7k2",
  "pinned_app_name": "My App",
  "pinned_build_id": null,
  "app_sdk_version": "18.0",
  "device_capabilities": { "appearance": true, "textSizeSteps": 12, "...": "..." },
  "posture": null,
  "form_factor": null,
  "display_metrics": { "chrome": "phone13", "scale": 3, "screen": { "width": 390, "height": 844 }, "corners": { "ul": 47.33, "ur": 47.33, "ll": 47.33, "lr": 47.33 } },
  "embed_app_ready": false,
  "embed_app_readiness_revision": 0
}

status: "active" and app_build_id alone do not prove installation succeeded: the build identifies the intended pinned or resolved build. Check pinned_install_confirmed together with session state and the selected app/build identity. A true acknowledgement does not establish foreground readiness or track later manual app changes. Roku still uses app_installed_at and app_install_pending for its post-activation installation.

List Sessions

GET /api/v1/sessions/

Auth: Bearer token required.

Query parameters:

Response: Array of session objects, newest first, each with these extra fields:

Run a Test on a Session

Run a saved test, or every test of a group, on a session you already have, for example the one you are driving on the Devices page or from a coding agent. The call returns at once; open run_url, or poll the run, to follow it. To run on devices of their own, use Start a run instead.

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

Auth: Bearer token required. Developer role or above.

Pass test_id or group_id, not both.

Response:

{
  "kind": "test_run",
  "run_id": 42,
  "run_public_id": "tr_abc123",
  "run_url": "https://vibeview.io/tests/runs/tr_abc123",
  "status": "started"
}

kind is suite_run for a group. Starting a run counts as use of the session, and the run’s steps keep it in use while they run.

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. It takes the same filters as List Sessions (except limit and offset); with none, it exports every session.

The columns are session_id, user_id, device_type, status, start_time, end_time and duration_minutes, then user_email, who, source, source_label, app, app_platform, build_version, device, os_version and end_reason.

On share-link and embed rows, user_id and user_email are the owner of the link or embed, not the visitor; who is Visitor.

Control Session

Send input commands to the running simulator.

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

Auth: Bearer token required.

Request body:

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

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:

Errors:

• 400 — The build is of an app for another platform than the session’s device, or for a TV when the device is a phone or tablet (or the reverse). The message lists your newest builds that run on this device.
• 404 — Your organization has no such build. The message lists the session’s app’s newest builds (or, for a session with no app, your newest builds that run on this device).
• 410 — The build has expired under your plan’s build retention: detail.error is build_expired, with message and newer_build_id (see Build retention). Nothing is installed.

Launch App

Launch an already-installed app on the device.

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

Auth: Bearer token required.

Request body:

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"
}