Rename a snapshot or change when it expires

A merge: fields left out stay as they are.

Takes write.

PATCH

https://api.glac.ai/v1/snapshots/{id}

Autorización

apiKeyHTTPrequired

Parámetros de ruta

idstringrequired
A snapshot's id (snap-…) or its name.

Parámetros de encabezado

X-Request-Idoptionalstring
The caller's own id for the request: 1 to 64 letters, digits, ., _ and -. The node then knows the request by it: in the answer's X-Request-Id, in error bodies and in its log. Anything else is ignored, and the node makes an id.

pattern: ^[A-Za-z0-9._\-]{1,64}$

Cuerpo de la solicitudJSONopcional

nameoptional
Null removes the name.
Una de estas opciones:
Name
null
}
expires_atoptionalstring | null
Null: never.

format: date-time

Returns

200

The snapshot as it is now.

JSON

replicatedbooleanrequired
Whether the snapshot is in the object store the node copies its disks to, complete (every part of it there and its index written last), so that a node of the site that copies to the same store can make a sandbox from it, fork from it and roll a sandbox back to it. A node that copies its disks (--upload) publishes every snapshot it takes, in the background, a second or two after the call that took it answered. Its disk is not copied: the publication pins the state the sandbox's own disk had in the store at the snapshot, and carries only the blocks that were not there yet; its memory goes as a sleep's image does. False until then, and for good for a snapshot of a node that copies to no store, one taken before snapshots were published, and one of a machine whose memory is not in layers: such a snapshot is used on its node, as ever.
replicated_atstring | nullrequired
When its publication was complete. Null: it is not in the store.

