Skip to main content
POST
Publish a port

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Makes the request retry-safe. Sail remembers the answer it sent under a key, including a 400 or a 409, and replays it with Idempotent-Replayed: true for a retry that repeats the key, the method, the path, and the body. Bodies are compared byte for byte. Reusing a key for a different request returns 409, so send a corrected request under a new key. A key that is blank or only spaces is ignored, and the request runs without idempotency.

Any string of up to 255 bytes works, and characters outside ASCII count for more than one. A UUID is a good default. Keys are remembered for at least 24 hours and scoped to the API key that sent them.

A server error, or a failure to record the answer, can leave a key unsettled, and creating a Sailbox is where that matters. See Retrying safely.

Maximum string length: 255

Path Parameters

sailbox_id
string
required

Id of the Sailbox, as returned by create. It is sb_ followed by a UUID.

Pattern: ^sb_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Body

application/json
guest_port
integer
required

Port your process listens on inside the Sailbox. Ports 10000, 10001, 15001, and 15002 are reserved and cannot be published on either protocol. Port 22 is reserved on http and available on tcp, which is what SSH needs.

A guest port is published under one protocol at a time. Publishing it again under that same protocol replaces its allowlist; publishing it under the other protocol is refused.

Required range: 1 <= x <= 65535
protocol
enum<string>
default:http

http publishes an HTTPS URL. tcp publishes a host and port for raw TCP, which is what SSH and database clients need.

Available options:
http,
tcp,
allowlist
string[]

Restricts who can reach the listener. An address or a range, such as 203.0.113.0/24, lets matching source IPs in, and works on both protocols. An app name, which lets Sailboxes in that app call this one, works on http only and is rejected on tcp.

An app name must not look like an address or a range, and must not contain a /. Every entry that reads as an address or a range is taken as one, and any other entry holding a / is refused as a malformed range. An address must not carry an IPv6 zone, such as fe80::1%eth0, which names an interface on one machine rather than a source.

Entries come back canonicalized: a range is reported by its network address, a bare address as a single-address range, and blank or repeated entries are dropped.

Leaving it empty makes the listener reachable by anyone who has the address. That is refused on a tcp listener for a well-known unauthenticated service port such as 5432 or 6379: publish those with an explicit allowlist, using 0.0.0.0/0 and ::/0 if you do want the whole internet.

Response

The port is published.

guest_port
integer
required

Port inside the Sailbox that traffic is sent to.

protocol
string
required

Protocol the listener serves. Values in use today are http and tcp. New values can appear over time, so treat this as an open set.

public_url
string

HTTPS URL for an http listener.

public_host
string

Host to dial for a tcp listener.

public_port
integer

Port to dial for a tcp listener.

allowlist
string[]

Sources allowed to reach the listener: addresses, ranges, and app names.