# Remote Dev Environments API

The Remote Dev Environments REST API lets you manage sessions, templates, and saved inputs programmatically, and report on what the workspace's active sessions consume. It's the same API that the CLI, the web UI, and the MCP server use.

:::warning[Experimental API]

The RDE API is experimental. Although it's versioned, endpoints and payloads can change in backwards-incompatible ways without notice. Pin your integrations to a known-good behavior and expect to update them.

:::

## Base URL

The API is served at:

```text
https://api.bitrise.io/rde
```

## Authentication

Authenticate with a Bitrise [personal access token](https://app.bitrise.io/me/account/security), sent in the `Authorization` header:

```text
Authorization: token YOUR_BITRISE_PAT
```

## Workspace usage report

The usage endpoint returns a point-in-time snapshot of the workspace's active sessions: session counts and vCPU and memory totals split by OS, workspace-wide and per user. It reports what the sessions consume right now — it's not a historical or billing-period report.

```text
GET /v1/workspaces/{workspace_id}/usage
```

Unlike the other endpoints, this one requires billing visibility: workspace owners and members with a billing-managing custom role can call it. Other members get a `403` response.

## Warm pools

The warm pool endpoints manage pools of pre-booted sessions, and the create session and create preview link requests claim from them with `warm_pool_id`:

```text
GET    /v1/workspaces/{workspace_id}/warm-pools
POST   /v1/workspaces/{workspace_id}/warm-pools
GET    /v1/workspaces/{workspace_id}/warm-pools/{warm_pool_id}
PATCH  /v1/workspaces/{workspace_id}/warm-pools/{warm_pool_id}
DELETE /v1/workspaces/{workspace_id}/warm-pools/{warm_pool_id}
POST   /v1/workspaces/{workspace_id}/warm-pools/{warm_pool_id}/retry
```

A pool's `status` reports how many sessions are ready and warming, the warm sessions themselves, and any configuration error. The `retry` request starts a pool warming again after it stopped because **On create** failed three times in a row. See [Warm pools](/bitrise-rde/configuration/warm-pools).

## Lifecycle hooks

Templates carry their setup scripts in the `hooks` object, and every session read reports its setup phase and hook runs in the `lifecycle` field. Two endpoints run a failed setup again, and one reads a hook's log:

```text
POST /v1/workspaces/{workspace_id}/sessions/{session_id}/hook-runs
POST /v1/workspaces/{workspace_id}/sessions/{session_id}/rebuild
GET  /v1/workspaces/{workspace_id}/sessions/{session_id}/logs/{stage}
```

See [Lifecycle hooks](/bitrise-rde/configuration/lifecycle-hooks#managing-hooks-from-the-cli-an-ai-agent-or-the-api).

## Device sessions

Include a `device_spec` in the create session request to boot an iOS simulator or Android emulator with the session, and an `artifact` to install an app build on it. The `device` field on every session read reports the device's state and the install status. See [Device sessions](/bitrise-rde/devices/device-sessions).

## Device preview links

The preview link endpoint mints a shareable link that opens an app build on a device in the recipient's browser, without a Bitrise login:

```text
POST /v1/workspaces/{workspace_id}/preview-links
```

Unlike the other endpoints, it also accepts a [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) created with **Remote Dev Environments** access, which is what a CI pipeline should use. See [Device preview links](/bitrise-rde/devices/device-preview-links).

## Reference

For the full list of endpoints, request and response schemas, and examples, see the interactive API reference:

[Remote Dev Environments API reference](/bitrise-rde-api/api-reference/bitrise-remote-dev-environments-api)