Tenantdata Backup

Summary

This guide explains how tenant data snapshots work and how to trigger backups manually or from ProcessFlow automation. It focuses on practical execution patterns, including API-triggered backup requests, timeout handling, and structured success and failure outputs. Use this recipe when you need reliable tenant-level recovery points before or after critical operations.

How tenantdata snapshots work

Tenant backups are stored as point-in-time snapshots under .backups/latest/<timestamp>, for example .backups/latest/2026-02-16-14-30. The backup mechanism uses hard-link optimization so unchanged files do not consume full duplicate storage in each snapshot. This keeps backup history efficient while preserving restore points.

The backup process excludes .backups and .cache and keeps only the latest configured number of snapshots, typically 30. When a new snapshot is created and the limit is exceeded, the oldest snapshot is removed. This retention behavior is important when sizing storage and recovery windows.

Trigger a backup manually from the support agent

You can request a backup directly in Platform Engineer or Support Agent chat when you need an immediate snapshot. This is useful before high-risk data changes, migrations, or external sync operations. No process code is required for manual execution.

Use a clear message such as: Create a new snapshot backup of the tenantdata files and directories. Keep 30 previous entries. The support agent handles tool execution and retention pruning in its workflow. Manual trigger is the fastest route for ad hoc backup needs.

Automate backups from ProcessFlow

For scheduled or event-driven backups, call the support-agent API from a ProcessFlow step. The step sends a backup instruction message, waits for streamed completion, and returns status data your process can use for branching or alerts. Long timeout settings are recommended because backup creation can take time on larger tenant datasets.

const keepBackups = Number(process_input.keep_backups ?? 30);
const prompt =
    String(process_input.message ?? "").trim() ||
    `Create a new snapshot backup of the tenantdata files and directories. Keep ${keepBackups} previous entries.`;

const url = `${String(app_url).replace(/\/$/, "")}/api/v1/chat/support-agent`;

try {
    const response = await fetch(url, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Accept: "text/event-stream",
            "X-Process-Authorization-Key": String(execution_auth_key ?? ""),
            "X-Tenant-ID": String(tenant_id ?? ""),
            "X-User-ID": String(user_id ?? ""),
            "User-Agent": "ProcessFlow/1.0 (tenant-backup-step)",
        },
        body: JSON.stringify({
            message: prompt,
            agent: "support_agent_mcp",
            timestamp: new Date().toISOString(),
        }),
        signal: AbortSignal.timeout(300_000),
    });

    const responseText = await response.text();
    const preview = responseText.slice(0, 1000);

    if (!response.ok) {
        return {
            success: false,
            error: {
                code: "SUPPORT_AGENT_BACKUP_FAILED",
                message: "Support-agent backup request failed",
                details: `HTTP ${response.status}`,
            },
            data: {
                http_code: response.status,
                response_preview: responseText.slice(0, 500),
            },
        };
    }

    return {
        success: true,
        data: {
            http_code: response.status,
            response_preview: preview,
        },
        message: "Backup request completed via support-agent",
    };
} catch (err) {
    return {
        success: false,
        error: {
            code: "SUPPORT_AGENT_BACKUP_FAILED",
            message: "Support-agent backup request failed",
            details: err instanceof Error ? err.message : "request failed",
        },
        data: { http_code: null, response_preview: null },
    };
}

API request examples

If you need to test backup trigger behavior outside a process step, send the same request shape to the support-agent endpoint. Use tenant and process authorization headers that match your execution context.

const baseUrl = "https://dev.tealfabric.io/api/v1";
const tenantId = "<TENANT_ID>";
const processKey = "<API_KEY>";

async function triggerTenantBackup() {
  const response = await fetch(`${baseUrl}/chat/support-agent`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "text/event-stream",
      "X-Process-Authorization-Key": processKey,
      "X-Tenant-ID": tenantId,
      "X-User-ID": "<USER_ID>",
    },
    body: JSON.stringify({
      message: "Create a new snapshot backup of the tenantdata files and directories. Keep 30 previous entries.",
      agent: "support_agent_mcp",
      timestamp: new Date().toISOString(),
    }),
  });
  if (!response.ok) throw new Error(`Backup request failed: ${response.status}`);
  return response.status;
}

curl -X POST "https://dev.tealfabric.io/api/v1/chat/support-agent" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-Process-Authorization-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "X-User-ID: <USER_ID>" \
  -d '{
    "message": "Create a new snapshot backup of the tenantdata files and directories. Keep 30 previous entries.",
    "agent": "support_agent_mcp",
    "timestamp": "2026-05-08T10:16:00Z"
  }'

{
  "success": true,
  "data": {
    "http_code": 200,
    "response_preview": "event stream response preview..."
  },
  "message": "Backup request completed via support-agent"
}

Optional inputs and return behavior

The automation step supports optional prompt override and retention override fields so teams can tune backup behavior per process. If no custom prompt is provided, the default backup instruction is generated using keep_backups. This keeps operational behavior explicit while preserving safe defaults.

On success, the step returns success: true with HTTP status and a truncated response preview. On failure, the step returns structured error data with code, message, details, and HTTP context for alerting or retry routing.

Final checklist

Use this checklist before deploying automated backup steps:

• Backup instruction prompt is explicit and includes retention target.
• X-Process-Authorization-Key, X-Tenant-ID, and X-User-ID headers are provided.
• Step timeout is long enough for backup execution on large datasets.
• Failure branch handles non-2xx responses and transport errors.
• Response preview is truncated to avoid oversized process payloads.