---
title: "Update box"
method: PATCH
path: "/boxes/{boxId}"
tags: ["Box"]
---

# Update box

`PATCH /boxes/{boxId}`

## Request body

- UpdateBoxRequest
  - `name` string — New display name. Empty strings are rejected; longer names are truncated to 120 chars by the backend.
  - `ttlSeconds` integer, nullable — New archival TTL. `null` disables auto-stop.
  - `subdomain` string — Rename the Box's stable subdomain (the `<subdomain>.on.ascii.dev` label). Lowercase letters, digits and hyphens; no leading/trailing/double hyphens; cannot end in `-desktop` or `-<number>` (reserved for the desktop and hosted-port URLs). Must be globally unique. The base URL, desktop URL and every live `host <port>` URL are re-pointed to the new name with no downtime and their access tokens preserved; the old URLs stop resolving. On a transient routing error the rename is saved but returns 502 `gateway_error` - retry with the same value to finish activating routes.

## Response `200`

Updated box details.

- BoxInfoResponse
  - `ok` boolean, required
  - `type` string, required — Stable success envelope discriminator added by v1.
  - `box` Box, required
    - `id` string, required
    - `name` string, required
    - `state` 'init' | 'provisioning' | 'provisioned' | 'cloning' | 'ready' | 'idle' | 'running' | 'archiving' | 'archived' | 'error', required
    - `url` string, uri, nullable — Machine URL when assigned.
    - `ip` string, nullable — Machine IPv4 address when assigned.
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable
    - `archiveAfter` string, date-time, nullable — Automatic archival time, or null when auto-stop is disabled.
    - `desktopAvailable` boolean, required
    - `desktopUrl` string, uri, nullable — Secret-bearing desktop stream URL when available. Redact from logs.
    - `snapshotAvailable` boolean, required
    - `snapshotCompletedAt` string, date-time, nullable — Timestamp of the most recent successfully completed snapshot, or null.
    - `subdomain` string, nullable — The box's stable three-word subdomain slug (e.g. "frazil-pneuma-rallye"), or null before one is assigned.
    - `lastSnapshotAttemptAt` string, date-time, nullable — Timestamp of the most recent snapshot attempt of any status (queued, in_progress, completed, failed, cancelled), or null. Use with snapshotCompletedAt to detect snapshots that keep failing.
    - `lastSnapshotStatus` 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'null', nullable — Status of the most recent snapshot attempt, or null if none. A value other than completed while snapshotCompletedAt stays stale indicates failing snapshots.

## Other responses

- `400` — Invalid request body or parameters.
- `401` — Missing or invalid bearer token.
- `404` — Resource not found.

---

[API](https://skmtc.dev/ascii/apis/box-public-api-v1.md) · [All operations](https://skmtc.dev/ascii/apis/box-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ascii/box-public-api-v1/revisions/82d576f82046/schema)