Branch Instance

POST/api/instance/:instance_id/branch

Save one hidden synchronous snapshot and create count children from it. The response snapshot is the previous snapshot for compatibility; each child refs.snapshot_id identifies the new snapshot. Body count/digest take precedence over query parameters when provided. Singular and plural instance routes are aliases.

Request

Path Parameters

• instance_idstringrequired

Query Parameters

• countinteger

  Default: 1

• digeststring | null

application/json

Body

• object | null

  Example: {"instance_metadata":{},"snapshot_metadata":{}}

  • countinteger | null

    Positive body count overrides query count; absent or non-positive falls back to a positive query count, default 1.

  • digeststring | null

    Body digest overrides query digest when non-null.

  • instance_metadataobject | array of object | null

    An object is applied to every child. An array supplies per-child metadata; missing array entries inherit the parent. Null or omitted inherits the parent.

    Any of the following schemas:

    • objectobject

      • Additional propertiesstring
    • array of objectarray of object

      • Itemsobject

        • Additional propertiesstring
    • nullnull
  • snapshot_metadataobject | null

    Metadata for the new snapshot

    • Additional propertiesstring

Responses

200

Successful Response

application/json

Schema

• object
  • instancesarray of objectrequired

    • Itemsobject

      • createdintegerrequired
      • idstringrequired
      • metadataobject

        User provided metadata for the instance

        • Additional propertiesstring
      • networkingobjectrequired

        • http_servicesarray of object

          • Itemsobject

            • auth_modestring

              Allowed values: "none", "api_key"

              Default: "none"

            • namestringrequired
            • portintegerrequired
            • urlstringrequired
        • internal_ipstring | null
      • objectstring

        Value: "instance"

        Default: "instance"

      • refsobjectrequired

        • image_idstringrequired
        • snapshot_idstringrequired
      • specobjectrequired

        • disk_sizeintegerrequired

          Size of the snapshot in megabytes

        • memoryintegerrequired

          Memory of the snaphshot in megabytes

        • vcpusintegerrequired

          VCPU Count of the snaphshot

      • statusstring

        Allowed values: "pending", "ready", "paused", "saving", "error"

        Default: "pending"

      • ttlobjectrequired

        Time to live settings for the instance. If not set, the instance will not expire.

        • ttl_actionstring | null

          Action to take when the instance expires

          Allowed values: "stop", "pause"

        • ttl_expire_atinteger | null

          Unix timestamp of when the instance will expire

        • ttl_secondsinteger | nullrequired

          Time to live in seconds for the instance

      • wake_onobjectrequired

        Wake on settings for the instance. If not set, the instance will not wake on access.

        • wake_on_httpboolean

          Whether to wake the instance on HTTP access

          Default: false

        • wake_on_sshboolean

          Whether to wake the instance on SSH access

          Default: false

  • snapshotobjectrequired

    Previous snapshot, retained for compatibility. New children reference the newly saved hidden snapshot through refs.snapshot_id.

    • createdintegerrequired

      Unix timestamp of when the snapshot was created

    • digeststring | null

      User provided digest of the snapshot content. Useful for caching if the snapshot takes a long time to create.

    • idstringrequired

      Unique identifier for the snapshot, like snapshot_xxxx

    • metadataobject

      User provided metadata for the snapshot

      • Additional propertiesstring
    • objectstring

      Object type, always 'snapshot'

      Value: "snapshot"

      Default: "snapshot"

    • refsobjectrequired

      • image_idstringrequired
    • specobjectrequired

      • disk_sizeintegerrequired

        Size of the snapshot in megabytes

      • memoryintegerrequired

        Memory of the snaphshot in megabytes

      • vcpusintegerrequired

        VCPU Count of the snaphshot

    • statusstringrequired

      Status of the snapshot

      Allowed values: "pending", "ready", "failed", "deleting", "deleted"

    • ttlobjectrequired

      Time to live settings for the snapshot. If not set, the snapshot will not expire.

      • ttl_expire_atinteger | null

        Unix timestamp of when the snapshot will expire

      • ttl_secondsinteger | nullrequired

        Time to live in seconds for the snapshot

400

Malformed input or invalid operation parameters

application/json

Schema

• object
  • detailstringrequired
  • error_codestring

401

Missing or invalid authentication

text/plain

Schema

• string

402

Billing or account restriction

application/json

Schema

• object
  • detailstringrequired
  • error_codestring

403

Authorization or quota refusal

application/json

Schema

• object
  • detailstringrequired
  • error_codestring

404

Instance not found in the authorized scope

application/json

Schema

• object
  • detailstringrequired
  • error_codestring

412

Instance readiness or paused-state precondition failed

application/json

Schema

• object
  • detailstringrequired
  • error_codestring

500

Database or operation failure

application/json

Schema

• object
  • detailstringrequired
  • error_codestring

503

Snapshot admission busy, or an operation dependency unavailable. A typed no-dispatch admission refusal includes Retry-After: 1.

Response Headers

• Retry-After string

  Present only when snapshot admission was refused before dispatch; other 503 failures may omit it.

application/json

Schema

• object
  • detailstringrequired
  • error_codestring