Delete a sandbox, its system files and its storage.

curl --request DELETE \
  --url https://api.instabox.sh/v1/machines/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>'

import requests

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

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

fetch('https://api.instabox.sh/v1/machines/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.delete("https://api.instabox.sh/v1/machines/{id}")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Delete.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'

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

Machines

Delete a sandbox, its system files and its storage.

Snapshots saved from it are kept. API keys: needs one of the scopes machines:delete. Send X-Confirm-Delete with the sandbox’s ID or name. API keys created on or after the server’s cutover (confirmDeleteKeysFrom) must send it: without it the delete is 409 delete_confirmation_required and the sandbox is kept. Older keys may still leave it out; their deletes then carry a Warning response header. Sign-in sessions are not required to send it.

A delete replaces an operation still queued: that operation fails with operation_conflict “cancelled by a delete of this sandbox”, and a sandbox whose queued create never placed it is deleted at once (the delete answers succeeded). A running operation answers 409 operation_conflict naming it; a delete already active is returned as is.

DELETE

machines

{id}

Delete a sandbox, its system files and its storage.

curl --request DELETE \
  --url https://api.instabox.sh/v1/machines/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>'

import requests

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

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

fetch('https://api.instabox.sh/v1/machines/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.delete("https://api.instabox.sh/v1/machines/{id}")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Delete.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'

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]+$

X-Confirm-Delete

string

Guard against deleting the wrong resource: the ID or the exact name of the sandbox or snapshot being deleted. When sent, any other value (empty, another resource's name or ID, or the header twice) is 409 delete_confirmation_required and nothing is deleted; the Idempotency-Key can then be reused. A sandbox delete with an API key created on or after the server's confirmDeleteKeysFrom cutover must send it (without it: the same 409, naming the ID to send); otherwise, without the header, the delete proceeds as before (an API key's response then carries a Warning header). The instabox CLI, the SDKs, the hosted MCP server and the dashboard send it.

Path Parameters

string

required

Sandbox ID (m_ + 26 lowercase base32 characters).

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

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