format: date-time
last_replication_statusstringrequired
How its publication stands: pending (taken, not asked of the node's uploader yet: its files are being forced), replicating (the uploader is at it), replicated, failed (the last try failed, and the node tries again, twenty seconds later and twice as long after each failure, at most a quarter of an hour), not_replicable (it is never published, for the reasons under replicated).
egressobjectrequired
The egress rules of the sandbox at the instant the snapshot was taken. A sandbox created from the snapshot starts with them unless the call gives egress; a sandbox restored to the snapshot keeps the rules it has.
- defaultallowodenyrequired
  What happens to what neither list speaks of.
- allowarray destringrequired
  Reached under default: deny. Empty under default: allow.
  
  maxLength: 300
- denyarray destringrequired
  Never reached, whatever allow says.
  
  maxLength: 300
- httparray deobjectrequired
  The requests the sandbox may send to a host, by method and path. Methods are shown in capitals, each once; the rest as it was given.
  
  hoststringrequired
  A host name, or *. and a name. Not an address.
  
  maxLength: 300
  allowarray deobjectrequired
  The requests that pass. A host that is to get none goes in deny.
  
  methodsoptionalarray | null
  Methods, as tokens; kept in capitals. A request's method is compared as it was sent, so get is none of them. CONNECT cannot be allowed.
  
  pathsoptionalarray | null
  Patterns. A pattern is a path: it begins with /, has no ? and no #, and is compared with the whole path of the request, which is its target before the ? (the query is not judged). * stands for any run of characters, / included, and nothing else is special: /repos/* is everything under /repos/ and not /repos. Case matters. Both are compared in one form: escapes of unreserved characters are decoded (%7E is ~), other escapes are kept with their digits in capitals, bytes outside ASCII are escaped. An encoded slash stays one and is not /; a pattern can contain %2F to allow exactly that (/@types%2Fnode). A path that hosts could read as another path has no form and matches no pattern (a rule without paths still has it): one with a segment that is . or .. after its escapes are decoded, once or more often, with \ and an encoded slash read as /, with what follows a ; in a segment cut off and the spaces at a segment's ends dropped; one with a malformed escape, a #, a control character, bytes that are no UTF-8, or a character that folds into ., / or \ (U+FF0E, U+FF0F, U+FF3C, U+2215, U+2044, U+2024); one of more than 8192 bytes. Such a request is answered 400 malformed_request.
- injectarray deobjectrequired
  Headers the node adds to the sandbox's HTTPS requests to a host.
  
  hoststringrequired
  A host name, or *. and a name. Not an address.
  
  maxLength: 300
  headersmapa destringrequired
  Each header's name and value. In a value, ${secrets.NAME} stands for the secret of that name (PUT /v1/secrets/{name}), which has to be one that may go to host (its allowed_hosts; 403 secret_host_not_allowed otherwise); the sandbox object shows the reference, never the secret. Headers that say where a request goes or where it ends (Host, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect) cannot be set.
- deny_portsoptionalarray deinteger
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say: refused first, by the packet filter, and never handed to the proxy. Shown only where the rules close any. A control plane closes a Browsers session's mail and mining-pool ports so.
  
  maximum: 65535 · minimum: 1
}
memory_loadablebooleanrequired
Whether a sandbox made from the snapshot on this node continues from the snapshot's instant, processes included. False: the snapshot's memory was saved by a build of Firecracker the host does not keep, or with other settings for the machine's devices than the node starts machines with now (or the snapshot is lost); one that a kept build saved is loaded by that build (Node.firecrackers). The snapshot is kept as it is, and is loadable again on a node that is started with what saved it. Meanwhile a sandbox created from it, or rolled back to it, gets the snapshot's disk and starts from that: nothing that ran in the snapshot runs in it, and its host_failure says so (cause node_changed).
idstringrequired
pattern: ^snap-[0-9a-hjkmnp-tv-z]{16}$
objectstringrequired
namerequired
Una de estas opciones:
Name
null
}
statusstringrequired
ready: the call that takes a snapshot returns when it is complete. lost: the node's host went down hard before the snapshot's files were on its disk (the node writes them there within a second or two of the call's answer, without holding the call up); it is listed so that its owner knows, sandboxes cannot be created from it or restored to it (409 snapshot_lost), and it can be deleted.
sandbox_idstring | nullrequired
The sandbox it was taken of.

pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
imagestring | nullrequired
The image that sandbox goes back to.
size_bytesintegerrequired
What it holds, in bytes, fixed when it is taken: what its sandbox had of its own at that moment (the pages of its memory that are not its template's, the state of its devices, the layer of its disk over the image) and nothing of the template or the image. The three parts a sleeping sandbox is counted as keeping. It is the same whatever else exists: another snapshot of the sandbox holds its own number, and deleting one changes no other's. A node counts a snapshot as keeping this for as long as it is there (a lost one as keeping nothing).

format: int64 · minimum: 0
volumesarray deobjectrequired
- pathstringrequired
- volumestringrequired
  pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
- read_onlybooleanrequired
}
created_atstringrequired
format: date-time
expires_atstring | nullrequired
When it deletes itself. Null: never.

format: date-time

400

The request is not one this call takes. invalid_json: the body is not a JSON object; unknown_field: the body has a field this call does not take; unknown_parameter: the query has a parameter this call does not take; invalid_field: a field or query parameter has the wrong type or is out of range; invalid_name: name is not a valid name; expires_in_the_past: expires_at is not in the future.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
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.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

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.
  
  Una de estas opciones:
  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 deobject
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 destringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray deobjectrequired
  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).
  
  treatmentdoneoadaptedoignoredorefusedrequired
  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 deobjectrequired
  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-
  statuscreatedochangedounchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceojobrequired
  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 deobjectrequired
  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).
  
  treatmentdoneoadaptedoignoredorefusedrequired
  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
  Una de estas opciones:
  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.
  
  Una de estas opciones:
  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.
  
  Una de estas opciones:
  string
  array<string>
  envmapa destringrequired
  secretsmapa destringrequired
  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 deobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray deobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  Una de estas opciones:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray destringrequired
  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 Free, 500 on Paid): 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 on Free, 50 on Paid), 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_msinteger | nullrequired
  The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. 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
  Una de estas opciones:
  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).
  
  defaultoptionalallowodenyonull
  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.
  
  metadatamapa destringrequired
  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 deobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray destringrequired
  endpoint_modestringrequired
  drivesoptionalarray deobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray deobject
  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.
  
  Una de estas opciones:
  Runtime
  ulimitsmapa deRuntimeLimitGivenrequired
  sysctlsmapa destringrequired
  tmpfsarray deobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray destringrequired
  searcharray destringrequired
  optionsarray destringrequired
  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 deobjectrequired
  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_makeomadeothereoexternalrequired
  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 destringrequired
- secretsarray deobjectrequired
  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 destringrequired
- left_outarray deobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray destringrequired
- absentarray destringrequired
  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 deobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

403

The credential may not do this. needs_api_key: a sandbox token cannot do this.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
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.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

404

Something the request names does not exist. snapshot_not_found: no such snapshot.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
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.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

409

The state of something stands in the way. name_taken: another snapshot has the name.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
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.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

default

Any other failure, in the same shape. internal (500): the node failed; the message says no more, and the node's log has the reason under the request's id. unavailable (503, retryable): no_capacity, every network slot of the node is in use; memory_full, a machine the call has to start (made, woken, booted from its disk, resumed, rolled back, built) does not fit in the host's memory beside what the machines that run on it are promised, and nothing paused or idle could be put to sleep to make room for it (memory of the node); drive_full, the call would have a template built and the node's data drive has no room for one (drive of the node); unavailable, the node is shutting down, the sandbox was still starting after 10 minutes, or it did not answer, or it is being moved to this node (with Retry-After: 1); fenced, the node's lease fences the sandbox (Node.lease). moved (409): the sandbox was moved to another node, which to names.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
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.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$