PITR API

The Point-in-Time Recovery (PITR) API enables continuous data protection by capturing every change to your Firestore database. This allows you to restore data to any specific moment in time.

Endpoints Overview

Method	Endpoint	Description
POST	/pitr/enable	Enable PITR for a project
POST	/pitr/:projectId/disable	Disable PITR
POST	/pitr/:projectId/pause	Pause PITR capture
POST	/pitr/:projectId/resume	Resume PITR capture
GET	/pitr/:projectId/config	Get PITR configuration
PATCH	/pitr/:projectId/config	Update PITR configuration
GET	/pitr/:projectId/statistics	Get PITR statistics
GET	/pitr/:projectId/health	Get PITR health status
GET	/pitr/:projectId/windows	List change windows
POST	/pitr/restore	Create PITR restore job
GET	/pitr/:projectId/restore-jobs	List restore jobs
GET	/pitr/:projectId/restore-jobs/:jobId	Get restore job status
GET	/pitr/:projectId/audit-log-status	Check audit log configuration

Enable PITR

Enable Point-in-Time Recovery for a project.

POST /api/v1/pitr/enable
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "projectId": "proj_abc123",
  "config": {
    "retentionDays": 7,
    "collections": ["users", "orders"],
    "changeWindowMinutes": 1,
    "storageDestinationId": "storage_xyz789"
  }
}

Request Body:

Field	Type	Required	Default	Description
projectId	string	Yes	-	Project to enable PITR for
config.retentionDays	integer	No	7	Days to retain PITR data
config.collections	array	No	All	Collections to monitor
config.changeWindowMinutes	integer	No	1	Change grouping interval
config.storageDestinationId	string	No	Default	Storage for PITR data

Response:

{
  "success": true,
  "data": {
    "id": "pitr_abc123",
    "projectId": "proj_abc123",
    "status": "initializing",
    "config": {
      "retentionDays": 7,
      "collections": ["users", "orders"],
      "changeWindowMinutes": 1
    },
    "enabledAt": "2024-01-15T10:00:00Z"
  }
}

Disable PITR

Disable PITR for a project.

POST /api/v1/pitr/:projectId/disable
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "deleteData": false
}

Request Body:

Field	Type	Required	Default	Description
deleteData	boolean	No	false	Delete existing PITR data

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "status": "disabled",
    "disabledAt": "2024-01-15T11:00:00Z",
    "dataRetained": true
  }
}

Pause PITR

Temporarily pause PITR change capture.

POST /api/v1/pitr/:projectId/pause
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "status": "paused",
    "pausedAt": "2024-01-15T11:00:00Z"
  }
}

Gap in Protection

While paused, changes are NOT captured. You cannot restore to timestamps during the paused period.

Resume PITR

Resume PITR change capture after pausing.

POST /api/v1/pitr/:projectId/resume
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "status": "active",
    "resumedAt": "2024-01-15T12:00:00Z"
  }
}

Get PITR Configuration

Retrieve current PITR configuration.

GET /api/v1/pitr/:projectId/config
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "status": "active",
    "config": {
      "retentionDays": 7,
      "collections": ["users", "orders"],
      "changeWindowMinutes": 1,
      "storageDestination": {
        "id": "storage_xyz789",
        "name": "Production S3",
        "type": "s3"
      }
    },
    "enabledAt": "2024-01-01T00:00:00Z",
    "lastChangeAt": "2024-01-15T10:30:00Z"
  }
}

Update PITR Configuration

Update PITR settings.

PATCH /api/v1/pitr/:projectId/config
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "retentionDays": 14,
  "collections": ["users", "orders", "products"]
}

Request Body:

Field	Type	Description
retentionDays	integer	Days to retain data
collections	array	Collections to monitor
changeWindowMinutes	integer	Change grouping interval
storageDestinationId	string	Storage destination

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "config": {
      "retentionDays": 14,
      "collections": ["users", "orders", "products"],
      "changeWindowMinutes": 1
    },
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Get PITR Statistics

Retrieve PITR statistics for a project.

GET /api/v1/pitr/:projectId/statistics
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "totalChangesCaptured": 1250000,
    "changeWindows": 10080,
    "storageUsed": 524288000,
    "oldestRecoveryPoint": "2024-01-08T10:00:00Z",
    "latestRecoveryPoint": "2024-01-15T10:30:00Z",
    "changesByCollection": {
      "users": 450000,
      "orders": 800000
    },
    "averageChangesPerHour": 7500,
    "peakChangesPerHour": 25000
  }
}

Get PITR Health

Check PITR health status.

GET /api/v1/pitr/:projectId/health
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "status": "healthy",
    "healthScore": 100,
    "lastChangeCapture": "2024-01-15T10:30:00Z",
    "captureLatency": 2,
    "checks": {
      "auditLogsEnabled": true,
      "workerRunning": true,
      "storageAccessible": true,
      "withinRetention": true
    },
    "warnings": [],
    "errors": []
  }
}

Health Status Values

Status	Description
healthy	All systems operational
degraded	Some issues detected
unhealthy	Critical issues
paused	PITR is paused
disabled	PITR is disabled

List Change Windows

Get captured change windows.

GET /api/v1/pitr/:projectId/windows
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	100	Items per page
from	string	-	Start timestamp
to	string	-	End timestamp
collection	string	-	Filter by collection

Response:

