Skip to content

Media

Media in Port OS represents content that can be played on devices, like:

  • Music
  • Movies and TV shows
  • Podcasts
  • Alarms

Get media relay credentials

View source specification ↗
GET /relay-credentials

Issues short-lived TURN credentials for the Port OS media relay to the authenticated principal. Use them as ICE servers when a WebRTC peer, such as port message record, cannot reach a camera or robot directly. The relay accepts TCP only, relays to public IPv4 peers only, and limits concurrent allocations per principal. Each call mints new credentials and stores nothing, so the response is never cached. Credentials stop working at expiresAt.

Required scope

Any authenticated access token

Returns

200

Relay credentials issued

Fields
iceServersarray<RelayIceServer>Required

ICE servers to add to a WebRTC peer configuration.

One TURN server with its time-limited username and credential.

urlsarray<string>Required

TURN URLs. The relay accepts TCP only.

usernamestringRequired

TURN username, `<unix-expiry>:<subject>`.

credentialstringRequired

TURN password for the username. Treat it as a secret until it expires.

expiresAtstringRequired

When the credentials stop working.

format: "date-time"

Response headers
Cache-Controlstring

Always `no-store`; the response carries a credential.

Errors

401 UNAUTHORIZED

Unauthorized

Obtain a valid access token, then retry.

500 INTERNAL

Internal server error

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.

503 SERVICE_UNAVAILABLE

This deployment runs no media relay

Wait for the provider or bridge to recover, then retry safely with backoff.

Tunnel to the media relay over a WebSocket

View source specification ↗
GET /relay-tunnel

Upgrades an authenticated GET to a WebSocket that carries the caller's TURN-over-TCP stream to the Port OS media relay. Use it on networks that pass only HTTPS through a TLS-intercepting proxy, such as an agent sandbox. Send the TURN stream as binary messages and read the relay's replies from binary messages; message boundaries carry no meaning, and a text message ends the tunnel. The relay still authenticates every allocation with credentials from GET /relay-credentials. The tunnel reaches only the deployment's relay, and it closes when either side ends.

Required scope

Any authenticated access token

Returns

101

Connection upgraded; the WebSocket now carries the TURN stream

No response body.

Errors

400 BAD_REQUEST

The request is not a WebSocket upgrade

Check the request fields and any validation details, then correct the payload.

401 UNAUTHORIZED

Unauthorized

Obtain a valid access token, then retry.

503 SERVICE_UNAVAILABLE

This deployment runs no media relay, or the relay could not be reached

Wait for the provider or bridge to recover, then retry safely with backoff.