Skip to content

Preview API reference

A port of a sandbox at a public HTTPS address: private with a signed token, or public.

Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.

Its states: making, ready, deleted.

Updated .md

Endpoints#

Method Path Description
POST /v2/sandboxes/{id}/previews Create a preview
GET /v2/previews List previews
GET /v2/previews/{name} Get a preview
POST /v2/previews/{name}:sign sign
POST /v2/previews/{name}:rotate rotate
DELETE /v2/previews/{name} Delete a preview

Create a preview#

POST /v2/sandboxes/{id}/previews

Shares a port of a sandbox at an HTTPS address and returns its url and, for a private one, a token; or changes its visibility and sites when it is shared. Asked again, the same preview.

Its action, for a key's grant: previews:create.

Path: id.

Body: a PreviewCreate.

Returns a Preview.

In v1: POST /v1/sandboxes/{id}/previews.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/sandboxes/PREVIEW_ID/previews" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "port": 3000 }'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.previews.create("PREVIEW_ID", { port: 3000 });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.previews.create("PREVIEW_ID", port=3000)
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.previews.create("PREVIEW_ID", port: 3000)
Terminalruntime previews create PREVIEW_ID --port 3000
JSON{ "method": "tools/call", "params": { "name": "runtime_sandboxes_previews_create", "arguments": { "id": "PREVIEW_ID", "port": 3000 } } }

List previews#

GET /v2/previews

Lists a sandbox's previews, lowest port first.

Its action, for a key's grant: previews:list.

Query:

Field Type Required Description
sandboxId string Yes The sandbox whose previews to list.
cursor string No Where the page starts: a page's next.
limit integer No The most items the page holds. At least 1. At most 200. Default: 50.

Returns a page: items, each a Preview, and next, where the next page starts, none on the last.

In v1: GET /v1/sandboxes/{id}/previews.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/previews?sandboxId=SANDBOX_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.previews.list({ sandboxId: "SANDBOX_ID" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.previews.list(sandbox_id="SANDBOX_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.previews.list(sandbox_id: "SANDBOX_ID")
Terminalruntime previews list --sandbox-id SANDBOX_ID
JSON{ "method": "tools/call", "params": { "name": "runtime_sandboxes_previews_list", "arguments": { "sandboxId": "SANDBOX_ID" } } }

Get a preview#

GET /v2/previews/{name}

Returns a preview; sign returns one with a token.

Its action, for a key's grant: previews:get.

Path: name.

Returns a Preview.

In v1: GET /v1/sandboxes/{id}/previews/{port}.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/previews/example" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.previews.get("example");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.previews.get("example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.previews.get("example")
Terminalruntime previews get example

sign#

POST /v2/previews/{name}:sign

Returns a private preview with a new token; tokens signed before keep their own expiry.

Its action, for a key's grant: previews:sign.

Path: name.

Query:

Field Type Required Description
ttlSeconds integer No The token's lifetime in seconds, from 60 until the calling key's own end (a year at most); a day when omitted, or the key's end when that is sooner. At least 60. At most 31536000. Default: 86400.

Returns a Preview.

In v1: GET /v1/sandboxes/{id}/previews/{port}.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/previews/example:sign" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.previews.sign("example");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.previews.sign("example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.previews.sign("example")
Terminalruntime previews sign example

rotate#

POST /v2/previews/{name}:rotate

Refuses every token signed for a preview so far, and returns a new one.

Its action, for a key's grant: previews:create.

Path: name.

Returns a Preview.

In v1: POST /v1/sandboxes/{id}/previews/{port}:rotate.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/previews/example:rotate" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.previews.rotate("example");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.previews.rotate("example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.previews.rotate("example")
Terminalruntime previews rotate example

Delete a preview#

DELETE /v2/previews/{name}

Stops sharing a port.

Its action, for a key's grant: previews:delete.

Path: name.

Returns a Preview.

In v1: DELETE /v1/sandboxes/{id}/previews/{port}.

Examples:

Terminalcurl -X DELETE "https://api.withruntime.com/v2/previews/example" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.previews.delete("example");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.previews.delete("example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.previews.delete("example")
Terminalruntime previews delete example

Objects#

PreviewCreate

A preview of the sandbox its path names to create, or its visibility and sites to change.

Field Type Required Description
port integer Yes The port inside the sandbox. At least 1. At most 65535.
visibility one of private, public No private (default): a token is needed. public: anyone with the address.
embedOrigins list of string No The sites that may show it in an iframe; omitted on one that exists, kept as it is; empty for any site.
ttlSeconds integer No The token's lifetime in seconds, from 60 until the calling key's own end (a year at most); a day when omitted, or the key's end when that is sooner. At least 60. At most 31536000. Default: 86400.

Preview

A preview.

Field Type Required Description
id string Yes Its ID.
object one of preview Yes Always preview.
sandboxId string Yes The sandbox whose port it shares.
port integer Yes The port inside the sandbox.
visibility one of private, public Yes private or public.
url string Yes Its address. A private one also needs the token.
state one of making, ready, deleted Yes Where it is: ready once every serving host routes it.
token string No A token signed for this answer, for a private preview and a key that may create one: send it in the x-runtime-preview-token header, or open the url with ?runtime_preview_token=<token> in a browser.
tokenExpiresAt string (RFC 3339) No When this answer's token stops working.
embedOrigins list of string No The sites that may show it in an iframe; none for any site.
createdAt string (RFC 3339) Yes When it was created.
deletedAt string (RFC 3339) No When it was deleted: a delete's answer, its state deleted.
Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial