Skip to content
Navigation

Make a database

A managed Postgres (reports/databases/README.md): a Drive (the data; in the strict tier unless storage.durability says standard: a commit returns once the object store has it) and an app of one stateful service whose instance mounts it, of the platform's Postgres image of the major version (ghcr.io/glacai/postgres-<version>), on the project's network under the database's name. The image makes the cluster on the empty Drive: the role group glac_superuser (the rights of Neon's neon_superuser; no superuser), the owner <database_name>_owner in it, the database; the owner's password is set once PostgreSQL is ready, as a SCRAM verifier, and is in this answer and kept nowhere. The call waits for the first start (150 s at the most) and answers the database ready (its instance's first start is over: PostgreSQL takes connections, the database is there, the owner has the password), or creating (it goes on: GET it). Idempotent by name: a create that names a database of the project answers that one, 200, without its password, where it asks for what it is. The app and the Drive are listed by /v1/apps and /v1/drives with managed_by, and changed through this API alone. A refusal of the Drive's or the app's create (the plan's limits, a name an app has) is the create's, and undoes what was made. Takes write. With tiering.enabled (a paid plan, where the object gateway serves), its branches load pg_lake and glac_tiering and run pgduck_server; where their partitions go and the key that reaches that prefix alone are handed to each running machine, never put in its start.

POST
https://api.glac.ai/v1/databases

Autorisierung

  • apiKeyHTTPrequired

AnfragetextJSONerforderlich

  • namestringrequired

    Lower-case letters, digits and hyphens: its name in the project and on its network, which its app has too.

  • engineoptionalpostgresodernull
  • versionoptionalstring | integer | null

    16, 17 or 18 (the default).

  • regionoptionalstring | null

    na, eu or ap; the project's home where none is given.

  • database_nameoptionalstring | null

    The database in the cluster: a lower-case identifier, 57 characters at the most, not postgres, template0, template1 nor pg_…. Default glacdb; its owner is <database_name>_owner.

  • sizeoptionalobject | null

    Upper bounds, held to the plan's: default 1 vCPU and 1 GiB.

    • vcpusoptionalinteger
    • memory_bytesoptionalinteger
  • storageoptionalobject | null

    Its Drive: size_bytes (default: a Drive's), durability (strict, the default: a commit returns once the object store has it; standard: once the node has it).

    • size_bytesoptionalinteger | null
    • durabilityoptionalstrictoderstandardodernull
  • sleep_after_secondsoptionalinteger | null

    After how long with nothing asked of it its instance is paused, in seconds: from 1 (the default) to 3600 (an hour) on a paid plan. On Free 1, fixed: a Free plan's database is paused a second after its last query and sleeps five minutes later, as Neon's Free scales to zero; another value is refused 400 invalid_field.

    maximum: 3600 · minimum: 1
  • suspend_after_secondsoptionalinteger | null

    After how long paused its instance has its memory saved and sleeps, from 1 to 86400 (300, Neon's five minutes, where none is given): paused, it holds its sessions in memory and a connection is answered in a millisecond or two, its memory metered; asleep, only its storage is, and it still keeps its sessions. Its node holds it to the longest it holds any instance paused (ten minutes). On Free 300, fixed: another value is refused 400 invalid_field.

    maximum: 86400 · minimum: 1
  • wake_daily_atoptionalstring | null

    A time of day in UTC, HH:MM, at which the database is woken every day while it rests, for what waits for a wake (pg_partman's maintenance, a vacuum that is due); it rests again once that is done. Its pg_cron jobs wake it at their own times whatever this says. Null (the default): none.

    pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  • metadataoptionalobject | null
  • tieringoptionalobject | null

    Tiered storage (DB18, Tiger's way): partitions of a table partitioned by range that a policy (glac.add_tiering_policy) or a call (glac.tier_partition) moves become Parquet files in the platform's bucket of the project, still in the same table, read-only, read where glac.enable_tiered_reads is on. On a paid plan alone (Free: 403 paid_plan_required), where the object gateway serves (400 objects_not_served otherwise). Billed by their sizes before the move, $0.02 a GB-month (tiered_bytes); reading them is neither a request nor egress.

    • enabledoptionalboolean | null

      On or off (the default).

  • history_secondsoptionalinteger | null

    How far back its root branch can be restored, or branched from, by a time, in seconds (slice DB8): a day unless the create said (history_seconds), 0 (none) to 30 days on a paid plan, a day on Free (fixed, with a GB of old data at the most: its oldest versions go past it). The last day of it is its root branch's Drive's own window of versions, one every 30 seconds in which it was written (POST /v1/databases/{id}/branches/{branch}/restore with at); further back, and to the second, is its WAL archive's (slice DB5: exact). Not billed: the history of a database's last day is free.

    maximum: 2592000 · minimum: 0

Returns

200

The database the name names, as the create asks for it: without its password.

JSON
  • objectstringrequired
  • idstringrequired
    pattern: ^db-[0-9a-hjkmnp-tv-z]{16}$
  • namestringrequired

    The project's one database of the name; its name on the project's network.

  • enginepostgresrequired
  • version16oder17oder18required

    PostgreSQL's major version.

  • regionnaodereuoderapodernullrequired

    As the create named it; null: the project's home.

  • statuscreatingoderreadyoderfailedoderdeletingoderdeletedrequired
  • errorstring | nullrequired

    Why its first start failed, of a failed one.

  • default_branchobjectrequired

    A branch of a database: a stateful instance and a Drive. The root branch, main, or one of the database's own (slice DB6): a fork of its parent's Drive.

    • objectstringrequired
    • idstringrequired
      pattern: ^br-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired
    • parentstring | nullrequired

      The branch it was made from, by its id: none, of the root branch.

    • endpointstringrequired

      Its endpoint's name, as Neon names one: random, so that no name of the database's or the project's is in an address.

      pattern: ^ep-[a-z]+-[a-z]+-[0-9a-f]{8}$
    • statecreatingoderfailedoderawakeoderpausedoderasleepoderunavailable+2 weitererequired

      Its instance's: awake while it runs, paused while the pause tier holds it in memory, asleep while it is saved; unavailable where its node cannot be reached (or it has no instance); creating and failed while the database has none yet, or failed to make one. deleting and deleted while it is deleted, and once it is.

    • hoststring | nullrequired

      Its public address, its endpoint under its database's region and the zone: <endpoint>.<region>.<zone> (ep-calm-river-1a2b3c4d.na.db.glac.run), port 5432, TLS alone; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • pooler_hoststring | nullrequired

      Its pooler's public address (PgBouncer in its instance): <endpoint>-pooler.<region>.<zone>, port 5432; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • connection_uristring | nullrequired

      How a client connects at its public address: postgresql://<owner>@<host>/<database>?sslmode=require, with the owner's password in the answers that give it (a create, a reset) alone; a branch of its own has its parent's password; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • pooled_uristring | nullrequired

      The same at its pooler: postgresql://<owner>@<pooler_host>/<database>?sslmode=require; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • private_hoststringrequired

      Its name on the project's network: the database's name, of the root branch; <database>-<branch> of a branch of its own.

    • private_uristringrequired

      How the project's sandboxes and services connect: postgresql://<owner>@<private_host>:5432/<database>, with the owner's password in the answers that give it (a create, a reset) alone. A branch of its own has its parent's roles and passwords.

    • sizeobjectrequired

      Its instance's upper bounds; what it uses is billed.

      • vcpusintegerrequired
      • memory_bytesintegerrequired
    • storageobjectrequired

      Its Drive (GET /v1/drives/{drive_id}).

      • drive_idstring | nullrequired
      • size_bytesinteger | nullrequired

        As the create gave it; null: the Drive's default.

      • durabilitystrictoderstandardrequired

        Its Drive's tier, as its node says it: strict (a commit returns once the object store has it) or standard.

      • used_bytesinteger | nullrequired

        What its Drive holds, as its node said last; null before it said.

      • billed_bytesinteger | nullrequired

        What its Drive is billed for keeping: what it holds, of the root branch; of a branch of its own, what it changed since the fork (what its newest version reads from objects of its own in the store, as the collector last worked it out), never more than what it holds: 0 until the collector said. Null before anything was said.

    • app_idstring | nullrequired

      Its app (GET /v1/apps/{app_id}), once made.

    • instance_idstring | nullrequired

      Its instance, a sandbox (/v1/sandboxes/{instance_id}: read it, run a command in it), where it has one.

    • start_commandrequired

      How its server runs, as its instance's node says (the instance's start_command, SandboxStartCommand in sandboxd/openapi/openapi.json): status (running; restarting: it ended, and is started again at restarting_at; exited), restarts (how often it was started again in its machine after it ended, with its data as it was: PostgreSQL recovers by its WAL), last_exit (status, signal, at), restarting_at. Each start is also an event instance.restarted. Null where it has no instance, or its node said nothing of it yet.

      Eines der folgenden:

      • 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.

          Eines der folgenden:

          • 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
    • expires_atstring | nullrequired

      When it is deleted by itself (once no branch made of it is there): never, of the root branch, and of one made without it.

      format: date-time
    • created_atstringrequired
      format: date-time
  • database_namestringrequired

    The database in the cluster (glacdb unless the create named another).

  • rolestringrequired

    Its owner, <database_name>_owner: a member of glac_superuser, no superuser.

  • passwordstring | nullrequired

    The owner's password, in the answers to a create and a reset alone; null otherwise. Kept nowhere.

  • sleep_after_secondsintegerrequired

    After how long without anything asked of it its instance sleeps.

  • suspend_after_secondsinteger | nullrequired

    After how long paused its instance (and each branch's) has its memory saved and sleeps (its node holds it to ten minutes). Null for a database made before it: its node's longest.

  • wake_daily_atstring | nullrequired

    The time of day in UTC at which it is woken every day while it rests (each branch too); null: none.

  • metadataMap vonstringrequired
  • final_snapshotobject | nullrequired

    Of a deleted one: the snapshot of its Drive kept, a Drive snapshot of the project's, and when it is deleted.

    • idstringrequired
    • expires_atstring | nullrequired
  • created_atstringrequired
    format: date-time
  • tieringobjectrequired

    Tiered storage: whether it is on, and what it bills by now.

    • enabledbooleanrequired
    • tiered_bytesintegerrequired

      What tiered storage bills by now: the sizes before the moves (pg_table_size of each partition as it was swapped) of the files its branches point at as tiered, each file once however many branches point at it, and never less than what its prefix holds in the object store. 0 while nothing is tiered.

  • history_secondsintegerrequired

    How far back its root branch can be restored, or branched from, by a time (slice DB8): a day unless the create said (history_seconds), 0 (none) to 30 days on a paid plan, a day on Free (fixed, with a GB of old data at the most: its oldest versions go past it). The last day of it is its root branch's Drive's own window of versions, one every 30 seconds in which it was written (POST /v1/databases/{id}/branches/{branch}/restore with at); further back, and to the second, is its WAL archive's (slice DB5: exact). Not billed: the history of a database's last day is free.

    maximum: 2592000 · minimum: 0
  • historyobjectrequired

    Its history as it stands.

    • fromstring | nullrequired

      The earliest time its root branch can be restored to now, by its Drive's window or its WAL archive, whichever reaches further back (within history_seconds); its making, where its WAL is archived (its archive's first base is the image's seed it started from); otherwise null until its Drive's window has a version (about three minutes after the database is ready).

      format: date-time
    • stored_bytesintegerrequired

      What the versions of its root branch's window keep that its newest version does not (not billed: its last day is free).

      format: int64 · minimum: 0
    • gapsArray vonobjectrequired

      The gaps of its WAL archive within its history, the oldest first: where its archive's gateway refused its WAL so long that more of it waited than its Drive keeps for the log, and the WAL was given up so that the database stayed up. A time in one is restored only from its root branch's Drive's window (a whole minute, or a version's own time, while the window holds it); to the second or exact, it is refused (400 invalid_history), never taken from a version before it. Empty: none.

      • fromstringrequired

        When the WAL given up began.

        format: date-time
      • tostring | nullrequired

        Until when the archive restores no time: the end of the first base taken after the gap (taken as soon as the archive takes the WAL again, while the database is awake); null until there is one.

        format: date-time
      • from_lsnstringrequired

        Where in the log the WAL given up begins (0/5000000).

      • to_lsnstringrequired

        Where it ends: the archive holds the WAL again from there.

201

The database, ready (or creating, its first start under way), with the owner's password and the private connection string with it.

JSON
  • objectstringrequired
  • idstringrequired
    pattern: ^db-[0-9a-hjkmnp-tv-z]{16}$
  • namestringrequired

    The project's one database of the name; its name on the project's network.

  • enginepostgresrequired
  • version16oder17oder18required

    PostgreSQL's major version.

  • regionnaodereuoderapodernullrequired

    As the create named it; null: the project's home.

  • statuscreatingoderreadyoderfailedoderdeletingoderdeletedrequired
  • errorstring | nullrequired

    Why its first start failed, of a failed one.

  • default_branchobjectrequired

    A branch of a database: a stateful instance and a Drive. The root branch, main, or one of the database's own (slice DB6): a fork of its parent's Drive.

    • objectstringrequired
    • idstringrequired
      pattern: ^br-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired
    • parentstring | nullrequired

      The branch it was made from, by its id: none, of the root branch.

    • endpointstringrequired

      Its endpoint's name, as Neon names one: random, so that no name of the database's or the project's is in an address.

      pattern: ^ep-[a-z]+-[a-z]+-[0-9a-f]{8}$
    • statecreatingoderfailedoderawakeoderpausedoderasleepoderunavailable+2 weitererequired

      Its instance's: awake while it runs, paused while the pause tier holds it in memory, asleep while it is saved; unavailable where its node cannot be reached (or it has no instance); creating and failed while the database has none yet, or failed to make one. deleting and deleted while it is deleted, and once it is.

    • hoststring | nullrequired

      Its public address, its endpoint under its database's region and the zone: <endpoint>.<region>.<zone> (ep-calm-river-1a2b3c4d.na.db.glac.run), port 5432, TLS alone; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • pooler_hoststring | nullrequired

      Its pooler's public address (PgBouncer in its instance): <endpoint>-pooler.<region>.<zone>, port 5432; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • connection_uristring | nullrequired

      How a client connects at its public address: postgresql://<owner>@<host>/<database>?sslmode=require, with the owner's password in the answers that give it (a create, a reset) alone; a branch of its own has its parent's password; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • pooled_uristring | nullrequired

      The same at its pooler: postgresql://<owner>@<pooler_host>/<database>?sslmode=require; where an edge serves PostgreSQL (the control plane's --database-zone), null where none does or the database has no region to be named under.

    • private_hoststringrequired

      Its name on the project's network: the database's name, of the root branch; <database>-<branch> of a branch of its own.

    • private_uristringrequired

      How the project's sandboxes and services connect: postgresql://<owner>@<private_host>:5432/<database>, with the owner's password in the answers that give it (a create, a reset) alone. A branch of its own has its parent's roles and passwords.

    • sizeobjectrequired

      Its instance's upper bounds; what it uses is billed.

      • vcpusintegerrequired
      • memory_bytesintegerrequired
    • storageobjectrequired

      Its Drive (GET /v1/drives/{drive_id}).

      • drive_idstring | nullrequired
      • size_bytesinteger | nullrequired

        As the create gave it; null: the Drive's default.

      • durabilitystrictoderstandardrequired

        Its Drive's tier, as its node says it: strict (a commit returns once the object store has it) or standard.

      • used_bytesinteger | nullrequired

        What its Drive holds, as its node said last; null before it said.

      • billed_bytesinteger | nullrequired

        What its Drive is billed for keeping: what it holds, of the root branch; of a branch of its own, what it changed since the fork (what its newest version reads from objects of its own in the store, as the collector last worked it out), never more than what it holds: 0 until the collector said. Null before anything was said.

    • app_idstring | nullrequired

      Its app (GET /v1/apps/{app_id}), once made.

    • instance_idstring | nullrequired

      Its instance, a sandbox (/v1/sandboxes/{instance_id}: read it, run a command in it), where it has one.

    • start_commandrequired

      How its server runs, as its instance's node says (the instance's start_command, SandboxStartCommand in sandboxd/openapi/openapi.json): status (running; restarting: it ended, and is started again at restarting_at; exited), restarts (how often it was started again in its machine after it ended, with its data as it was: PostgreSQL recovers by its WAL), last_exit (status, signal, at), restarting_at. Each start is also an event instance.restarted. Null where it has no instance, or its node said nothing of it yet.

      Eines der folgenden:

      • 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.

          Eines der folgenden:

          • 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
    • expires_atstring | nullrequired

      When it is deleted by itself (once no branch made of it is there): never, of the root branch, and of one made without it.

      format: date-time
    • created_atstringrequired
      format: date-time
  • database_namestringrequired

    The database in the cluster (glacdb unless the create named another).

  • rolestringrequired

    Its owner, <database_name>_owner: a member of glac_superuser, no superuser.

  • passwordstring | nullrequired

    The owner's password, in the answers to a create and a reset alone; null otherwise. Kept nowhere.

  • sleep_after_secondsintegerrequired

    After how long without anything asked of it its instance sleeps.

  • suspend_after_secondsinteger | nullrequired

    After how long paused its instance (and each branch's) has its memory saved and sleeps (its node holds it to ten minutes). Null for a database made before it: its node's longest.

  • wake_daily_atstring | nullrequired

    The time of day in UTC at which it is woken every day while it rests (each branch too); null: none.

  • metadataMap vonstringrequired
  • final_snapshotobject | nullrequired

    Of a deleted one: the snapshot of its Drive kept, a Drive snapshot of the project's, and when it is deleted.

    • idstringrequired
    • expires_atstring | nullrequired
  • created_atstringrequired
    format: date-time
  • tieringobjectrequired

    Tiered storage: whether it is on, and what it bills by now.

    • enabledbooleanrequired
    • tiered_bytesintegerrequired

      What tiered storage bills by now: the sizes before the moves (pg_table_size of each partition as it was swapped) of the files its branches point at as tiered, each file once however many branches point at it, and never less than what its prefix holds in the object store. 0 while nothing is tiered.

  • history_secondsintegerrequired

    How far back its root branch can be restored, or branched from, by a time (slice DB8): a day unless the create said (history_seconds), 0 (none) to 30 days on a paid plan, a day on Free (fixed, with a GB of old data at the most: its oldest versions go past it). The last day of it is its root branch's Drive's own window of versions, one every 30 seconds in which it was written (POST /v1/databases/{id}/branches/{branch}/restore with at); further back, and to the second, is its WAL archive's (slice DB5: exact). Not billed: the history of a database's last day is free.

    maximum: 2592000 · minimum: 0
  • historyobjectrequired

    Its history as it stands.

    • fromstring | nullrequired

      The earliest time its root branch can be restored to now, by its Drive's window or its WAL archive, whichever reaches further back (within history_seconds); its making, where its WAL is archived (its archive's first base is the image's seed it started from); otherwise null until its Drive's window has a version (about three minutes after the database is ready).

      format: date-time
    • stored_bytesintegerrequired

      What the versions of its root branch's window keep that its newest version does not (not billed: its last day is free).

      format: int64 · minimum: 0
    • gapsArray vonobjectrequired

      The gaps of its WAL archive within its history, the oldest first: where its archive's gateway refused its WAL so long that more of it waited than its Drive keeps for the log, and the WAL was given up so that the database stayed up. A time in one is restored only from its root branch's Drive's window (a whole minute, or a version's own time, while the window holds it); to the second or exact, it is refused (400 invalid_history), never taken from a version before it. Empty: none.

      • fromstringrequired

        When the WAL given up began.

        format: date-time
      • tostring | nullrequired

        Until when the archive restores no time: the end of the first base taken after the gap (taken as soon as the archive takes the WAL again, while the database is awake); null until there is one.

        format: date-time
      • from_lsnstringrequired

        Where in the log the WAL given up begins (0/5000000).

      • to_lsnstringrequired

        Where it ends: the archive holds the WAL again from there.

400

invalid_json; unknown_field (of a later slice too: suspend_after_seconds, DB9; allowed_ips, DB3); missing_field: no name; invalid_name; unknown_version: a major version that is not offered (16, 17, 18); invalid_field (engine other than postgres, database_name, size, storage, sleep_after_seconds, metadata; history_seconds not 0 to 2592000, or not 86400 on Free); unknown_region; unknown_parameter. invalid_field of tiering.enabled (true or false), unknown_field of tiering.…. objects_not_served: tiering.enabled where this control plane has no object gateway.
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.

      Eines der folgenden:

      • 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 vonobject

    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 vonstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsArray vonobjectrequired

      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).

      • treatmentdoneoderadaptedoderignoredoderrefusedrequired

        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 vonobjectrequired

      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-
      • statuscreatedoderchangedoderunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceoderjobrequired

        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 vonobjectrequired
        • 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).

        • treatmentdoneoderadaptedoderignoredoderrefusedrequired

          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

          Eines der folgenden:

          • 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.

          Eines der folgenden:

          • 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.

            Eines der folgenden:

            • string
            • array<string>
        • envMap vonstringrequired
        • secretsMap vonstringrequired

          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 vonobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesArray vonobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          Eines der folgenden:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsArray vonstringrequired

          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

          Eines der folgenden:

          • 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).

          • defaultoptionalallowoderdenyodernull
          • 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 vonstringrequired
        • 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 vonobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesArray vonstringrequired
          • endpoint_modestringrequired
        • drivesoptionalArray vonobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalArray vonobject

          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.

          Eines der folgenden:

          • Runtime
            • ulimitsMap vonRuntimeLimitGivenrequired
            • sysctlsMap vonstringrequired
            • tmpfsArray vonobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversArray vonstringrequired
              • searchArray vonstringrequired
              • optionsArray vonstringrequired
            • 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 vonobjectrequired

      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_makeodermadeoderthereoderexternalrequired

        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 vonstringrequired
    • secretsArray vonobjectrequired

      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 vonstringrequired
    • left_outArray vonobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesArray vonstringrequired
    • absentArray vonstringrequired

      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 vonobject

    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.

      Eines der folgenden:

      • 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 vonobject

    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 vonstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsArray vonobjectrequired

      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).

      • treatmentdoneoderadaptedoderignoredoderrefusedrequired

        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 vonobjectrequired

      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-
      • statuscreatedoderchangedoderunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceoderjobrequired

        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 vonobjectrequired
        • 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).

        • treatmentdoneoderadaptedoderignoredoderrefusedrequired

          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

          Eines der folgenden:

          • 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.

          Eines der folgenden:

          • 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.

            Eines der folgenden:

            • string
            • array<string>
        • envMap vonstringrequired
        • secretsMap vonstringrequired

          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 vonobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesArray vonobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          Eines der folgenden:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsArray vonstringrequired

          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

          Eines der folgenden:

          • 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).

          • defaultoptionalallowoderdenyodernull
          • 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 vonstringrequired
        • 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 vonobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesArray vonstringrequired
          • endpoint_modestringrequired
        • drivesoptionalArray vonobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalArray vonobject

          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.

          Eines der folgenden:

          • Runtime
            • ulimitsMap vonRuntimeLimitGivenrequired
            • sysctlsMap vonstringrequired
            • tmpfsArray vonobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversArray vonstringrequired
              • searchArray vonstringrequired
              • optionsArray vonstringrequired
            • 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 vonobjectrequired

      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_makeodermadeoderthereoderexternalrequired

        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 vonstringrequired
    • secretsArray vonobjectrequired

      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 vonstringrequired
    • left_outArray vonobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesArray vonstringrequired
    • absentArray vonstringrequired

      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 vonobject

    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.

      Eines der folgenden:

      • 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 vonobject

    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 vonstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsArray vonobjectrequired

      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).

      • treatmentdoneoderadaptedoderignoredoderrefusedrequired

        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 vonobjectrequired

      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-
      • statuscreatedoderchangedoderunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceoderjobrequired

        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 vonobjectrequired
        • 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).

        • treatmentdoneoderadaptedoderignoredoderrefusedrequired

          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

          Eines der folgenden:

          • 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.

          Eines der folgenden:

          • 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.

            Eines der folgenden:

            • string
            • array<string>
        • envMap vonstringrequired
        • secretsMap vonstringrequired

          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 vonobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesArray vonobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          Eines der folgenden:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsArray vonstringrequired

          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

          Eines der folgenden:

          • 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).

          • defaultoptionalallowoderdenyodernull
          • 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 vonstringrequired
        • 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 vonobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesArray vonstringrequired
          • endpoint_modestringrequired
        • drivesoptionalArray vonobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalArray vonobject

          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.

          Eines der folgenden:

          • Runtime
            • ulimitsMap vonRuntimeLimitGivenrequired
            • sysctlsMap vonstringrequired
            • tmpfsArray vonobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversArray vonstringrequired
              • searchArray vonstringrequired
              • optionsArray vonstringrequired
            • 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 vonobjectrequired

      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_makeodermadeoderthereoderexternalrequired

        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 vonstringrequired
    • secretsArray vonobjectrequired

      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 vonstringrequired
    • left_outArray vonobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesArray vonstringrequired
    • absentArray vonstringrequired

      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 vonobject

    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, needs_api_key, account_held (as everywhere); product_not_open: Serverless Database is not open on this platform yet (--products): nothing new of it is made. plan_cap_reached: the free plan's databases (param): databases, one more than the account may have (100); storage.size_bytes, one that would hold more than 1 GB (a free database's Drive is 1 GB, given where the create gives no size); account_database_cu_hours, the account's databases computed the free plan's 300 CU-hours this calendar month. paid_plan_required: tiering.enabled on the free plan.
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.

      Eines der folgenden:

      • 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 vonobject

    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 vonstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsArray vonobjectrequired

      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).

      • treatmentdoneoderadaptedoderignoredoderrefusedrequired

        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 vonobjectrequired

      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-
      • statuscreatedoderchangedoderunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceoderjobrequired

        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 vonobjectrequired
        • 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).

        • treatmentdoneoderadaptedoderignoredoderrefusedrequired

          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

          Eines der folgenden:

          • 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.

          Eines der folgenden:

          • 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.

            Eines der folgenden:

            • string
            • array<string>
        • envMap vonstringrequired
        • secretsMap vonstringrequired

          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 vonobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesArray vonobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          Eines der folgenden:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsArray vonstringrequired

          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

          Eines der folgenden:

          • 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).

          • defaultoptionalallowoderdenyodernull
          • 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 vonstringrequired
        • 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 vonobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesArray vonstringrequired
          • endpoint_modestringrequired
        • drivesoptionalArray vonobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalArray vonobject

          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.

          Eines der folgenden:

          • Runtime
            • ulimitsMap vonRuntimeLimitGivenrequired
            • sysctlsMap vonstringrequired
            • tmpfsArray vonobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversArray vonstringrequired
              • searchArray vonstringrequired
              • optionsArray vonstringrequired
            • 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 vonobjectrequired

      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_makeodermadeoderthereoderexternalrequired

        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 vonstringrequired
    • secretsArray vonobjectrequired

      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 vonstringrequired
    • left_outArray vonobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesArray vonstringrequired
    • absentArray vonstringrequired

      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 vonobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

