Skip to main content
GET
Diff two sandbox snapshots
Starts two billable VMs, one restored from each snapshot, walks both file trees (at most 200 files each) and answers the files added, removed and modified. A modified file carries both contents, fromContent and toContent, each read up to 64 KiB and cut to 65,536 characters, and 4 MiB of UTF-8 in total; truncated says the walk or the content budget stopped early. A file counts as modified only when its size differs, so an edit that keeps the size is not reported. path limits the walk to files under a prefix. Repeat it for up to 20 prefixes of letters, digits, _, ., / and -, at most 512 characters each. The two snapshot ids must differ. While Forge is stopped, the diff is refused with 403 and nothing is provisioned.

Masking

Runtime text is masked before it is cut to its cap: credential-shaped strings (JWTs, Bearer tokens, x-access-token: URLs and GitHub tokens) are replaced by a [REDACTED] marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses.

Visibility

A snapshot is reachable only when it is active and names the run that created it, and you can read that run’s sandboxes (factories:read at the run’s home and at every company it carries). Any other snapshot (unknown, deleted, failed, created outside a run such as a procedure image, or of a run out of reach) answers 404 “Snapshot not found”, and nothing is provisioned.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

fromSnapshotId
string
required

The snapshot to compare from.

Required string length: 1 - 200
toSnapshotId
string
required

The snapshot to compare to; it must differ.

Required string length: 1 - 200
path
string[]

A path prefix to limit the diff to. Repeatable.

Maximum array length: 20
Required string length: 1 - 512

Response

The snapshot diff

data
object
required
meta
object
required