Save a sandbox's system files and storage as a snapshot.

curl --request POST \
  --url https://api.instabox.sh/v1/machines/{id}/snapshots \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "rootOnly": false,
  "forFork": false
}
'

import requests

url = "https://api.instabox.sh/v1/machines/{id}/snapshots"

payload = {
    "name": "<string>",
    "description": "<string>",
    "rootOnly": False,
    "forFork": False
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', description: '<string>', rootOnly: false, forFork: false})
};

fetch('https://api.instabox.sh/v1/machines/{id}/snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instabox.sh/v1/machines/{id}/snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'rootOnly' => false,
    'forFork' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instabox.sh/v1/machines/{id}/snapshots"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"rootOnly\": false,\n  \"forFork\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.instabox.sh/v1/machines/{id}/snapshots")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"rootOnly\": false,\n  \"forFork\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instabox.sh/v1/machines/{id}/snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"rootOnly\": false,\n  \"forFork\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "orgId": "<string>",
  "sourceMachineId": "<string>",
  "sourceSnapshotSeq": 123,
  "status": "pending",
  "template": {
    "id": "<string>",
    "version": "<string>",
    "digest": "<string>",
    "kernel": "<string>"
  },
  "rootSizeBytes": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "error": "<string>",
  "dataSizeBytes": 123,
  "exclusiveBytes": 123,
  "defaultSpec": {
    "vcpus": 123,
    "memMiB": 123,
    "persistentDiskGiB": 123,
    "rootDiskGiB": 123
  },
  "guestUser": "<string>",
  "visibility": "private",
  "publishedAt": "2023-11-07T05:31:56Z",
  "publisherLogin": "<string>"
}

{
  "id": "<string>",
  "name": "<string>",
  "orgId": "<string>",
  "sourceMachineId": "<string>",
  "sourceSnapshotSeq": 123,
  "status": "pending",
  "template": {
    "id": "<string>",
    "version": "<string>",
    "digest": "<string>",
    "kernel": "<string>"
  },
  "rootSizeBytes": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "error": "<string>",
  "dataSizeBytes": 123,
  "exclusiveBytes": 123,
  "defaultSpec": {
    "vcpus": 123,
    "memMiB": 123,
    "persistentDiskGiB": 123,
    "rootDiskGiB": 123
  },
  "guestUser": "<string>",
  "visibility": "private",
  "publishedAt": "2023-11-07T05:31:56Z",
  "publisherLogin": "<string>"
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

Snapshots

Save a sandbox's system files and storage as a snapshot.

A stopped sandbox (fully saved, no operation in progress): synchronous (201) and quick, since no data is copied. A running sandbox, where the server allows live snapshots: 202 with the snapshot pending; the sandbox’s files are frozen briefly while they are copied, and the snapshot becomes ready (or failed) once the copy is uploaded. Unless rootOnly is true, both system files and storage are saved, including credentials under HOME (/data/home). Memory and running programs are not included. API keys: needs one of the scopes images:write.

POST

machines

{id}

snapshots

Save a sandbox's system files and storage as a snapshot.

curl --request POST \
  --url https://api.instabox.sh/v1/machines/{id}/snapshots \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "rootOnly": false,
  "forFork": false
}
'

import requests

url = "https://api.instabox.sh/v1/machines/{id}/snapshots"

payload = {
    "name": "<string>",
    "description": "<string>",
    "rootOnly": False,
    "forFork": False
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', description: '<string>', rootOnly: false, forFork: false})
};

fetch('https://api.instabox.sh/v1/machines/{id}/snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instabox.sh/v1/machines/{id}/snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'rootOnly' => false,
    'forFork' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instabox.sh/v1/machines/{id}/snapshots"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"rootOnly\": false,\n  \"forFork\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.instabox.sh/v1/machines/{id}/snapshots")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"rootOnly\": false,\n  \"forFork\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instabox.sh/v1/machines/{id}/snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"rootOnly\": false,\n  \"forFork\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "orgId": "<string>",
  "sourceMachineId": "<string>",
  "sourceSnapshotSeq": 123,
  "status": "pending",
  "template": {
    "id": "<string>",
    "version": "<string>",
    "digest": "<string>",
    "kernel": "<string>"
  },
  "rootSizeBytes": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "error": "<string>",
  "dataSizeBytes": 123,
  "exclusiveBytes": 123,
  "defaultSpec": {
    "vcpus": 123,
    "memMiB": 123,
    "persistentDiskGiB": 123,
    "rootDiskGiB": 123
  },
  "guestUser": "<string>",
  "visibility": "private",
  "publishedAt": "2023-11-07T05:31:56Z",
  "publisherLogin": "<string>"
}