409

name_taken: the project has a database of the name that is not what the create asks for, or an app or a Drive has the name (the Drive is <name>-data).
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.

      Eines der folgenden:

      • 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 vonobject

    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 vonstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsArray vonobjectrequired

      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).

      • treatmentdoneoderadaptedoderignoredoderrefusedrequired

        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 vonobjectrequired

      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-
      • statuscreatedoderchangedoderunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceoderjobrequired

        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 vonobjectrequired
        • 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).

        • treatmentdoneoderadaptedoderignoredoderrefusedrequired

          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

          Eines der folgenden:

          • 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.

          Eines der folgenden:

          • 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.

            Eines der folgenden:

            • string
            • array<string>
        • envMap vonstringrequired
        • secretsMap vonstringrequired

          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 vonobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesArray vonobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          Eines der folgenden:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsArray vonstringrequired

          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

          Eines der folgenden:

          • 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).

          • defaultoptionalallowoderdenyodernull
          • 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 vonstringrequired
        • 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 vonobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesArray vonstringrequired
          • endpoint_modestringrequired
        • drivesoptionalArray vonobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalArray vonobject

          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.

          Eines der folgenden:

          • Runtime
            • ulimitsMap vonRuntimeLimitGivenrequired
            • sysctlsMap vonstringrequired
            • tmpfsArray vonobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversArray vonstringrequired
              • searchArray vonstringrequired
              • optionsArray vonstringrequired
            • 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 vonobjectrequired

      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_makeodermadeoderthereoderexternalrequired

        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 vonstringrequired
    • secretsArray vonobjectrequired

      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 vonstringrequired
    • left_outArray vonobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesArray vonstringrequired
    • absentArray vonstringrequired

      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 vonobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

