Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview

Publish a sandbox port over HTTPS, or change its visibility

The edge proxies https://<sandbox>-<port>.<sandbox domain> to the port over the host’s private network, while the sandbox runs. A private port (the default) needs a login link from POST .../ports/{port}/link; a public one is open to anyone. The service must listen on the sandbox’s network interface (for example 0.0.0.0), not only on 127.0.0.1. Port 6080 is the desktop; use POST .../desktop for it.

PUT/v1/sandboxes/{sandbox}/ports/{port}
Authorization
AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters
sandboxstringrequired

Sandbox ID (sbx_...) or name.

portintegerrequired

TCP port inside the sandbox.

min 1 · max 65535
Request body
application/json
publicboolean

Open the port to anyone, without a login link.

default: false
Responses
200

The published port.

portintegerrequired
min 1 · max 65535
publicbooleanrequired

Open to anyone. Private ports need a login link.

urlstringrequired

The port's HTTPS URL, on the sandbox's host label (on its ID for a sandbox without one). For a private port, open a login link first.

created_atstring<date-time>required
429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request
curl -X PUT 'https://api.pols.so/v1/sandboxes/string/ports/1' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "public": false
}'
Response
{
  "port": 1,
  "public": true,
  "url": "https://braveotterk3f9-8080.on.pols.so/",
  "created_at": "2019-08-24T14:15:22Z"
}