Box lifecycle

Stop and archive box

Stop active work and archive/snapshot the box for later resume or fork.

A stop always saves the box’s disk first. If that save is failing, the stop is refused and the box keeps running so your work is not discarded, we retry automatically and email you. You are not billed for time spent in that state.

Set force: true to stop anyway, accepting the loss of everything written since the last successful snapshot. This is irreversible; only reach for it after a stop has already failed.

POST

boxes

{boxId}

stop

Stop and archive box

curl --request POST \
  --url https://ascii.dev/api/box/v1/boxes/{boxId}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": false
}'

import requests

url = "https://ascii.dev/api/box/v1/boxes/{boxId}/stop"

payload = { "force": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({force: false})
};

fetch('https://ascii.dev/api/box/v1/boxes/{boxId}/stop', 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://ascii.dev/api/box/v1/boxes/{boxId}/stop",
  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([
    'force' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://ascii.dev/api/box/v1/boxes/{boxId}/stop"

	payload := strings.NewReader("{\n  \"force\": false\n}")

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

	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://ascii.dev/api/box/v1/boxes/{boxId}/stop")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ascii.dev/api/box/v1/boxes/{boxId}/stop")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"force\": false\n}"

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

{
  "ok": true,
  "type": "box.stopping",
  "id": "bx_23456789",
  "status": "archiving",
  "box": {
    "id": "bx_23456789",
    "name": "Box 2026-05-31 12:00",
    "state": "archiving",
    "desktopAvailable": true,
    "snapshotAvailable": false
  }
}

{
  "ok": false,
  "type": "box.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Box bearer token in the form box_.... Service API keys authenticate Box operations.

Path Parameters

boxId

string

required

Public Box id returned by create/list/get box calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Body

application/json

Options for stopping a Box.

force

boolean

default:false

Stop the box even if its disk cannot be snapshotted. Everything written since the last successful snapshot is permanently LOST. Without this, a box whose snapshot pipeline is failing is left running rather than discarding your work, and you are not billed for that time. Only use this after a stop has already been refused.

Response

Box archival started or already in progress.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Example:

"box.stopping"

string

required

status

string

required

Example:

"archiving"

box

object | null

Show child attributes

Stop and archive box

curl --request POST \
  --url https://ascii.dev/api/box/v1/boxes/{boxId}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": false
}'

import requests

url = "https://ascii.dev/api/box/v1/boxes/{boxId}/stop"

payload = { "force": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({force: false})
};

fetch('https://ascii.dev/api/box/v1/boxes/{boxId}/stop', 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://ascii.dev/api/box/v1/boxes/{boxId}/stop",
  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([
    'force' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://ascii.dev/api/box/v1/boxes/{boxId}/stop"

	payload := strings.NewReader("{\n  \"force\": false\n}")

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

	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://ascii.dev/api/box/v1/boxes/{boxId}/stop")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ascii.dev/api/box/v1/boxes/{boxId}/stop")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"force\": false\n}"

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

{
  "ok": true,
  "type": "box.stopping",
  "id": "bx_23456789",
  "status": "archiving",
  "box": {
    "id": "bx_23456789",
    "name": "Box 2026-05-31 12:00",
    "state": "archiving",
    "desktopAvailable": true,
    "snapshotAvailable": false
  }
}

{
  "ok": false,
  "type": "box.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}