Move a key's instance to another version of its app, in place

reports/workers/keyed-upgrade.md, slices U1 and U2. A key's instance stays on the version it was made from until this is asked. version: the version it goes to, by its id or its number (the app's current version where it is not given), any of the app's versions that is ready, an older one too. when (slice U3): now (the default), or asleep, which waits (waiting) for the instance to sleep, by its node's last inventory, and begins then, its node making sure it sleeps still (one that woke meanwhile is waited for again): it holds none of the requests the instance serves while it waits; one that never sleeps waits until it is cancelled (DELETE …/upgrades/{id}). keep_days (0 to 365, 7 by default): how long what a revert needs is kept once it is done, billed as snapshots are (rollback): a snapshot of the instance as it was, and one of each Drive it had. The instance keeps its id, its node, its key, its project address, its tokens and its own Drives (key_drives) with what they hold; its disk, its machine, its processes, its start command and its labels become the new version's. Its own Drives are matched by their names (reports/workers/keyed-upgrade.md, 五): one the new version names is mounted at the new version's path; one it names that the key has none of is made for the key first, on the instance's node, of the version's size_bytes, given what the image has at its path unless the version says nocopy, as the key's first instance's are (drive.created); one it no longer names is left off, and kept: still the key's, listed, billed as a Drive, deleted with the key, mounted again by a later version that names it. A Drive that cannot be made ends the upgrade failed, upgrade_not_here, the make's code and words in its message, nothing of the instance touched; an upgrade that does not end done deletes the Drives it made again, and the key has its Drives as before (one that failed on the instance's node, its version not coming up, reads failed a moment before they are gone: their drive.deleted events say when). The steps: preparing, the instance's node is given the version's template as a deploy gives a node of the app one (had, fetched from the object store, or built), the instance serving meanwhile; switching, every edge holds the instance's requests as for a move, the requests its node has in hand are answered first, the calls of its sandbox are answered 503 upgrading (but a read of it (GET /v1/sandboxes/{id}) answers 200 with it as it was last seen, status upgrading), and its node stops its start command (the old version's stop), takes its Drives off with a version of each made as the old version left it, rolls it over to the new template in place, mounts its Drives again where the new version has them (and the ones made for it; not the ones it leaves off), and starts the new start command; then the key names the new version (instance.upgraded), and the held requests go to it, at the pace a move lets them go. A new version that does not come up has the instance put back as it was, its Drives with what they held before (failed, upgrade_failed, put_back; instance.upgrade_failed). Open connections end: their processes are replaced. Takes write; Idempotency-Key is honoured. Of an app of the Sandboxes product (managed_by.object sandboxes: the project's default sandbox app, or an image's), the instance is the project's sandbox the key names (its name, or its id), and any version of the app is one it may go to (an image the project named for its default sandbox app, or one its tag was moved to): its node is given its own template of the version's image, by its digest, in the sandbox's shape (or the base template), and the sandbox keeps its labels and its settings; its disk and its processes become the new version's, as a restore to a snapshot replaces them; and version_id, image_digest say what it is from then on.

POST

https://api.glac.ai/v1/apps/{app}/instances/{key}/upgrade

View as Markdown

Authorization

apiKeyHTTPrequired

Path parameters

appstringrequired
The app's id (app-...) or its name.
keystringrequired
A key of the app: 1 to 128 characters, none of them a control character, written into the path as a segment is (%XX for a byte that is not a letter, a digit or one of -._~: agent%2042 for agent 42).

Header parameters

Idempotency-Keyoptionalstring
1 to 255 characters: the same key and body again gets the same answer, and nothing is made twice.

maxLength: 255 · minLength: 1

Request bodyJSON

versionoptionalstring | integer | null
The version it goes to: its id (ver-…) or its number. Not given: the app's current version.
whenoptionalnoworasleepornull
now (the default), or asleep: once the instance sleeps.
keep_daysoptionalinteger | null
Days what a revert needs is kept: 7 where it is not given; 0 for nothing.

maximum: 365 · minimum: 0

Returns

200

The instance is on that version already: the instance, as GET …/instances/{key} shows it.

JSON

idstringrequired
The sandbox's id (sbx-...): what /v1/sandboxes/{id}/... answers it under.
objectinstancerequired
statusstringrequired
A sandbox's status; unavailable while its node cannot be reached.
app_idstringrequired
version_idstringrequired
The version it was made from; a version deployed later leaves it on this one.
keystringrequired
regionstringrequired
The region it was made in.
metadataoptionalmap ofstring
The app's labels, and app, version, region and key: what a table that is built again from the nodes reads.
start_commandoptional
How its start command runs, how often it was started again in its machine after it ended (a key's instance and a stateful service's are, with their disk and volumes as they are; each start is an instance.restarted), how its last run ended, and when the next start is due while one waits: status (running, restarting, exited), restarts, last_exit (status, signal, at), restarting_at, as SandboxStartCommand in sandboxd/openapi/openapi.json says. Null where its guest has said nothing of it yet.
One of the following:
InstanceStartCommand
statusstringrequired
running: a run of it is under way (or what it left behind still holds its output); restarting: it ended, and is started again at restarting_at; exited: it ended, and nothing starts it again.

restartsintegerrequired
How often it was started again in its machine since the sandbox was made, across the boots of its machines.

format: int64 · minimum: 0
last_exitrequired
How its last run ended; null where none has.

One of the following:
object
null
restarting_atstring | nullrequired
While restarting: when its next run begins, by its guest's clock (a machine asleep then starts it as it wakes). Null otherwise.

format: date-time
null
}
delete_after_idle_msoptionalinteger | null
Its own time asleep after which it is deleted, as a sandbox's (PATCH /v1/sandboxes/{id}): where it has one, it goes by that and not by its app's keys.delete_after_idle_ms. null: its app's.
idle_sinceoptionalstring | null
When its current sleep began, as its node says (in a list, as the control plane last saw its object), or, for one that was frozen, when it was let go of: what both times asleep are counted from. null while it is awake.

format: date-time

202

The upgrade, preparing (waiting with when: asleep); Location is where it is shown (?wait_seconds= waits for its end).

JSON

idstringrequired
pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
objectupgraderequired
app_idstringrequired
pattern: ^app-[0-9a-hjkmnp-tv-z]{16}$
keystringrequired
instance_idstringrequired
The instance, which keeps its id.

pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
kindstringrequired
revert: back to what an upgrade kept (reverts).
from_versionstringrequired
pattern: ^ver-[0-9a-hjkmnp-tv-z]{16}$
to_versionstringrequired
pattern: ^ver-[0-9a-hjkmnp-tv-z]{16}$
statusstringrequired
waiting: for the instance to sleep (when: asleep), or a batch's member for its turn, the instance serving as ever; preparing: the instance's node is given the new version's template, the instance serving meanwhile; switching: its node moves it over, its requests held at the edges and its calls answered 503 upgrading (but a read of it (GET /v1/sandboxes/{id}) answers 200 with it as it was last seen, status upgrading); done; failed (error, put_back); cancelled (while it waited: DELETE, or its batch stopped, error saying so).
whennoworasleeprequired
asleep: it began once the instance slept (by its node's last inventory, its node making sure), and so held none of the requests the instance served while it waited.
keep_daysintegerrequired
How many days what a revert needs is kept (0: nothing).

maximum: 365 · minimum: 0
rollbackrequired
What a revert of it needs, kept once it is done (null where it kept nothing).
One of the following:
UpgradeRollback
snapshot_idstring | nullrequired
The instance's snapshot (snap-…).

with_processesbooleanrequired
A revert has the instance's processes back as they were (an instance without Drives); else it boots from the snapshot's disk and starts its version's start command once its Drives are mounted.

drivesarray ofobjectrequired
drive_idstring | nullrequired
snapshot_idstring | nullrequired
The Drive's snapshot (dsnap-…, named before-upgrade-<id> or before-revert-<id>); null where none could be kept (a revert is refused then).

expires_atstring | nullrequired
Until when it is kept, by the books' clock.

format: date-time
gone_atstring | nullrequired
When it was let go of.

format: date-time
null
}
revertsstring | nullrequired
A revert's: the upgrade it goes back from.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
batchstring | nullrequired
The batch it is a member of (POST /v1/apps/{app}/upgrades).

pattern: ^upb-[0-9a-hjkmnp-tv-z]{16}$
timingsobjectrequired
Milliseconds, each where its step was reached: prepare_ms (and template: how the node came to have it, had, fetched or built), held_ms (how long the edges held its requests), node (the node's own), total_ms.
- prepare_msoptionalinteger
  Until the instance's node had the new version's template.
  
  minimum: 0
- templateoptionalstring
  How the node came to have it.
- held_msoptionalinteger
  How long the edges held the instance's requests.
  
  minimum: 0
- nodeoptionalobject | null
  The node's own steps, in milliseconds to the hundredth, as SandboxUpgrade.timings in sandboxd/openapi/openapi.json says them; null where the node said none.
  
  snapshot_msoptionalnumber
  minimum: 0
  stop_msoptionalnumber
  minimum: 0
  detach_msoptionalnumber
  minimum: 0
  versions_msoptionalnumber
  minimum: 0
  restore_msoptionalnumber
  minimum: 0
  switch_msoptionalnumber
  minimum: 0
  attach_msoptionalnumber
  minimum: 0
  start_msoptionalnumber
  minimum: 0
  total_msoptionalnumber
  minimum: 0
- total_msoptionalinteger
  The whole upgrade, once it is over.
  
  minimum: 0
}
errorobject | nullrequired
Where it failed: upgrade_failed, the new version did not come up (what it said is in message); upgrade_not_here, the instance's node could not have the new version's template, or refused the upgrade before touching anything (the node's words are in message), or a Drive the new version gives the key could not be made (the make's code and words are in message: drive_limit_reached where the plan does not let it be); rollback_gone, what a revert goes back to is gone. Where it was cancelled other than by DELETE: instance_gone (the key names another instance, or none), batch_stopped (its batch stopped, or was superseded), superseded (a stateful service's deploy came first).
- codestringrequired
- messagestringrequired
}
put_backboolean | nullrequired
Where it failed with upgrade_failed: whether the instance was put back as it was, its Drives with what they held before.
created_atstringrequired
format: date-time
started_atstring | nullrequired
When its requests began to be held.

format: date-time
ended_atstring | nullrequired
format: date-time

400

invalid_json, unknown_field, unknown_parameter, invalid_field (version is neither an id nor a number; when, keep_days), invalid_key, invalid_idempotency_key.

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

401

missing_api_key, invalid_api_key, expired_api_key, invalid_token.

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

402

account_in_debt: the account owes (its balance is below zero), and until it has paid nothing of it can be used: every call of its keys, and of the tokens of its sandboxes, is refused so, but those that read what it owes and pay it; those that list and read the backups of its volumes and make a volume from one (POST /v1/volumes with from_backup, but while what it stores is being deleted), what one that stopped paying wants most; and, unless the control plane is started with --debt-allows-delete false, those that list, read and delete the volumes, snapshots and sandboxes it stores, and delete its backups. Never a new backup. Before the key's scopes are looked at, and whatever the path. The message says how much is owed, since when, when what the account stores is deleted, how to pay, that it can delete what it stores to stop the amount from growing, and that a volume is still made from a backup (GET /v1/billing, debt).

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

403

key_scope: the key does not allow the scope the call takes (the message names it); needs_api_key: the operator's key, or the SSH gateway's; account_held: the account is held for its payments, and every call of its keys but GET /v1/account is refused so, before the scopes are looked at (x-error-codes); installation_key_scope: a key held to an installation of a Managed Application, on a call that is not about that installation's own things. (A sandbox token is passed to its node, which answers what it has no call for with 404 no_such_route.)

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

404

app_not_found; key_not_found: the key names no instance (param is key); version_not_found: the app has no such version (param is version).

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

409

version_not_ready: the version is being built, or failed, or the app has none deployed (param is version); upgrade_in_progress: the key has an upgrade that is not over (its id is upgrade_id, beside error); managed_by_database: the app is a database's, changed through /v1/databases alone; upgrade_not_here: of an app of the Sandboxes product, a sandbox made with what its create said of its start (its start command, environment, ready check, runtime or files, or credentials for its image), which the control plane does not keep, or made from a snapshot: its new version could not be made so; idempotency_key_reused.

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

503

moving (retryable, Retry-After): the instance is being moved to another node; it is upgraded once that is over.

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  One of the following:
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionalarray ofobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilesarray ofstringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray ofobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicesarray ofobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedorchangedorunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceorjobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemsarray ofobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneoradaptedorignoredorrefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  One of the following:
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  One of the following:
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  One of the following:
  string
  array<string>
  envmap ofstringrequired
  secretsmap ofstringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumesarray ofobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray ofobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  One of the following:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray ofstringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on the free plan, 50 on p20, 200 on p100, 500 on p300, 1,000 on p1000, 2,000 on p2000): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2, 10, 20, 50, 100 and 200), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msintegerrequired
  After how long without a request an instance stops. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  One of the following:
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowordenyornull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap ofstringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_onarray ofobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray ofstringrequired
  endpoint_modestringrequired
  drivesoptionalarray ofobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray ofobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  One of the following:
  Runtime
  ulimitsmap ofRuntimeLimitGivenrequired
  sysctlsmap ofstringrequired
  tmpfsarray ofobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray ofstringrequired
  searcharray ofstringrequired
  optionsarray ofstringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumesarray ofobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeormadeorthereorexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_byarray ofstringrequired
- secretsarray ofobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_byarray ofstringrequired
- left_outarray ofobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray ofstringrequired
- absentarray ofstringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionalarray ofobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}