Pause a running sandbox, keeping its running programs.

curl --request POST \
  --url https://api.instabox.sh/v1/machines/{id}/suspend \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

import requests

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

payload = {}
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({})
};

fetch('https://api.instabox.sh/v1/machines/{id}/suspend', 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}/suspend",
  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([
    
  ]),
  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}/suspend"

	payload := strings.NewReader("{}")

	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}/suspend")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

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

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 = "{}"

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

{
  "id": "<string>",
  "machineId": "<string>",
  "type": "create",
  "state": "queued",
  "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"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "phase": "<string>",
  "forkInherited": true,
  "trigger": "idle",
  "machine": {
    "id": "<string>",
    "name": "<string>",
    "desiredState": "creating",
    "state": "creating",
    "revision": 123,
    "operationId": "<string>",
    "template": {
      "id": "<string>",
      "version": "<string>",
      "digest": "<string>",
      "kernel": "<string>"
    },
    "spec": {
      "vcpus": 123,
      "memMiB": 123,
      "persistentDiskGiB": 123,
      "rootDiskGiB": 123
    },
    "storage": {
      "sizeGiB": 123,
      "mountPath": "/data",
      "persistent": true,
      "synced": true,
      "snapshotSeq": 123
    },
    "runtime": {
      "ready": true,
      "processesPreserved": true
    },
    "autoSuspendAfterSeconds": 123,
    "maxRunMinutes": 1073741823,
    "runStartedAt": "2023-11-07T05:31:56Z",
    "cooldownUntil": "2023-11-07T05:31:56Z",
    "metadata": {},
    "vault": true,
    "guestUser": "alice",
    "orgId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "snapshot": {
      "id": "<string>"
    },
    "image": {
      "id": "<string>"
    },
    "lastError": {
      "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"
    },
    "archiveAt": "2023-11-07T05:31:56Z",
    "deleteAt": "2023-11-07T05:31:56Z",
    "readyAt": "2023-11-07T05:31:56Z",
    "cooldownReason": "abuse_egress_blocklist",
    "abuseLock": {
      "at": "2023-11-07T05:31:56Z",
      "explanation": "<string>",
      "what": "<string>",
      "appeal": "<string>",
      "dst": "<string>",
      "port": 123,
      "kind": "<string>",
      "count": 123,
      "coreShare": 123,
      "process": "<string>",
      "pool": "<string>"
    },
    "autoSuspendedAt": "2023-11-07T05:31:56Z",
    "envNames": [
      "<string>"
    ],
    "free": true,
    "earlyAllowanceEnded": true,
    "oomKills": 123,
    "lastOom": {
      "at": "2023-11-07T05:31:56Z",
      "pid": 123,
      "process": "<string>",
      "rssBytes": 123,
      "anonRssBytes": 123,
      "cgroup": true,
      "uid": 123
    }
  }
}

{
  "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"
  }
}

POST

machines

{id}

suspend

Pause a running sandbox, keeping its running programs.

curl --request POST \
  --url https://api.instabox.sh/v1/machines/{id}/suspend \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

import requests

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

payload = {}
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({})
};

fetch('https://api.instabox.sh/v1/machines/{id}/suspend', 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}/suspend",
  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([
    
  ]),
  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}/suspend"

	payload := strings.NewReader("{}")

	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}/suspend")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

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

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 = "{}"

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

