previews

Share a port of a sandbox at a public HTTPS address.

Creates the preview for this port, or changes its visibility and embedOrigins if it exists (so a retry is harmless). Returns the URL and, for a private preview, a signed token. WebSockets are supported. The server must listen on 0.0.0.0 or localhost inside the sandbox. embedOrigins limits which sites may show it in an iframe.

post/v1/sandboxes/{id}/previews

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/sandboxes/{id}/previews
  • Auth: HTTP bearer

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

portinteger required

The port inside the sandbox.

visibility'private' | 'public'

private (default): a token is needed. public: anyone with the address; only for an account with a kept top-up.

ttlSecondsinteger

The token's lifetime in seconds.

expiresAtstring date-time

An absolute private-token deadline, at least a minute and at most a week ahead. The token never outlives it.

embedOriginsstring[] nullable

The sites that may show this preview in an iframe, as origins: https://app.example.com, https://*.example.com for its subdomains, or http://localhost:3000. Up to 16. Any other site's iframe is refused, and a private link's token works in an iframe only on these. Omitted on a preview that exists: kept as it is. [] or null: any site (the default).

Response

Success

idstring
sandboxIdstring
portinteger
visibilitystring
urlstring

The address. A private preview also needs the token.

tokenstring nullable

Private previews: a token signed for this answer. Every create and read signs its own, each with its own tokenExpiresAt (a day unless ttlSeconds or expiresAt asks otherwise); tokens signed before keep working until their own expiry or a rotate. Null for a key that cannot run commands in the sandbox, such as a read-only key.

tokenExpiresAtstring date-time nullable

When this answer's token stops working. It is not stored on the preview: another read signs another token with its own expiry, and does not shorten or extend this one.

urlWithTokenstring nullable

Private previews: a link that carries the token once, for a browser.

disabledboolean

Turned off by Runtime after a report. Contact support.

embedOriginsstring[] nullable

The sites that may show it in an iframe; null for any site.

createdAtstring date-time
hintstring

How to share it, in one line.

Changes

No recorded changes to this operation across all 1 revision of this API.