{
  "id": "<string>",
  "name": "<string>",
  "orgId": "<string>",
  "sourceMachineId": "<string>",
  "sourceSnapshotSeq": 123,
  "status": "pending",
  "template": {
    "id": "<string>",
    "version": "<string>",
    "digest": "<string>",
    "kernel": "<string>"
  },
  "rootSizeBytes": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "error": "<string>",
  "dataSizeBytes": 123,
  "exclusiveBytes": 123,
  "defaultSpec": {
    "vcpus": 123,
    "memMiB": 123,
    "persistentDiskGiB": 123,
    "rootDiskGiB": 123
  },
  "guestUser": "<string>",
  "visibility": "private",
  "publishedAt": "2023-11-07T05:31:56Z",
  "publisherLogin": "<string>"
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

Opaque instabox access token (1 hour). Refresh with /v1/auth/refresh (refresh token valid 30 days, rotates on use).

Headers

Idempotency-Key

string

required

Client-generated key, 1-200 printable ASCII characters, scoped to the user. Same key and same method+path+body returns the original response; same key with a different request returns 409 idempotency_conflict. Records are kept for 7 days.

Required string length: 1 - 200

Pattern: ^[\x21-\x7e]+$

Path Parameters

string

required

Sandbox ID (m_ + 26 lowercase base32 characters).

Pattern: ^m_[a-z2-7]{26}$

Body

application/json

name

string

required

Unique among the caller's snapshots; 1-63 of a-z, 0-9, '-', starting with a letter or digit.

description

string

rootOnly

boolean

default:false

Save the system files only, not the storage (/data).

forFork

boolean

default:false

Saved to fork its source (instabox fork, when the native fork cannot run). For a free source, the server records its max-run window as activity extended it, and a sandbox the same user creates from this snapshot in the next 30 minutes starts with that window, as a native fork does. Names no window.

Response

The snapshot (of a stopped sandbox).

A saved copy of a sandbox (software and files). New sandboxes can be created from it. It belongs to its source sandbox's org: every member of the org sees, uses and deletes it.

string

required

sn_... (im_... for older snapshots).

name

string

required

Unique among the org's live snapshots.

orgId

string

required

The org the snapshot belongs to (its source sandbox's).

sourceMachineId

string

required

sourceSnapshotSeq

integer<int64>

required

The source sandbox's saved state (storage.snapshotSeq) this snapshot was taken from; 0 for a live snapshot of a sandbox that was never stopped.

status

enum<string>

required

ready can be used. A snapshot of a running sandbox is pending while it uploads (its sizes are the sandbox's until then), then ready or failed.

Available options:

pending,

ready,

failed

template

object

required

Show child attributes

rootSizeBytes

integer<int64>

required

The logical size of the system disk a sandbox created from it gets (its provisioned capacity), not the bytes stored: a snapshot is saved sparse and compressed.

createdAt

string<date-time>

required

description

string

error

string

Why a failed snapshot failed.

dataSizeBytes

integer<int64>

The logical size of the storage disk (/data) a sandbox created from it gets, not the bytes stored (the saved data is sparse and compressed); absent for system-files-only snapshots. Sandboxes created from it get at least this much storage.

exclusiveBytes

integer<int64>

deprecated

No longer computed; servers leave it out. (Was the stored bytes only this snapshot references.)

defaultSpec

object

The size a sandbox created from this snapshot gets when the create names none: the caller's plan default for vCPUs and memory (limits.machineSpec, 4 vCPU / 8 GiB on api.instabox.sh), not the source sandbox's size, so a snapshot of a 2/4 box creates a 4/8 one unless the create passes vcpus and memMiB; plus the storage (/data) and system disk sizes the snapshot was saved with, which a created sandbox gets at least. Absent when its template is unknown.

Show child attributes

guestUser

string

The source sandbox's Linux user (Machine.guestUser), which a sandbox created from this snapshot keeps unless the create names another. dev for snapshots of sandboxes from older templates.

visibility

enum<string>

Who can create from the snapshot (docs/community-templates.md): private (the default, its org's members), community (every signed-in account) or official (listed next to the built-in templates). Absent on older servers: treat as private. Handlers do not set community or official yet.

Available options:

private,

community,

official

publishedAt

string<date-time>

When the visibility became community or official.

Who shared or published it.