Skip to content

Session API reference

A short-lived token a frontend holds to reach one machine directly: it reads the machine, runs its commands and processes, reads and writes its files, and signs its previews' links, and does nothing else. It acts as the key that made it and ends with that key.

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

Its states: active, deleted.

Updated .md

Endpoints#

Method Path Description
POST /v2/sessions Create a session
DELETE /v2/sessions/{id} Delete a session

Create a session#

POST /v2/sessions

Makes a session for one machine the caller reaches and returns its token this once. The token reads the machine, runs its commands and processes, reads and writes its files and signs its previews' links, and nothing else; it acts as the caller, lives expiresInSeconds (an hour unless asked, a day at most), never past the caller's key, and ends when that key is revoked. The API answers CORS for its calls, so a web page can make them.

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

Body: a SessionCreate.

Returns a SessionCreated.

In v1: POST /v1/sandboxes/{machineId}/sessions.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/sessions" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "machineId": "example" }'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.sessions.create({ machineId: "example" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.sessions.create(machine_id="example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.sessions.create(machine_id: "example")
Terminalruntime sessions create --machine-id example

Delete a session#

DELETE /v2/sessions/{id}

Ends a session now: its next call is refused. Its maker ends its own; an owner or an admin, any of the organization's. Ended already, it returns 404.

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

Path: id.

Returns a Session.

In v1: POST /v1/sandboxes/{sandbox}/sessions/{id}:revoke.

Examples:

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

Objects#

SessionCreate

A session to make.

Field Type Required Description
machineId string Yes The machine it reaches (a sandbox, an app, a desktop, any machine), by its ID.
expiresInSeconds integer No Seconds until it stops working, 60 to 86400; 3600 when omitted. Never past the key that makes it. At least 60. At most 86400.
name string No Its name: your own handle for it, such as the user it is for. At least 1 character. At most 64 characters.

Session

A session: a token for one machine, for a frontend.

Field Type Required Description
id string Yes Its ID.
object one of session Yes Always session.
machineId string Yes The machine it reaches, alone.
name string Yes Its name, as its maker gave it.
accountId string No The person it acts as or for.
agentId string No The agent or CI pipeline it acts as.
state one of active, deleted Yes active while it works; deleted once ended: a delete's answer.
createdAt string (RFC 3339) Yes When it was made.
expiresAt string (RFC 3339) Yes When it stops working: its own end, or the end of the key that made it, the sooner.
deletedAt string (RFC 3339) No When it was ended: a delete's answer.

SessionCreated

A session just made, with its token: shown this once, never again.

Field Type Required Description
id string Yes Its ID.
object one of session Yes Always session.
machineId string Yes The machine it reaches, alone.
name string Yes Its name, as its maker gave it.
accountId string No The person it acts as or for.
agentId string No The agent or CI pipeline it acts as.
state one of active, deleted Yes active while it works; deleted once ended: a delete's answer.
createdAt string (RFC 3339) Yes When it was made.
expiresAt string (RFC 3339) Yes When it stops working: its own end, or the end of the key that made it, the sooner.
deletedAt string (RFC 3339) No When it was ended: a delete's answer.
token string Yes The token, to send as Authorization: Bearer <token> from the frontend.
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