{
  "success": true,
  "data": [
    {
      "id": "window_abc123",
      "startTime": "2024-01-15T10:00:00Z",
      "endTime": "2024-01-15T10:01:00Z",
      "changesCount": 150,
      "size": 52428,
      "collections": ["users", "orders"],
      "breakdown": {
        "users": { "created": 10, "updated": 25, "deleted": 2 },
        "orders": { "created": 50, "updated": 60, "deleted": 3 }
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 100,
    "total": 10080,
    "totalPages": 101
  }
}

Create PITR Restore Job

Restore data to a specific point in time.

POST /api/v1/pitr/restore
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "projectId": "proj_abc123",
  "targetTimestamp": "2024-01-15T10:30:00Z",
  "options": {
    "collections": ["users"],
    "mergeMode": "overwrite",
    "targetProjectId": "proj_def456",
    "dryRun": false
  }
}

Request Body:

Field	Type	Required	Default	Description
projectId	string	Yes	-	Source project
targetTimestamp	string	Yes	-	ISO 8601 restore point
options.collections	array	No	All	Collections to restore
options.mergeMode	string	No	overwrite	overwrite, skip_existing, merge
options.targetProjectId	string	No	Same	Target project
options.dryRun	boolean	No	false	Preview without writing

Response:

{
  "success": true,
  "data": {
    "id": "pitr_restore_xyz789",
    "projectId": "proj_abc123",
    "targetTimestamp": "2024-01-15T10:30:00Z",
    "status": "pending",
    "options": {
      "collections": ["users"],
      "mergeMode": "overwrite",
      "targetProjectId": "proj_def456"
    },
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

List Restore Jobs

Get all PITR restore jobs for a project.

GET /api/v1/pitr/:projectId/restore-jobs
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": [
    {
      "id": "pitr_restore_xyz789",
      "targetTimestamp": "2024-01-15T10:30:00Z",
      "status": "completed",
      "documentsRestored": 15000,
      "duration": 180,
      "createdAt": "2024-01-15T11:00:00Z",
      "completedAt": "2024-01-15T11:03:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

Get Restore Job Status

Get details of a specific restore job.

GET /api/v1/pitr/:projectId/restore-jobs/:jobId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "pitr_restore_xyz789",
    "projectId": "proj_abc123",
    "targetTimestamp": "2024-01-15T10:30:00Z",
    "status": "completed",
    "progress": 100,
    "options": {
      "collections": ["users"],
      "mergeMode": "overwrite",
      "targetProjectId": "proj_def456"
    },
    "result": {
      "documentsRestored": 15000,
      "collectionsRestored": 1,
      "baseBackupUsed": "bkp_abc123",
      "changeWindowsApplied": 45
    },
    "timeline": [
      { "phase": "initializing", "timestamp": "2024-01-15T11:00:00Z" },
      { "phase": "downloading_base", "timestamp": "2024-01-15T11:00:05Z" },
      { "phase": "applying_changes", "timestamp": "2024-01-15T11:01:00Z" },
      { "phase": "verifying", "timestamp": "2024-01-15T11:02:50Z" },
      { "phase": "completed", "timestamp": "2024-01-15T11:03:00Z" }
    ],
    "createdAt": "2024-01-15T11:00:00Z",
    "completedAt": "2024-01-15T11:03:00Z"
  }
}

Restore Status Values

Status	Description
pending	Job queued
initializing	Preparing restore
downloading_base	Fetching base backup
applying_changes	Replaying change windows
verifying	Verifying restored data
completed	Restore successful
failed	Restore failed

Check Audit Log Status

Verify that Firebase audit logs are properly configured.

GET /api/v1/pitr/:projectId/audit-log-status
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "auditLogsEnabled": true,
    "dataReadLogsEnabled": true,
    "dataWriteLogsEnabled": true,
    "lastLogReceived": "2024-01-15T10:30:00Z",
    "logLag": 5,
    "issues": []
  }
}

Audit Log Not Configured

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "auditLogsEnabled": false,
    "dataReadLogsEnabled": false,
    "dataWriteLogsEnabled": false,
    "lastLogReceived": null,
    "issues": [
      {
        "code": "AUDIT_LOGS_DISABLED",
        "message": "Firestore audit logs are not enabled",
        "resolution": "Enable audit logs in Google Cloud Console > IAM & Admin > Audit Logs"
      }
    ]
  }
}

PITR Object

Field	Type	Description
id	string	PITR configuration ID
projectId	string	Project ID
status	string	Current status
config	object	Configuration settings
enabledAt	string	When PITR was enabled
lastChangeAt	string	Last captured change
statistics	object	Usage statistics

Error Responses

PITR Not Enabled

{
  "success": false,
  "error": {
    "code": "PITR_NOT_ENABLED",
    "message": "PITR is not enabled for this project"
  }
}

Invalid Timestamp

{
  "success": false,
  "error": {
    "code": "INVALID_TIMESTAMP",
    "message": "Requested timestamp is outside the retention window",
    "details": {
      "requestedTimestamp": "2024-01-01T00:00:00Z",
      "oldestAvailable": "2024-01-08T10:00:00Z",
      "latestAvailable": "2024-01-15T10:30:00Z"
    }
  }
}

Audit Logs Required

{
  "success": false,
  "error": {
    "code": "AUDIT_LOGS_REQUIRED",
    "message": "Firebase audit logs must be enabled for PITR",
    "details": {
      "instructions": "Enable audit logs in Google Cloud Console"
    }
  }
}

Webhook Events

Event	Description
pitr.enabled	PITR was enabled
pitr.disabled	PITR was disabled
pitr.paused	PITR was paused
pitr.resumed	PITR was resumed
pitr.restore.started	Restore job started
pitr.restore.completed	Restore job completed
pitr.restore.failed	Restore job failed
pitr.health.degraded	Health status degraded

Related

• Backups API - Standard backup operations
• Point-in-Time Recovery - User guide
• PITR Compliance Tutorial - Compliance setup