Schedules API

The Schedules API allows you to create and manage automated backup schedules. You can configure recurring backups with custom CRON expressions, retention policies, and notification settings.

Endpoints Overview

Method	Endpoint	Description
POST	/schedules	Create a schedule
GET	/schedules	List all schedules
GET	/schedules/project/:projectId	List schedules for a project
GET	/schedules/:id	Get schedule details
PUT	/schedules/:id	Update schedule
DELETE	/schedules/:id	Delete schedule
PATCH	/schedules/:id/toggle	Enable/disable schedule
POST	/schedules/:id/trigger	Manually trigger schedule
GET	/schedules/stats/overview	Get schedule statistics

Create Schedule

Create a new backup schedule.

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

{
  "name": "Daily Production Backup",
  "projectId": "proj_abc123",
  "cronExpression": "0 2 * * *",
  "timezone": "America/New_York",
  "backupConfig": {
    "type": "full",
    "collections": ["users", "orders"],
    "includeSubcollections": true,
    "includeAuth": false,
    "compression": "brotli",
    "encrypt": true
  },
  "storageDestinationId": "storage_xyz789",
  "retention": {
    "type": "count",
    "value": 30
  },
  "enabled": true
}

Request Body:

Field	Type	Required	Description
name	string	Yes	Schedule display name
projectId	string	Yes	Project to backup
cronExpression	string	Yes	CRON expression (5 or 6 fields)
timezone	string	No	IANA timezone (default: UTC)
backupConfig	object	No	Backup configuration
backupConfig.type	string	No	full or incremental
backupConfig.collections	array	No	Collections to backup
backupConfig.includeSubcollections	boolean	No	Include subcollections
backupConfig.includeAuth	boolean	No	Include Firebase Auth
backupConfig.compression	string	No	brotli, gzip, none
backupConfig.encrypt	boolean	No	Enable encryption
storageDestinationId	string	No	Storage destination
retention	object	No	Retention policy
retention.type	string	No	count, days, or size
retention.value	integer	No	Retention value
enabled	boolean	No	Enable schedule (default: true)

Response:

