Sandboxes

Partially update a running sandbox

Applies a partial update to a running sandbox. Each top-level field in the request body is optional; only fields that are present are applied. Omitted top-level fields are left unchanged. Nested objects are full replacements when present — to clear a list, send it as an empty array.

At least one top-level field must be present, otherwise the request is rejected with 400. Unknown top-level fields are also rejected with 400 so typos surface as errors instead of silent no-ops.

Currently patchable fields

network — replaces the egress allow/deny rules. The sandbox must be in the active state; patching a paused sandbox returns 409. Rules take effect immediately and are persisted so they survive a future pause/resume cycle.
metadata — replaces the sandbox’s metadata tags. Can be updated regardless of sandbox state (active, paused).
auto_delete_seconds — sets or clears (null) the garbage-collection window for the paused state. Can be updated regardless of sandbox state. When applied to an already-paused sandbox, the deletion deadline counts from the moment of this request — never retroactively from when the sandbox paused — so you always get the full window.
timeout_seconds — sets or clears (null) the auto-pause timeout. Can be updated regardless of sandbox state; on a paused sandbox it applies to the next active session. The timeout is evaluated against the current active session, so lowering it below already-elapsed time pauses the sandbox promptly.
idle_timeout_seconds — sets or clears (null) the idle timeout. Can be updated regardless of sandbox state.
preview_access — sets the default access mode for ports published in the future. Existing per-port modes are unchanged. It also moves an older legacy_public sandbox to strict routing. legacy_public cannot be selected.

PATCH

sandboxes

{sandbox_id}

Partially update a running sandbox

curl --request PATCH \
  --url https://api.superserve.ai/sandboxes/{sandbox_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "metadata": {
    "env": "prod",
    "owner": "agent-7"
  }
}
'

import requests

url = "https://api.superserve.ai/sandboxes/{sandbox_id}"

payload = { "metadata": {
        "env": "prod",
        "owner": "agent-7"
    } }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {env: 'prod', owner: 'agent-7'}})
};

fetch('https://api.superserve.ai/sandboxes/{sandbox_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.superserve.ai/sandboxes/{sandbox_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'env' => 'prod',
        'owner' => 'agent-7'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-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.superserve.ai/sandboxes/{sandbox_id}"

	payload := strings.NewReader("{\n  \"metadata\": {\n    \"env\": \"prod\",\n    \"owner\": \"agent-7\"\n  }\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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.patch("https://api.superserve.ai/sandboxes/{sandbox_id}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"env\": \"prod\",\n    \"owner\": \"agent-7\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.superserve.ai/sandboxes/{sandbox_id}")

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {\n    \"env\": \"prod\",\n    \"owner\": \"agent-7\"\n  }\n}"

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

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

sandbox_id

string

required

The unique identifier of the sandbox. Public sandbox ID: a bare UUID, or the region-tagged form sb-<region>-<uuid> (e.g. sb-use-1b4e28ba-…). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably.

Pattern: ^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Body

application/json

Partial update body for PATCH /sandboxes/{sandbox_id}. Each top-level field is optional; only fields that are present are applied. Omitted fields are left unchanged. Nested objects are full replacements when present — to clear a list, send it as an empty array.

At least one top-level field must be set, otherwise the request is rejected with 400. Unknown fields are also rejected with 400.

network

object

Replace the sandbox's egress rules. The sandbox must be in the active state. The provided allow_out and deny_out lists fully replace whatever was previously configured.

Show child attributes

metadata

object

Replace the sandbox's metadata tags. Fully replaces the existing metadata — omitted keys are removed. Can be patched regardless of sandbox state. Same validation limits as on create (64 keys, 256-byte keys, 2 KB values, 16 KB total).

Show child attributes

auto_delete_seconds

integer<int32> | null

Set or clear the garbage-collection window for the paused state. Once the sandbox has been continuously paused for this many seconds it is deleted automatically. 0 deletes as soon as the sandbox pauses; null disables auto-delete. On an already-paused sandbox the deadline counts from this request, so the sandbox gets the full window. Maximum 2592000 (30 days).

Required range: 0 <= x <= 2592000

timeout_seconds

integer<int32> | null

Set or clear the auto-pause timeout. Same semantics as on create; null disables auto-pause. Evaluated against the current active session, so lowering it below already-elapsed time pauses the sandbox promptly. Maximum 604800 (7 days).

Required range: 1 <= x <= 604800

idle_timeout_seconds

integer<int32> | null

Set or clear the idle timeout. Same semantics as on create; null disables idle pausing.

Required range: 60 <= x <= 604800

preview_access

enum<string>

Set the default access for newly published ports and move a legacy sandbox to strict routing. Existing per-port modes are unchanged. legacy_public cannot be selected through the API.

Available options:

public,

private

Response

Patch applied

⌘I

Partially update a running sandbox

curl --request PATCH \
  --url https://api.superserve.ai/sandboxes/{sandbox_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "metadata": {
    "env": "prod",
    "owner": "agent-7"
  }
}
'

import requests

url = "https://api.superserve.ai/sandboxes/{sandbox_id}"

payload = { "metadata": {
        "env": "prod",
        "owner": "agent-7"
    } }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {env: 'prod', owner: 'agent-7'}})
};

fetch('https://api.superserve.ai/sandboxes/{sandbox_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.superserve.ai/sandboxes/{sandbox_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'env' => 'prod',
        'owner' => 'agent-7'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-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.superserve.ai/sandboxes/{sandbox_id}"

	payload := strings.NewReader("{\n  \"metadata\": {\n    \"env\": \"prod\",\n    \"owner\": \"agent-7\"\n  }\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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.patch("https://api.superserve.ai/sandboxes/{sandbox_id}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"env\": \"prod\",\n    \"owner\": \"agent-7\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.superserve.ai/sandboxes/{sandbox_id}")

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {\n    \"env\": \"prod\",\n    \"owner\": \"agent-7\"\n  }\n}"

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

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "action_url": "https://console.superserve.ai/plan-usage"
  }
}

Sandboxes

Snapshots

Exec

Files

Templates

Secrets

Team Management

Activity

Partially update a running sandbox

Currently patchable fields

Authorizations

Path Parameters

Body

Response