Control Plane
The control plane is the Telnyx API athttps://api.telnyx.com. It is one endpoint for every region, and the only one that requires a Telnyx API key. It stops at the edge of a sandbox and never reaches inside one, so it answers 404 for a data-plane request.
The control plane serves these resources.
/v2/compute/sandboxlists and creates sandboxes./batchcreates many sandboxes at once./{sandbox_id}reads a sandbox and sets its tags./waitwaits for a pause or a terminate./connectresumes the sandbox and extends its lifetime./pause,/resume, and/terminatemove it between its states./timeoutsets its lifetime./forkcopies it into many sandboxes./snapshottakes and lists snapshots./{snapshot_id}reads and deletes a snapshot.
/networkchanges its outbound policy.
/templatelists and creates templates./{template_id}reads and deletes a template./rebuildrebuilds it.
/tokenissues a token.
/v2/compute/secretsholds the organization’s secrets.
Data Plane
Each region has its own data plane athttps://api.<region>.sandbox.telnyxcompute.com. It requires a token, never an API key. It stops at the edge of its region, serves only that region’s sandboxes, and issues no tokens.
The data plane serves these resources for its own region.
/v2/compute/sandbox/{sandbox_id}/execruns and lists execs, in a PTY when asked./{exec_id}reads an exec./attachstreams its output and writes its stdin./killsignals it./stdin/closecloses its stdin.
/attachwrites the main command’s stdin and returns its exit code./stdin/closecloses the main command’s stdin./logsreturns the main command’s logs./filesreads, writes, lists, and deletes files./renamerenames a file or directory.
/metricsreturns the sandbox’s resource usage./lifecycle_eventlists the sandbox’s lifecycle events.
/lifecycle_eventlists every sandbox’s lifecycle events.
https://<sandbox_id>-<port>.<region>.sandbox.telnyxcompute.com, for HTTP and WebSocket requests. Ports are public by default.
The line between acting on a sandbox and acting in it has two exceptions, both on the data plane.
- Management at the region. The data plane also accepts management requests for its own region, at the same paths as the control plane, so a client that holds a token can pause or resume a sandbox without the control plane.
- Records of a sandbox. Lifecycle events and metrics describe a sandbox from the outside, yet are read from the data plane, not the control plane, because each region keeps the record of its own sandboxes.