{
  "id": "<string>",
  "machineId": "<string>",
  "type": "create",
  "state": "queued",
  "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"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "phase": "<string>",
  "forkInherited": true,
  "trigger": "idle",
  "machine": {
    "id": "<string>",
    "name": "<string>",
    "desiredState": "creating",
    "state": "creating",
    "revision": 123,
    "operationId": "<string>",
    "template": {
      "id": "<string>",
      "version": "<string>",
      "digest": "<string>",
      "kernel": "<string>"
    },
    "spec": {
      "vcpus": 123,
      "memMiB": 123,
      "persistentDiskGiB": 123,
      "rootDiskGiB": 123
    },
    "storage": {
      "sizeGiB": 123,
      "mountPath": "/data",
      "persistent": true,
      "synced": true,
      "snapshotSeq": 123
    },
    "runtime": {
      "ready": true,
      "processesPreserved": true
    },
    "autoSuspendAfterSeconds": 123,
    "maxRunMinutes": 1073741823,
    "runStartedAt": "2023-11-07T05:31:56Z",
    "cooldownUntil": "2023-11-07T05:31:56Z",
    "metadata": {},
    "vault": true,
    "guestUser": "alice",
    "orgId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "snapshot": {
      "id": "<string>"
    },
    "image": {
      "id": "<string>"
    },
    "lastError": {
      "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"
    },
    "archiveAt": "2023-11-07T05:31:56Z",
    "deleteAt": "2023-11-07T05:31:56Z",
    "readyAt": "2023-11-07T05:31:56Z",
    "cooldownReason": "abuse_egress_blocklist",
    "abuseLock": {
      "at": "2023-11-07T05:31:56Z",
      "explanation": "<string>",
      "what": "<string>",
      "appeal": "<string>",
      "dst": "<string>",
      "port": 123,
      "kind": "<string>",
      "count": 123,
      "coreShare": 123,
      "process": "<string>",
      "pool": "<string>"
    },
    "autoSuspendedAt": "2023-11-07T05:31:56Z",
    "envNames": [
      "<string>"
    ],
    "free": true,
    "earlyAllowanceEnded": true,
    "oomKills": 123,
    "lastOom": {
      "at": "2023-11-07T05:31:56Z",
      "pid": 123,
      "process": "<string>",
      "rssBytes": 123,
      "anonRssBytes": 123,
      "cgroup": true,
      "uid": 123
    }
  }
}

{
  "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

The optional body of POST /v1/machines/{id}/suspend, which takes no fields; any key is refused with 400 unknown_field.

Response

The mutation was accepted (or replayed for the same idempotency key). Poll the operation.

The progress of a change to a sandbox (suspend is pause; restore puts its disks back to a snapshot's; move, admin only, copies it to another host pool). It does not return the request it was queued with (a start's vcpus/memMiB show in the sandbox's spec).

string

required

machineId

string

required

type

enum<string>

required

Available options:

create,

start,

stop,

suspend,

resume,

delete,

restore,

resize,

move

state

enum<string>

required

succeeded and failed are terminal.

Available options:

queued,

running,

succeeded,

failed

error

object | null

required

Show child attributes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

phase

string

Free text progress, e.g. scheduling, booting, waiting_ready, snapshotting.

forkInherited

boolean

On the answer to POST /v1/machines/{id}/fork: the control host that took it keeps the source's delete deadline, idle auto-suspend, max run and metadata, and takes autoSuspendAfterSeconds and maxRunMinutes. Absent: a host from before that (during a rolling control deploy), which gave the fork its defaults with only the request's metadata and deleteAfterSeconds; set the idle auto-suspend and max run with PATCH /v1/machines/{id}.

trigger

enum<string>

Set when instabox started the operation itself: idle (paused when idle), max_run (maximum continuous runtime), memory_pressure (paused, its processes kept, because the host it ran on was running out of memory; the next use wakes it, as after idle), request (wake on use), wake (POST /v1/machines/{id}/wake), timeout, archive, delete_at (the sandbox's deleteAt passed), drain (maintenance by an admin), user_delete (an admin deleted the owner), user_disable (an admin disabled the owner), admin (an admin stopped or paused the sandbox), admin_delete (an admin deleted the sandbox), credit (its free-tier org used up the month's included usage), spend_cap, downgrade, subscription_ended, payment_method (its free workspace has no card on file), members (its free workspace has more members than the free plan allows), early_allowance_ended (paused because the account's early free-sandbox allowance ended and it has more free sandboxes than the free plan runs), abuse_pool (paused because the sandbox tried to connect to a blocked destination on the egress blocklist, such as a crypto-mining pool; a DNS lookup of a listed domain never suspends) or abuse_cpu (paused by the CPU abuse detector: a restricted account's sandbox ran flat out for an hour with no memory use, no public port, nobody using it and a connection to a mining port) or abuse_scan (paused by the flow detector: a restricted account's sandbox swept one port across many hosts, scanned many ports of one host or brute-forced a login port). Absent: a client request.

Available options:

idle,

max_run,

memory_pressure,

timeout,

archive,

delete_at,

drain,

request,

wake,

user_delete,

user_disable,

admin,

admin_delete,

credit,

spend_cap,

downgrade,

subscription_ended,

payment_method,

members,

early_allowance_ended,

abuse_pool,

abuse_cpu,

abuse_scan,

abuse_proxy

machine

object

The sandbox as it is when GET /v1/operations/{id} is read. Included when the operation succeeded, the sandbox still exists, and the caller may read sandboxes (machines:read for API keys). Later operations can change it; it is not a record of the state at completion. Absent otherwise, and from older servers.

Show child attributes