Retention & deletion

Choose Run retention

Each Environment defaults to 30-day retention for Platform Run content. Read GET /v1/environments/{environmentId}/data-policy or use PUT with {"runContentRetentionDays":7} to choose 7, 30 or 90 days. Retention is measured from a terminal Run's finishedAt. Cleanup waits for its checkpoint to stop being pending and runs asynchronously. Shortening the policy also affects old records; increasing it does not recover erased content.

This policy erases Platform prompts, output, steering messages, event payloads, file references/manifests and verbose errors. It does not erase the live RootFS, native harness history, supervisor journals or checkpoints. Those remain until the Environment is deleted. Cleared Runs return contentDeletedAt, empty input, no output, and no replayable content events. Minimal Run/usage identities remain so settlement and unresolved provider reservations still work. Idempotency fingerprints and minimum native recovery coordinates also remain; they support safe retries and rollback without restoring erased API content.

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/data-policy" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "runContentRetentionDays": "",
    "auditRetentionDays": 90,
    "workspaceRetention": "until_environment_deletion",
    "runContentScope": "platform_records",
    "backupErasure": "operator_managed"
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/data-policy" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "runContentRetentionDays": ""
}'

{
  "runContentRetentionDays": ""
}

{
  "data": {
    "runContentRetentionDays": "",
    "auditRetentionDays": 90,
    "workspaceRetention": "until_environment_deletion",
    "runContentScope": "platform_records",
    "backupErasure": "operator_managed"
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Delete Run records

Wait for the Run to be terminal and its checkpoint to stop being pending. Request record cleanup, save the returned deletion ID and poll the receipt. This does not restore workspace state.

curl -X POST \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/runs/$RUN_ID/content-deletions" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "id": "",
    "environmentId": "",
    "kind": "run_content",
    "status": "pending",
    "attempts": -9007199254740991,
    "requestedAt": "2026-10-12T01:00:00Z",
    "scope": "platform_records",
    "physicalErasure": "not_verified",
    "backupErasure": "operator_managed",
    "providerErasure": "provider_managed"
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Delete an Environment

Request cleanup and track the receipt until completion. New operations are fenced as soon as deletion is accepted. Delete independent completed forks separately.

curl -X POST \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/deletions" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "id": "",
    "environmentId": "",
    "kind": "run_content",
    "status": "pending",
    "attempts": -9007199254740991,
    "requestedAt": "2026-10-12T01:00:00Z",
    "scope": "platform_records",
    "physicalErasure": "not_verified",
    "backupErasure": "operator_managed",
    "providerErasure": "provider_managed"
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

curl \
    "https://api.sandpi.ai/v1/deletions/$DELETION_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "id": "",
    "environmentId": "",
    "kind": "run_content",
    "status": "pending",
    "attempts": -9007199254740991,
    "requestedAt": "2026-10-12T01:00:00Z",
    "scope": "platform_records",
    "physicalErasure": "not_verified",
    "backupErasure": "operator_managed",
    "providerErasure": "provider_managed"
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

What completion proves

Receipts explicitly report physicalErasure: "not_verified", backupErasure: "operator_managed" and providerErasure: "provider_managed". Sandbox0 reference release and physical object garbage collection are distinct. Shared blocks needed by independent forks remain. Backup copies may contain older content, and restoring a backup requires replaying deletion receipts before access is reopened. Contact contact@sandpi.ai for deployment-specific backup retention, provider processing terms or a DPA. These APIs do not assert a certification or that every physical/provider/backup copy has been erased.

Track cleanup

Poll the deletion receipt or list the latest 100 receipts in your key’s scope. Filter by Environment ID to find the receipt created by DELETE Environment, which returns 204 on acceptance. A receipt remains readable after the Environment is deleted. Completed receipts describe their declared scope: Platform records for a Run, or online Environment content for whole-workspace cleanup. Pending jobs retry asynchronously.

curl \
    "https://api.sandpi.ai/v1/deletions" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": [
    {
      "id": "",
      "environmentId": "",
      "kind": "run_content",
      "status": "pending",
      "attempts": -9007199254740991,
      "requestedAt": "2026-10-12T01:00:00Z",
      "scope": "platform_records",
      "physicalErasure": "not_verified",
      "backupErasure": "operator_managed",
      "providerErasure": "provider_managed"
    }
  ]
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Select the right operation

See stop and rollback and audit and exports.

Delete using the Environment resource

The Environment DELETE operation uses the same asynchronous cleanup queue but returns an empty response. List deletion receipts to track completion. Prefer the receipt-returning request above when your integration needs a deletion ID immediately.

curl -X DELETE \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}