Port API reference
A public TCP port carried to a port of a sandbox: a database, a game server, anything that is not HTTP.
Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.
Its states: making, ready, deleted.
Endpoints#
| Method | Path | Description |
|---|---|---|
POST |
/v2/ports |
Create a port |
GET |
/v2/ports |
List ports |
DELETE |
/v2/ports/{id} |
Delete a port |
Create a port#
POST /v2/ports
Opens a public TCP port to a port of a sandbox: raw TCP, carried as it is. The public port is assigned from a pool of 10,000; returns 409 when every one is in use. Asked again for the same sandbox and port, it returns the same public port.
Its action, for a key's grant: ports:create.
Body: a PortCreate.
Returns a Port.
In v1: POST /v1/ports.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/ports" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sandboxId": "SANDBOX_ID", "port": 3000 }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ports.create({ sandboxId: "SANDBOX_ID", port: 3000 });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.ports.create(sandbox_id="SANDBOX_ID", port=3000)rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ports.create(sandbox_id: "SANDBOX_ID", port: 3000)Terminalruntime ports create --sandbox-id SANDBOX_ID --port 3000List ports#
GET /v2/ports
Lists the org's public TCP ports, or one sandbox's, by connect.
Its action, for a key's grant: ports:list.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
sandboxId |
string | No | Only this sandbox's ports. |
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 Port, and next, where the next page starts, none on the last.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/ports" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ports.list();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.ports.list()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ports.listTerminalruntime ports listDelete a port#
DELETE /v2/ports/{id}
Closes a public TCP port and the connections through it.
Its action, for a key's grant: ports:delete.
Path: id.
Returns a Port.
In v1: DELETE /v1/ports/{id}.
Examples:
Terminalcurl -X DELETE "https://api.withruntime.com/v2/ports/PORT_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ports.delete("PORT_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.ports.delete("PORT_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ports.delete("PORT_ID")Terminalruntime ports delete PORT_IDObjects#
PortCreate
A public TCP port to open.
| Field | Type | Required | Description |
|---|---|---|---|
sandboxId |
string | Yes | The sandbox to carry to. |
port |
integer | Yes | The port inside the sandbox, 1 to 65535. |
PortSettings
A public TCP port's settings, as it keeps them.
| Field | Type | Required | Description |
|---|---|---|---|
port |
integer | Yes | The port inside the sandbox. At least 1. At most 65535. |
Port
A public TCP port: raw TCP from a public address and port to a port of a sandbox.
| Field | Type | Required | Description |
|---|---|---|---|
port |
integer | Yes | The port inside the sandbox. At least 1. At most 65535. |
id |
string | Yes | Its ID. |
object |
one of port |
Yes | Always port. |
connect |
string | Yes | address:publicPort ([address]:publicPort for IPv6), for a client's host and port. |
address |
string | Yes | The public address to connect to. |
publicPort |
integer | Yes | The public port to connect to. |
sandboxId |
string | Yes | The sandbox it carries to. |
state |
one of making, ready, deleted |
Yes | Its state: ready once every edge carries it. |
disabled |
boolean | Yes | Turned off by Runtime: no connection passes. |
createdAt |
string (RFC 3339) | Yes | When it was opened. |
deletedAt |
string (RFC 3339) | No | When it was deleted: a delete's answer, its state deleted. |