Menu
Platform
AI
App store purchases
Database
Flags
Jobs and cron
Localization
Monitoring
Notifications
Payments
Queues
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Acquire control on a lease
Takes exclusive input control of a lease's display.
Takes exclusive input control of a lease's display. A HUMAN acquire preempts an AGENT holder and returns a controller stream; an AGENT acquire is refused CONTROL_HELD_BY_HUMAN while a human holds control. Control lapses at ttl, which the platform caps at 30 minutes.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:acquireControl - Scope
sandboxes:exec - Effect
write— a successful call changes state. - Collection leases
#Request
| Field | Type | What it is |
|---|---|---|
name | string | The name of the lease. Required. |
holder | ControlHolder | HUMAN or AGENT. Required. One of agent, human. |
ttl | duration | How long; default 10 minutes, capped at 30 minutes. |
holder_label | string | A label for the holder, for example the person's user id; recorded in the audit events. |
preempt | bool | For HUMAN: take control from another human. |
#Response
| Field | Type | What it is |
|---|---|---|
control | ControlState | The control now held. |
stream | StreamSession | For HUMAN: the controller stream bound to this epoch. |
#ControlState
| Field | Type | What it is |
|---|---|---|
holder | ControlHolder | Who holds control; UNSPECIFIED when nobody does (agent actions allowed). Output only. One of agent, human. |
epoch | int64 | Increases on every acquire; release names it. Output only. |
principal | string | The Access principal that acquired control. Output only. |
holder_label | string | The caller's label for the person or agent, for example a user id. Output only. |
acquire_time | timestamp | When control was acquired. Output only. |
expire_time | timestamp | When control lapses unless re-acquired. Output only. |
#StreamSession
| Field | Type | What it is |
|---|---|---|
role | StreamRole | VIEWER (frames) or CONTROLLER (frames and input). One of viewer, controller. |
token | string | The stream token. Never returned again. |
viewer_uri | string | An embeddable page (web, Telegram Mini App webview) that connects on load; the token rides in the URL fragment and never reaches a server log. Never returned again. |
signaling_uri | string | The WebRTC signaling WebSocket; send the token as the first message. |
ice_servers | IceServer[] | ICE servers, TURN credentials included, valid until expire_time. |
vnc_uri | string | The noVNC/websockify fallback WebSocket for networks that block WebRTC. |
expire_time | timestamp | When the token stops admitting new connections. |
lease_generation | int64 | The lease generation the token is bound to. |
control_epoch | int64 | For CONTROLLER: the control epoch the token is bound to. |
revoke_uri | string | Revokes the token early: POST it with the token as bearer. |
#IceServer
| Field | Type | What it is |
|---|---|---|
urls | string[] | stun:, turn:, or turns: URLs. |
username | string | The TURN username. |
credential | string | The TURN credential. Never returned again. |
#Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.INVALID_FIELD— A field failed validation.INVALID_STATE— The Resource is in a state that forbids the call.CONTROL_HELD— Another holder has input control of the display.CONTROL_HELD_BY_HUMAN— A human has taken over the display; agent input and screenshots are refused until control is released or expires.
Every error arrives in the body Errors describes.
#Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:acquireControl" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"holder":"agent"}'