Domain API reference
Your own hostname serving a sandbox's port, with HTTPS.
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/domains |
Create a domain |
GET |
/v2/domains |
List domains |
GET |
/v2/domains/{hostname} |
Get a domain |
POST |
/v2/domains/{hostname}:verify |
verify |
DELETE |
/v2/domains/{hostname} |
Delete a domain |
Create a domain#
POST /v2/domains
Adds a hostname to serve a sandbox's port, checks its TXT record, and returns the DNS records to set. Asked again with another sandbox or port, it points the name there.
Its action, for a key's grant: domains:create.
Body: a DomainCreate.
Returns a Domain.
In v1: POST /v1/domains.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/domains" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "hostname": "example", "sandboxId": "SANDBOX_ID", "port": 3000 }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.domains.create({ hostname: "example", sandboxId: "SANDBOX_ID", port: 3000 });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.domains.create(hostname="example", sandbox_id="SANDBOX_ID", port=3000)rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.domains.create(hostname: "example", sandbox_id: "SANDBOX_ID", port: 3000)Terminalruntime domains create --hostname example --sandbox-id SANDBOX_ID --port 3000List domains#
GET /v2/domains
Lists the org's custom domains, by hostname.
Its action, for a key's grant: domains:list.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
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 Domain, and next, where the next page starts, none on the last.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/domains" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.domains.list();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.domains.list()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.domains.listTerminalruntime domains listGet a domain#
GET /v2/domains/{hostname}
Returns a custom domain and the DNS records it needs.
Its action, for a key's grant: domains:get.
Path: hostname.
Returns a Domain.
In v1: GET /v1/domains/{hostname}.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/domains/HOSTNAME_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.domains.get("HOSTNAME_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.domains.get("HOSTNAME_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.domains.get("HOSTNAME_ID")Terminalruntime domains get HOSTNAME_IDverify#
POST /v2/domains/{hostname}:verify
Checks the TXT record now; the name is served once it matches.
Its action, for a key's grant: domains:create.
Path: hostname.
Returns a Domain.
In v1: POST /v1/domains/{hostname}:verify.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/domains/HOSTNAME_ID:verify" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.domains.verify("HOSTNAME_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.domains.verify("HOSTNAME_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.domains.verify("HOSTNAME_ID")Terminalruntime domains verify HOSTNAME_IDDelete a domain#
DELETE /v2/domains/{hostname}
Stops serving the hostname. Remove its DNS records too.
Its action, for a key's grant: domains:delete.
Path: hostname.
Returns a Domain.
In v1: DELETE /v1/domains/{hostname}.
Examples:
Terminalcurl -X DELETE "https://api.withruntime.com/v2/domains/HOSTNAME_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.domains.delete("HOSTNAME_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.domains.delete("HOSTNAME_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.domains.delete("HOSTNAME_ID")Terminalruntime domains delete HOSTNAME_IDObjects#
DomainCreate
A custom domain to add, or to point at another sandbox or port.
| Field | Type | Required | Description |
|---|---|---|---|
hostname |
string | Yes | The hostname, at most 253 characters. |
sandboxId |
string | Yes | The sandbox to serve. |
port |
integer | Yes | The port inside the sandbox, 1 to 65535. |
DomainSettings
A custom domain's settings, as it keeps them: the port it serves, and its proof of ownership as facts.
| Field | Type | Required | Description |
|---|---|---|---|
port |
integer | Yes | The port inside the sandbox. At least 1. At most 65535. |
token |
string | Yes | The token the TXT record at _runtime-challenge.<hostname> holds as runtime-verify=<token>. |
verifiedAt |
string (RFC 3339) | No | When the TXT record was last found to hold the token; none until it is. |
checkedAt |
string (RFC 3339) | No | When the TXT record was last looked up. |
checkError |
string | No | What the last lookup found wrong; none when it proved the name. |
Domain
A custom domain: your own hostname serving a sandbox's port.
| Field | Type | Required | Description |
|---|---|---|---|
port |
integer | Yes | The port inside the sandbox. At least 1. At most 65535. |
token |
string | Yes | The token the TXT record at _runtime-challenge.<hostname> holds as runtime-verify=<token>. |
verifiedAt |
string (RFC 3339) | No | When the TXT record was last found to hold the token; none until it is. |
checkedAt |
string (RFC 3339) | No | When the TXT record was last looked up. |
checkError |
string | No | What the last lookup found wrong; none when it proved the name. |
id |
string | Yes | Its ID. |
object |
one of domain |
Yes | Always domain. |
hostname |
string | Yes | The hostname, lower case. |
sandboxId |
string | Yes | The sandbox it serves. |
state |
one of making, ready, deleted |
Yes | Its state: ready once every serving host routes it. |
disabled |
boolean | Yes | Turned off by Runtime. |
createdAt |
string (RFC 3339) | Yes | When it was added. |
records |
list of object of strings | No | The DNS records to set: the TXT record that proves the name, and the CNAME that sends visitors here. |
deletedAt |
string (RFC 3339) | No | When it was deleted: a delete's answer, its state deleted. |