Ephemeral PhoneOpen console

Docs · API

Control API

A small bearer-authenticated HTTP API for phone lifecycle, runtime capabilities, audit events, and short-lived connection tickets.

Authentication

Self-hosted requests use Authorization: Bearer <EPHEMERAL_ADMIN_TOKEN>. Keep that token out of URLs, client bundles, logs, and source control.

curl http://localhost:8080/api/v1/phones \
  -H "Authorization: Bearer $EPHEMERAL_ADMIN_TOKEN"

Download the OpenAPI 3.1 document.

Phones

  • GET /api/v1/phones — list phone instances.
  • POST /api/v1/phones — create an instance.
  • GET /api/v1/phones/{phoneId} — read one instance.
  • DELETE /api/v1/phones/{phoneId} — delete it and its provider resources.
curl -X POST http://localhost:8080/api/v1/phones \
  -H "Authorization: Bearer $EPHEMERAL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"personal","mode":"persistent","cpu":4,"memory_mib":4096,"storage_gib":64}'

Lifecycle actions

  • POST /api/v1/phones/{phoneId}/start
  • POST /api/v1/phones/{phoneId}/stop
  • POST /api/v1/phones/{phoneId}/lock
  • POST /api/v1/phones/{phoneId}/snapshot
  • POST /api/v1/phones/{phoneId}/connect — returns a short-lived stream ticket.
A phone's reported locked lifecycle state is not a universal proof that every runtime path is inaccessible. Treat runtime and provider enforcement as part of your deployment's security boundary.

Capabilities and events

  • GET /healthz — unauthenticated liveness check.
  • GET /api/v1/capabilities — runtime provider features.
  • GET /api/v1/events?limit=100 — recent lifecycle audit events.

Hosted gateway

The public Vercel app does not expose the admin bearer token. A GitHub-authenticated server function maps the signed user session to an owner-specific backend token and proxies only an explicit allowlist of API operations. The hosted gateway is an application boundary, not a general API proxy.