Skip to main content
POST
Resize a Sailbox

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
X-Sail-Owner-Override-Reason
string

Lets an organization admin operate a private Sailbox someone else created. Say why in plain text; the reason goes into your organization's audit log, and the operation is refused without it. Ignored on Sailboxes you could already operate.

Pause, resume, sleep, scheduled wake, upgrade, reboot, resize, and terminate accept an override, and so does deleting a checkpoint taken from the Sailbox. Setting an egress policy accepts one too. Running commands and moving files accept one through an SDK or the CLI. Publishing and unpublishing ports, adding and removing custom domains, checkpointing, and creating from a checkpoint stay with the creator.

Pattern: ^[ -~]*$

Path Parameters

sailbox_id
string
required

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

Body

application/json

Every field is optional, but at least one must be set. A field left out (or null) keeps its current value, and a value equal to the current one is accepted and changes nothing. A field set to 0 or to an empty string is rejected.

size
enum<string>

The new size. Limits outside the new size's range are clamped into it. A smaller size is refused while the Sailbox uses more memory than that size allows, or while its disk limit is above that size's maximum.

Available options:
s,
m,
l
memory_limit_gib
integer

The new memory limit in whole GiB, within the size's range. Lowering it needs a running Sailbox. The limit cannot come within a GiB of what the Sailbox is using: it settles one GiB above that amount, rounded up to a whole GiB, when that is higher; the response reports the limit that took effect.

Required range: x >= 1
state_disk_limit_gib
integer

The new disk limit in GiB, within the size's range. A disk only grows: a value below the current limit is refused.

Required range: x >= 1

Response

The Sailbox's shape after the call.

sailbox_id
string
required

Id of the Sailbox.

status
string
required

Current state of the Sailbox. Values in use today are creating, running, paused, sleeping, terminating, terminated, failed, create_failed, interrupted_restorable, and interrupted_unsafe_to_retry. New values can appear over time, so treat this as an open set.

applied
boolean
required

true when the Sailbox has the new shape now. false when it was powered off: the shape is recorded and takes effect at the next wake. Also false when a restart the change needed could not complete; the Sailbox is then paused with the new shape recorded.

restarted
boolean
required

true when the change restarted the Sailbox. Files on its disk were kept; running processes and memory were not.

size
string
required

The size the Sailbox is now set to: s, m, or l. Empty when its vCPU count does not match a size, as for a Sailbox created with a raw cpu count whose resize changed only a limit.

vcpu_count
integer
required

Virtual CPUs the Sailbox has now.

memory_mib
integer
required

The memory limit in MiB that took effect. On a lowering this can be above what you asked for, because the limit lands one GiB above what the Sailbox is using.

state_disk_size_gib
integer
required

The disk limit in GiB now.

memory_in_use_mib
integer | null
required

Memory the Sailbox was using when its memory limit was lowered while running, in MiB; the lowered limit lands one GiB above it. null for any other change.