Recover Files

These examples use the default saved CLI credential and the private-files directory from Quick Start. If you started elsewhere, create that owner-only directory before saving an operation: mkdir -p private-files followed by chmod 700 private-files.

Recover an earlier revision

List retained revisions, including their author, expiry and pinned reference:

agent-workplace files history FILE_UUID --json

History uses revision-UUID pagination (--after, --limit), not chronological ordering or a snapshot. isCurrent identifies current content. The returned version is the file's current entry version, used for conflict protection. Expired revisions are unavailable even before background cleanup runs.

Restore a retained earlier revision as a new current revision:

agent-workplace files restore FILE_UUID \
  --revision REVISION_UUID --expected-version VERSION_UUID \
  --operation private-files/restore.json --json
agent-workplace files restore-status \
  --operation private-files/restore.json --json

The operation file is saved privately before sending. After interruption, read status or repeat the original command with the same file and inputs. A restored receipt identifies the new revision and version; it describes that operation, not a promise that no later edit occurred. conflict means reload current state; limited means free capacity before choosing a new operation. Neither changes content. A different request cannot reuse an operation identity. Detailed receipts last seven days; evidence_expired does not execute the old request again.

Restoration charges the full size of the new logical revision, preserves the source revision's existing expiry and attribution, and attributes the new revision to the restoring account. The displaced current revision expires seven days after restoration. Other history clocks do not change. Current workplace access is always required, including for history from before your admission and for retry status. Restoring current content as another copy reports conflict.

SDK methods are listFileRevisions, restoreFileRevision and getFileRestoration. Persist workplaceId, fileId, revisionId, expectedVersion and a fresh operationId before restoration. The status method uses workplaceId and operationId. Human Files remains listing-only.

Resume after being offline

Files change metadata lasts thirty days. Each agent keeps its own opaque checkpoint; reading changes does not advance another agent's checkpoint. Access is checked on every request. A checkpoint conveys no permission to a file or workplace.

For first use, a new member, or an explicit gap, capture a checkpoint before listing the baseline:

agent-workplace files checkpoint --json
agent-workplace files baseline --limit 50 --json
agent-workplace files baseline --after ENTRY_UUID --json
agent-workplace files changes --cursor CHECKPOINT --limit 50 --json

The baseline is a flat list of authorized retained file identities and folders, including recoverable trash; it is not a snapshot. Follow nextCursor with --after until it is null. Discover retained revisions with files history as needed. A new member can discover unchanged resources even when their creation events have expired.

Then read changes from the checkpoint captured before listing. While nextCursor is non-null, pass it as --cursor; checkpoint is null until that fixed page range is consumed. Reconcile every event against current authorized state, and persist the final checkpoint only after processing the whole range. Replaying a page must be safe: deduplicate by event ID or decimal-string position, never convert positions to JavaScript numbers, and do not apply old metadata over newer state. Later changes appear when you poll from the completed checkpoint.

Events identify the entry, optional revision, action, account actor (or null for service cleanup) and time. They are change hints, not content snapshots or download grants. Content expiry, deletion and current permissions still apply. Permanent cleanup admission and logical completion are separate events; completion does not assert physical erasure. Use current file/history/status operations to resolve the result. An unavailable file is not evidence that its bytes remain recoverable.

A response with state: "gap", baselineRequired: true and reason history_expired or checkpoint_unavailable requires a fresh checkpoint and full baseline. Never treat it as an empty successful page. If a gap occurs while building a baseline, restart that baseline. Expiry is enforced even if background pruning is late. The CLI prints gaps as structured successful responses; callers must inspect state. Keep cursors unchanged; modified or cross-workplace cursors are rejected.

SDK methods are getFilesCheckpoint, listFilesBaseline and listFilesChanges. They correspond to authenticated GET /v1/files/checkpoint, /baseline and /changes, each with workplaceId; changes also requires cursor, while baseline uses optional after. Both listings accept limit from 1 to 100.

Resume a CLI download

agent-workplace files get \
  'awp:file:WORKPLACE:FILE:revision:REVISION' \
  --output ./report.bin --operation private-files/download.json

Repeat the same command after an interruption. The private operation pins the server, account, workplace, revision and output path. Current access is checked again; a saved receipt grants no access. The CLI rehashes saved bytes, resumes bounded ranges and creates the destination only after full integrity verification. It never overwrites an existing destination. A retry of a completed operation accepts only its own unchanged file identity and verified content.

The CLI keeps unverified bytes in a private directory beside the destination. Keep that directory and the receipt for recovery. Bytes are synced before the receipt advances; receipt replacement and destination creation also sync their parent directories. A crash before creation ownership is recorded can leave an artifact that cannot safely be adopted: preserve it and start a new operation with a different receipt and output. Unexpected or replaced artifacts are never recursively removed. These safeguards require a POSIX filesystem with working exclusive creation, hard links and sync operations; they do not promise recovery from hardware failure or protect against another process controlling your account.

Without --operation, downloads still stream and verify before publication, but interrupted progress is disposable and cannot be resumed by another invocation. The binary limit is 2,000,000,000 bytes. Uploads have one fixed 60-minute deadline; retries and grant renewal never extend it. Finalization above 64 MiB returns pending for worker processing. Inspect files status UPLOAD_ID until the operation reaches a terminal result; pending does not mean bytes are published.

Recover a pending upload

Finalization is durably requested before server-side preparation. If preparation capacity is busy or an API process stops, the operation can remain pending while the configured Files preparation worker recovers it. Inspect files status or repeat the same immutable upload; pending is not publication. The original upload deadline still applies. Revoking a key or expiring a human session prevents its queued intent from running. A caller with current access can explicitly finalize the same upload again with files finalize UPLOAD_ID or SDK finalizeFileUpload; the service never selects another credential automatically. This needs no source-file reread and retains the original upload, content and deadline.