{
  "success": true,
  "data": {
    "id": "sched_abc123",
    "name": "Daily Production Backup",
    "projectId": "proj_abc123",
    "cronExpression": "0 2 * * *",
    "timezone": "America/New_York",
    "nextRunAt": "2024-01-16T07:00:00Z",
    "enabled": true,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

List Schedules

Get all schedules in the organization.

GET /api/v1/schedules
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page
enabled	boolean	-	Filter by enabled status
projectId	string	-	Filter by project

Response:

{
  "success": true,
  "data": [
    {
      "id": "sched_abc123",
      "name": "Daily Production Backup",
      "projectId": "proj_abc123",
      "projectName": "Production App",
      "cronExpression": "0 2 * * *",
      "cronDescription": "Every day at 2:00 AM",
      "timezone": "America/New_York",
      "enabled": true,
      "lastRunAt": "2024-01-15T07:00:00Z",
      "lastRunStatus": "completed",
      "nextRunAt": "2024-01-16T07:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

List Project Schedules

Get schedules for a specific project.

GET /api/v1/schedules/project/:projectId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response: Same format as List Schedules.

Get Schedule

Get details of a specific schedule.

GET /api/v1/schedules/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "sched_abc123",
    "name": "Daily Production Backup",
    "projectId": "proj_abc123",
    "projectName": "Production App",
    "cronExpression": "0 2 * * *",
    "cronDescription": "Every day at 2:00 AM",
    "timezone": "America/New_York",
    "backupConfig": {
      "type": "full",
      "collections": ["users", "orders"],
      "includeSubcollections": true,
      "includeAuth": false,
      "compression": "brotli",
      "encrypt": true
    },
    "storageDestination": {
      "id": "storage_xyz789",
      "name": "Production S3",
      "type": "s3"
    },
    "retention": {
      "type": "count",
      "value": 30
    },
    "enabled": true,
    "lastRunAt": "2024-01-15T07:00:00Z",
    "lastRunStatus": "completed",
    "lastRunBackupId": "bkp_xyz789",
    "nextRunAt": "2024-01-16T07:00:00Z",
    "statistics": {
      "totalRuns": 42,
      "successfulRuns": 40,
      "failedRuns": 2,
      "successRate": 95.24,
      "averageDuration": 45,
      "averageSize": 6200000
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T07:00:45Z"
  }
}

Update Schedule

Update an existing schedule.

PUT /api/v1/schedules/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "name": "Daily Production Backup (Updated)",
  "cronExpression": "0 3 * * *",
  "backupConfig": {
    "type": "incremental",
    "collections": ["users", "orders", "products"]
  },
  "retention": {
    "type": "days",
    "value": 60
  }
}

Request Body:

All fields are optional. Only provided fields are updated.

Response:

{
  "success": true,
  "data": {
    "id": "sched_abc123",
    "name": "Daily Production Backup (Updated)",
    "cronExpression": "0 3 * * *",
    "nextRunAt": "2024-01-16T08:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Delete Schedule

Delete a schedule.

DELETE /api/v1/schedules/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Schedule deleted successfully"
}

Backup Retention

Deleting a schedule does not delete backups created by that schedule. Configure retention policies or manually delete backups if needed.

Toggle Schedule

Enable or disable a schedule.

PATCH /api/v1/schedules/:id/toggle
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "enabled": false
}

Request Body:

Field	Type	Required	Description
enabled	boolean	Yes	Enable/disable schedule

Response:

{
  "success": true,
  "data": {
    "id": "sched_abc123",
    "enabled": false,
    "nextRunAt": null,
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Trigger Schedule

Manually trigger a schedule to run immediately.

POST /api/v1/schedules/:id/trigger
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "backupId": "bkp_manual123",
    "scheduleId": "sched_abc123",
    "status": "pending",
    "triggeredBy": "manual",
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

Manual vs Scheduled

Manually triggered backups are tagged with triggeredBy: "manual" and do not affect the schedule's next run time.

Schedule Statistics

Get aggregate statistics across all schedules.

GET /api/v1/schedules/stats/overview
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "totalSchedules": 10,
    "activeSchedules": 8,
    "pausedSchedules": 2,
    "backupsToday": 15,
    "backupsThisWeek": 85,
    "backupsThisMonth": 320,
    "successRate": 97.5,
    "totalStorageUsed": 15000000000,
    "averageBackupSize": 6200000,
    "averageBackupDuration": 42,
    "nextScheduledBackup": {
      "scheduleId": "sched_abc123",
      "scheduleName": "Daily Production Backup",
      "projectName": "Production App",
      "nextRunAt": "2024-01-16T07:00:00Z"
    }
  }
}

CRON Expression Reference

FireBackup supports standard 5-field CRON expressions:

* * * * *
│ │ │ │ │
│ │ │ │ └─── day of week (0-6, Sun=0)
│ │ │ └───── month (1-12)
│ │ └─────── day of month (1-31)
│ └───────── hour (0-23)
└─────────── minute (0-59)

Common Patterns

Expression	Description
0 * * * *	Every hour
0 */6 * * *	Every 6 hours
0 0 * * *	Daily at midnight
0 2 * * *	Daily at 2:00 AM
0 0 * * 0	Weekly on Sunday
0 0 1 * *	Monthly on the 1st
0 9-17 * * 1-5	Hourly 9AM-5PM, Mon-Fri
*/15 * * * *	Every 15 minutes

Special Characters

Character	Description
*	Any value
,	Value list separator
-	Range of values
/	Step values

Schedule Object

Field	Type	Description
id	string	Unique schedule ID
name	string	Display name
projectId	string	Target project ID
cronExpression	string	CRON expression
cronDescription	string	Human-readable description
timezone	string	IANA timezone
backupConfig	object	Backup configuration
storageDestination	object	Storage destination
retention	object	Retention policy
enabled	boolean	Whether schedule is active
lastRunAt	string	Last execution time
lastRunStatus	string	Last execution status
nextRunAt	string	Next scheduled execution
statistics	object	Run statistics
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp

Retention Policies

Count-Based

Keep the last N backups:

{
  "retention": {
    "type": "count",
    "value": 30
  }
}

Time-Based

Keep backups for N days:

{
  "retention": {
    "type": "days",
    "value": 90
  }
}

Size-Based

Keep backups until total size exceeds N bytes:

{
  "retention": {
    "type": "size",
    "value": 10737418240
  }
}

Error Responses

Schedule Not Found

{
  "success": false,
  "error": {
    "code": "SCHEDULE_NOT_FOUND",
    "message": "Schedule 'sched_xxx' not found"
  }
}

Invalid CRON Expression

{
  "success": false,
  "error": {
    "code": "INVALID_CRON",
    "message": "Invalid CRON expression",
    "details": {
      "expression": "invalid * * * *",
      "field": "minute",
      "reason": "Expected number or special character"
    }
  }
}

Schedule Conflict

{
  "success": false,
  "error": {
    "code": "SCHEDULE_CONFLICT",
    "message": "A schedule already exists for this project at the same time"
  }
}

Webhook Events

Event	Description
schedule.created	Schedule was created
schedule.updated	Schedule was updated
schedule.deleted	Schedule was deleted
schedule.enabled	Schedule was enabled
schedule.disabled	Schedule was disabled
schedule.triggered	Schedule was manually triggered

Related

• Backups API - Manual backup operations
• Webhooks - Event notifications
• Backup Schedules - User guide