Create device preview link

POST 
/v1/workspaces/:workspaceId/preview-links

Turns an app build into a shareable URL that opens the app on a live Android emulator or iOS simulator in the recipient's browser — no Bitrise login, no local tooling, nothing to install. The usual shape is a CI step that builds a simulator/emulator app and posts the link on the pull request, so reviewers can try the change before merging.

Authentication

Unlike the rest of this API, this endpoint accepts a Workspace API Token (bitwat_…, created with Remote Dev Environments access) as well as a Personal Access Token — the workspace token is what a CI pipeline should carry, since it belongs to no one person. Devices opened from a PAT-minted link are sessions owned by that user; devices from a workspace-token link are owned by the workspace and are visible to every workspace member. GET /v1/workspaces/{workspace_id}/stacks and /machine-types take a workspace token too, so a CI step can check stack_id / machine_type values before minting.

Nothing is stored

The signed token in the response is the only artifact — no row is written, and a link nobody opens costs nothing. Every open spawns its own device session, so one link serves many reviewers at once.

The app build

artifact.url must be an absolute http(s) URL that a plain anonymous GET can fetch; a presigned URL is fine, and the URL is never echoed back to viewers. It must be a simulator/emulator build, not a device build — iOS wants a zipped .app carrying an arm64 simulator slice, Android an .apk that runs on x86_64. A device-signed build installs on neither.

Lifetime and limits

ttl_seconds defaults to 24 hours and is capped at 72 hours. There is no revocation list, so a short lifetime is the control: treat the link as a bearer credential, because anyone holding the URL can open a device. Sessions a link spawns are capped at 5 alive per link and 20 per workspace — opens past the cap are refused with ResourceExhausted — and each one auto-terminates after its idle window (session_auto_terminate_minutes, at least 10, default 60).

Request

Responses

200

A successful response.