503

no_capacity (retryable): no node has room for the Drive, or none copies Drives to an object store (the strict tier).
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.

      Eines der folgenden:

      • 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 vonobject

    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 vonstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsArray vonobjectrequired

      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).

      • treatmentdoneoderadaptedoderignoredoderrefusedrequired

        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 vonobjectrequired

      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-
      • statuscreatedoderchangedoderunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceoderjobrequired

        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 vonobjectrequired
        • 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).

        • treatmentdoneoderadaptedoderignoredoderrefusedrequired

          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

          Eines der folgenden:

          • 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.

          Eines der folgenden:

          • 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.

            Eines der folgenden:

            • string
            • array<string>
        • envMap vonstringrequired
        • secretsMap vonstringrequired

          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 vonobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesArray vonobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          Eines der folgenden:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsArray vonstringrequired

          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

          Eines der folgenden:

          • 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).

          • defaultoptionalallowoderdenyodernull
          • 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 vonstringrequired
        • 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 vonobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesArray vonstringrequired
          • endpoint_modestringrequired
        • drivesoptionalArray vonobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalArray vonobject

          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.

          Eines der folgenden:

          • Runtime
            • ulimitsMap vonRuntimeLimitGivenrequired
            • sysctlsMap vonstringrequired
            • tmpfsArray vonobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversArray vonstringrequired
              • searchArray vonstringrequired
              • optionsArray vonstringrequired
            • 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 vonobjectrequired

      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_makeodermadeoderthereoderexternalrequired

        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 vonstringrequired
    • secretsArray vonobjectrequired

      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 vonstringrequired
    • left_outArray vonobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesArray vonstringrequired
    • absentArray vonstringrequired

      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 vonobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

Suchbegriff eingeben…

↑↓ navigieren↵ auswählenEsc schließen