Introduction
The SimpleBackups Automation API lets you manage your entire backup infrastructure programmatically. Add servers, configure and run backups, manage storage providers, and pull activity reports — all via REST.
Authentication
All API requests require an Authorization header with a Bearer token. Create yours in Settings → API.
Authorization: Bearer YOUR_API_TOKEN Accept: application/json Content-Type: application/json
Rate limiting: Requests are limited to 60 requests/minute. A 429 Too Many Requests response is returned when you exceed the limit.
Backups
8 endpointshttps://my.simplebackups.io/api/backup/createCreate Backup
Create a backup of an existing resource (server), to be stored on an existing cloud storage.
JSON Body Fields
| Field | Required | Description |
|---|---|---|
name | required | VPS-Server-Backup |
type | required | full, file or db |
db_type | required unless type=file | MySQL, mongoDB or PostgreSQL |
db_host | required unless type=file | db hostname, ex: 127.0.0.1 |
db_port | required unless type=file | db port, ex: 3306 |
db_user | optional | db user, ex: dbuser |
db_psw | optional | db password, ex: dbpass123 |
project_id | optional | project id, ex: 2 |
db_name | required unless type=file | database name or * for all MySQL databases |
db_connection_string | either this field or individual database fields should be passed for db backups | database full connection string |
file_path | required unless type=db | path(s) to back up /home/sbio |
excluded_file_path | required unless type=db | path(s) to exclude from backup, ex: /home/*/vendor |
server_id | required | ID of the server to dumps your backup on |
tunnel_server_id | optional | ID of the tunnel/bastion server tunnel your database connection through |
storage_path | optional | Custom path under your storage for the backup, example daily/db-backups |
storage_id | required | ID of the storage to send your backup to |
schedule | required | on-demand, twice-daily, hourly, daily, weekly, custom |
schedule_cron | required when schedule=custom | cron expression, example: 0 23 * * 1-5 |
retention | required | number of retained backups, example: 7 |
meta | optional, array | additional options for backup |
secondary_schedules | optional, array | additional schedules for backup |
secondary_storages | optional, array | additional storages for backup |
JSON Meta Fields
| Meta field | Required | Description |
|---|---|---|
backup_is_incremental | optional | false or true |
backup_tar_donot_expand_symlinks | optional | false or true |
backup_tar_no_compression | optional | false or true |
backup_file_flatten_archive_contents | optional | false or true |
backup_file_streaming | optional | false or true |
backup_tar_donot_ignore_failed_read | optional | false or true |
backup_file_using_sudo | optional | false or true |
backup_store_uncompressed_db | optional | false or true |
backup_is_incremental_database | optional | false or true |
backup_db_streaming | optional | false or true |
backup_db_dumpall_single | optional | false or true |
backup_postgres_quick | optional | false or true |
backup_encryption_key | optional | RSA public key in PEM format |
Request Body
{
"name": "VPS-Server-Backup",
"type": "full",
"db_type": "mongoDB",
"db_host": "127.0.0.1",
"db_port": "3306",
"db_user": "dbuser",
"db_psw": "dbpass123",
"db_name": "mydb",
"project_id": "5",
"file_path": "/home/sbio",
"server_id": "108",
"storage_id": "96",
"schedule": "on-demand",
"retention": "7",
"meta": {
"backup_store_uncompressed_db": false,
"backup_tar_no_compression": false,
"backup_file_flatten_archive_contents": false,
"backup_is_incremental": true,
"backup_tar_donot_expand_symlinks": true,
"backup_file_streaming": true,
"backup_tar_donot_ignore_failed_read": false,
"backup_postgres_quick": false
},
"secondary_schedules": [
{
"schedule": "daily",
"retention": "1"
}
],
"secondary_storages": [
{
"storage_id": "145",
"storage_path": "test1"
}
]
}Response
{
"success": true,
"message": "Backup was created successfully!",
"errors": [],
"data": {
"id": 189,
"server_id": 108,
"storage_id": 96,
"type": "file",
"name": "VPS-Server-Backup",
"schedule": "on-demand",
"schedule_cron": null,
"status": 1,
"retention": 7,
"created_at": "2020-11-24 19:34:45",
"file_path": "/home/sbio",
"excluded_file_path": null,
"storage": {
"id": 96,
"name": "AWS S3",
"type": "s3"
},
"server": {
"id": 108,
"name": "Mongo-Test-04",
"connection_type": "password"
},
"project": {
"id": 5,
"name": "project 03"
},
"flags": {
"backup_store_uncompressed_db": false,
"backup_tar_no_compression": false,
"backup_file_flatten_archive_contents": false,
"backup_is_incremental": true,
"backup_tar_donot_expand_symlinks": true,
"backup_file_streaming": true,
"backup_tar_donot_ignore_failed_read": false,
"backup_postgres_quick": false
},
"last_file_backup": null,
"last_db_backup": null,
"trigger_url": "https://simplebackups/api/backup/a1b02bad-bb03-4e98-9f46-3e04e1a8ada7/run?api_token=mn4xfzUDNwu71JJqf90F",
"restore_command": null,
"secondary_schedules": [],
"secondary_storages": []
}
}https://my.simplebackups.io/api/backup/{backup_id}/updateUpdate Backup
Update a backup. Note that storage_id, server_id and type cannot be updated.
JSON Body Fields
| Field | Required | Description |
|---|---|---|
name | required | VPS-Server-Backup |
db_type | required unless type=file | MySQL, mongoDB or PostgreSQL |
db_host | required unless type=file | db hostname, ex: 127.0.0.1 |
db_port | required unless type=file | db port, ex: 3306 |
db_user | optional | db user, ex: dbuser |
db_psw | optional | db password, ex: dbpass123 |
project_id | optional | project id, ex: 2 |
db_name | required unless type=file | database name or * for all MySQL databases |
db_connection_string | either this field or individual database fields should be passed for db backups | database full connection string |
file_path | required unless type=db | path(s) to back up /home/sbio |
excluded_file_path | required unless type=db | path(s) to exclude from backup, ex: /home/*/vendor |
storage_path | optional | Custom path under your storage for the backup, example daily/db-backups |
schedule | required | on-demand, daily, weekly, custom |
schedule_cron | required when schedule=custom | cron expression, example: 0 23 * * 1-5 |
retention | required | number of retained backups, example: 7 |
meta | optional, array | additional options for backup |
secondary_schedules | optional, array | additional schedules for backup |
secondary_storages | optional, array | additional storages for backup |
JSON Meta Fields
| Meta field | Required | Description |
|---|---|---|
backup_is_incremental | optional | false or true |
backup_tar_donot_expand_symlinks | optional | false or true |
backup_tar_no_compression | optional | false or true |
backup_file_flatten_archive_contents | optional | false or true |
backup_file_streaming | optional | false or true |
backup_tar_donot_ignore_failed_read | optional | false or true |
backup_file_using_sudo | optional | false or true |
backup_store_uncompressed_db | optional | false or true |
backup_is_incremental_database | optional | false or true |
backup_db_streaming | optional | false or true |
backup_db_dumpall_single | optional | false or true |
backup_postgres_quick | optional | false or true |
backup_encryption_key | optional | RSA public key in PEM format |
Request Body
{
"name": "VPS-Server-Backup",
"db_type": "mongoDB",
"db_host": "127.0.0.1",
"db_port": "3306",
"db_user": "dbuser",
"db_psw": "dbpass123",
"db_name": "mydb",
"project_id": "5",
"file_path": "/home/sbio",
"schedule": "on-demand",
"retention": "7",
"meta": {
"backup_store_uncompressed_db": false,
"backup_tar_no_compression": false,
"backup_file_flatten_archive_contents": false,
"backup_is_incremental": true,
"backup_tar_donot_expand_symlinks": true,
"backup_file_streaming": true,
"backup_tar_donot_ignore_failed_read": false,
"backup_postgres_quick": false
},
"secondary_schedules": [
{
"schedule": "daily",
"retention": "1"
}
],
"secondary_storages": [
{
"storage_id": "145",
"storage_path": "test1"
}
]
}Response
{
"success": true,
"message": "Backup was updated successfully!",
"errors": [],
"data": {
"id": 189,
"server_id": 108,
"storage_id": 96,
"type": "file",
"name": "VPS-Server-Backup",
"schedule": "on-demand",
"schedule_cron": null,
"status": 1,
"retention": 7,
"created_at": "2020-11-24 19:34:45",
"file_path": "/home/sbio",
"excluded_file_path": null,
"storage": {
"id": 96,
"name": "AWS S3",
"type": "s3"
},
"server": {
"id": 108,
"name": "Mongo-Test-04",
"connection_type": "password"
},
"project": {
"id": 5,
"name": "project 03"
},
"flags": {
"backup_store_uncompressed_db": false,
"backup_tar_no_compression": false,
"backup_file_flatten_archive_contents": false,
"backup_is_incremental": true,
"backup_tar_donot_expand_symlinks": true,
"backup_file_streaming": true,
"backup_tar_donot_ignore_failed_read": false,
"backup_postgres_quick": false
},
"last_file_backup": null,
"last_db_backup": null,
"trigger_url": "https://simplebackups/api/backup/a1b02bad-bb03-4e98-9f46-3e04e1a8ada7/run?api_token=mn4xfzUDNwu71JJqf90F",
"restore_command": null,
"secondary_schedules": [],
"secondary_storages": []
}
}https://my.simplebackups.io/api/backup/listList Backups
List all backups on your SimpleBackups account.
Available filters:
idpassed as URL parameterfilters[id]=backup_id
namepassed as URL parameterfilters[name]=BackupName
statuspassed as URL parameterfilters[status]=0orfilters[status]=1
typepassed as URL parameterfilters[type]=db(db,file,full,sync,recipe)
serverpassed as URL parameterfilters[server]=server_id
storagepassed as URL parameterfilters[storage]=storage_id
Response
https://my.simplebackups.io/api/backup/{backup_id}/runRun Backup
Run a backup given its ID.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| backup_id | integer | required | ID of the backup to run. |
Response
{
"success": true,
"message": "Backup dispatched! You'll be notified when your backup is available.",
"errors": [],
"data": {
"created_at": "2020-01-27 00:00:00",
"filename": "simplebackups.io.file.b101010_20-01-27_000000.tar.gz",
"filesize": null,
"id": 9090909,
"status": "initiated",
"type": "file"
}
}https://my.simplebackups.io/api/backup/{backup_id}/pausePause Backup
Pause a backup schedule given its ID.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| backup_id | integer | required | ID of the backup to pause. |
Response
{
"success": true,
"message": "Backup has been paused! We will no longer run this backup automatically with respect to the selected schedule (daily). However, you can still run this backup on demand.",
"errors": [],
"data": []
}https://my.simplebackups.io/api/backup/{backup_id}/resumeResume Backup
Resume a backup schedule given its ID.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| backup_id | integer | required | ID of the backup to resume. |
Response
{
"success": true,
"message": "Backup has been resumed! We will run this backup with respect to the selected schedule (daily).",
"errors": [],
"data": []
}https://my.simplebackups.io/api/backup/{backup_id}/download-link/{log_id}Get Backup Download Link
Generate a signed download link for your last successful backup given its ID.
If passing a log_id as well, it will generate a signed download link for that specific backup log.
For full backups, the response includes both, file and db backup links.
If a backup is encrypted, you will also see the signed_encryption_passphrase_link in the response, otherwise it is null.
Links expire in 300 seconds where applicable.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| backup_id | integer | required | ID of the backup to get its download link(s). |
| log_id | integer | optional | ID of the specific log to get its download link(s). |
Response
{
"success": true,
"message": "Signed download link generated successfully!",
"errors": [],
"data": {
"db": {
"signed_link": "https://sample.s3.eu-north-1.amazonaws.com/backups/db.sakila.mysql-backup.b1010101010.25-01-01_1010101.sql.gz?X-Amz-Content-Sha256=...&X-Amz-Signature=...",
"signed_encryption_passphrase_link": null
},
"file": {
"signed_link": null,
"signed_encryption_passphrase_link": null
}
}
}https://my.simplebackups.io/api/backup/{backup_id}/deleteDelete Backup
Delete a backup job. This will not remove the backup copies stored on your storage.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| backup_id | integer | required | ID of the backup to delete. |
Response
{
"success": true,
"message": "Backup was successfully deleted!",
"errors": [],
"data": []
}Servers
4 endpointshttps://my.simplebackups.io/api/server/listList Servers
List all servers providers added to your SimpleBackups account.
Response
https://my.simplebackups.io/api/server/addAdd Server
Add a server to SimpleBackups.
Prerequisites
For servers that use an SSH password authentication method, you only need to pass the credentials to fully add your server.
If your server uses an SSH key authentication method, you will need to:
1. Add the server via the API without passing a password (you may still pass a password if your server requires a password in addition to a key)
2. Immediately run the command given in the install_command value which will be given in the response
JSON Body Fields
| Field | Type/Example | Description |
|---|---|---|
name | required, integer, My-Amazon-VPS | Name your server |
connection_type | required, string, password | How you connect to your server, can be ssh for SSH key authentication or password |
host | required, string, 1.1.1.1 | SSH hostname or IP of your server |
port | required, integer, 22 | SSH port |
user | required, string, ubuntu | SSH user |
password | optional, string, mysteri0usFlyte$ | SSH password, required for password authentication |
temp_directory | optional, string, /home/ubuntu | A directory used for temporary operations and retaining SimpleBackups settings on your server. Must have write access to it |
project_id | optional | project id, ex: 5 |
Request Body
{
"name": "Amazon-VPS-16",
"connection_type": "ssh",
"host": "1.1.1.1",
"port": "22",
"user": "ubuntu",
"password": "",
"temp_directory": "/home/ubuntu",
"project_id": "5"
}Response
{
"success": true,
"message": "Server was added successfully!",
"errors": [],
"data": {
"id": 78,
"name": "Amazon-VPS-16",
"connection_type": "ssh",
"status": 1,
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5VVVAAIHq0+gix03if8Dn++p2POXO3c0a+crUmPcZFcxzXo6Hn SB-WORKER-T007",
"created_at": "2025-01-01T00:06:43.000000Z",
"install_command": "curl -sSL \"https://simplebackups/api/setup/78/connect?token=34ee595255\" | bash -s 1649068f-0593-4fc2-8bb4-6743f9fa767d",
"project": {
"id": 5,
"name": "project 03"
}
}
}https://my.simplebackups.io/api/server/{server_id}/validate-connectionValidate Server Connection
Validate that your server has been added and is connected properly to SimpleBackups. A validated server is a server that is ready for backups.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| server_id | integer | required | ID of the server to validate its connection. |
Request Body
{}Response
{
"success": true,
"data": {
"status": true,
"message": ""
}
}https://my.simplebackups.io/api/server/{server_id}/removeRemove Server
Removes a server from your SimpleBackups dashboard, and also removes SimpleBackups' ability to connect to that server.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| server_id | integer | required | ID of the server to remove. |
Request Body
{}Response
{
"success": true,
"message": "Server removal queued! May take a couple of minutes.",
"errors": [],
"data": []
}Storage
1 endpointhttps://my.simplebackups.io/api/storage/listList Storage
List all storage providers added to your SimpleBackups account.
Available URL filters
| Field | Example | Description |
|---|---|---|
name | filters[name]=ServerName | |
status | filters[status]=0 or filters[status]=1 |
Response
{
"data": [
{
"id": 1,
"name": "Backblaze Limited Scope",
"type": "backblaze",
"status": 1,
"created_at": "2025-01-01T00:06:43.000000Z"
},
{
"id": 2,
"name": "SimpleStorage",
"type": "simple",
"status": 1,
"created_at": "2025-01-01T00:06:43.000000Z"
}
]
}Statistics
4 endpointshttps://my.simplebackups.io/api/stats/activityList Job Activity
Returns a list of jobs, ordered by descending creation date.
Available filters
| Field | Type | Description |
|---|---|---|
date_from | optional, date, default:1 month ago | Query from that date. Example: 2022-01-01 |
date_to | optional, date, default:now | Query until that date. Example: 2022-01-31 |
type | required, string, accepted values: backup, snapshot, cloudsync | Type of resource to query. Example: backup |
resource_ids | optional, string, accepted values: comma-separated ids | Type of resource to query. Example: 10,214,477 |
Response fields
| Fields | Type | Description |
|---|---|---|
status | string | Possible values: success, error, rotated |
Response
https://my.simplebackups.io/api/stats/resourceList Resource Activity
Returns a list of resources (backup, snapshot or cloudsync), with their job activity and next scheduled jobs.
Available filters
| Field | Type | Description |
|---|---|---|
date_from | optional, date, default:1 month ago | Query from that date. Example: 2022-01-01 |
date_to | optional, date, default:now | Query until that date. Example: 2022-01-31 |
type | required, string, accepted values: backup, snapshot, cloudsync | Type of resource to query. Example: backup |
resource_ids | optional, string, accepted values: comma separated ids | Type of resource to query. Example: 10,214,477 |
Response
{
"data": [
{
"id": 13,
"name": "long-lab-1095",
"created_at": "2020-10-21 11:05:26",
"storage": {
"id": 104,
"name": "Simple Storage",
"type": "simple"
},
"server": {
"id": 16,
"name": "server-cloud-01"
},
"schedules": [
"Sat, Mar 12, 2022 3:00 AM",
"Sat, Mar 19, 2022 3:00 AM",
"Sat, Mar 26, 2022 3:00 AM",
"Sat, Apr 2, 2022 4:00 AM",
"Sat, Apr 9, 2022 4:00 AM"
],
"logs": [
{
"id": 9937389,
"status": "error",
"filesize": null,
"created_at": "2022-02-24 14:38:32",
"finished_at": "2022-02-24 14:38:34",
"backup": {
"id": 13,
"name": "long-lab-1095",
"type": "file"
}
}
]
},
{
"id": 10015,
"name": "filebackup",
"created_at": "2022-02-24 14:41:23",
"storage": {
"id": 103,
"name": "my-awesome-space3",
"type": "digitalocean_spaces"
},
"server": {
"id": 118,
"name": "silent-butterfly-1303"
},
"schedules": [
"On demand"
],
"logs": []
},
{
"id": 10016,
"name": "withered-morning-7291",
"created_at": "2022-02-24 15:47:38",
"storage": {
"id": 106,
"name": "SimpleStorage",
"type": "simple"
},
"server": {
"id": 118,
"name": "silent-butterfly-1303"
},
"schedules": [
"On demand"
],
"logs": [
{
"id": 9937412,
"status": "purged",
"filesize": "12.43",
"created_at": "2022-02-25 12:30:04",
"finished_at": "2022-02-25 12:30:17",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937411,
"status": "purged",
"filesize": "12.43",
"created_at": "2022-02-25 12:28:41",
"finished_at": "2022-02-25 12:28:53",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937410,
"status": "rotated",
"filesize": "12.43",
"created_at": "2022-02-25 12:28:15",
"finished_at": "2022-02-25 12:28:27",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937409,
"status": "rotated",
"filesize": "12.43",
"created_at": "2022-02-25 12:16:53",
"finished_at": "2022-02-25 12:17:05",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937408,
"status": "rotated",
"filesize": "12.43",
"created_at": "2022-02-25 12:10:13",
"finished_at": "2022-02-25 12:10:33",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937407,
"status": "purge-max-tries",
"filesize": "12.43",
"created_at": "2022-02-25 12:07:59",
"finished_at": "2022-02-25 12:08:11",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937406,
"status": "rotated",
"filesize": "12.43",
"created_at": "2022-02-25 12:07:27",
"finished_at": "2022-02-25 12:07:39",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
},
{
"id": 9937405,
"status": "rotated",
"filesize": "12.43",
"created_at": "2022-02-25 12:06:52",
"finished_at": "2022-02-25 12:07:04",
"backup": {
"id": 10016,
"name": "withered-morning-7291",
"type": "file"
}
}
]
},
{
"id": 10017,
"name": "file-super-brook-4222",
"created_at": "2022-03-04 15:23:29",
"storage": {
"id": 103,
"name": "my-awesome-space3",
"type": "digitalocean_spaces"
},
"server": {
"id": 66,
"name": "still-union-0448"
},
"schedules": [
"On demand"
],
"logs": []
}
]
}https://my.simplebackups.io/api/stats/reportActivity Report
Returns the "activity report" for the given period for all resources (backup, snapshots and cloud-sync). The activity report contains summarize how many backup ran, their status (success/error) as well as storage usage.
Available filters
| Field | Type | Description |
|---|---|---|
date_from | optional, date, default:1 month ago | Query from that date. Example: 2022-01-01 |
date_to | optional, date, default:now | Query until that date. Example: 2022-01-31 |
Response
https://my.simplebackups.io/api/stats/scheduleScheduled jobs list
Returns a list of the next 5 scheduled date for each resources.
Available filters
| Field | Type | Description |
|---|---|---|
type | required, string, accepted values: backup, snapshot, cloudsync | Type of resource to query. Example: backup |
resource_ids | optional, string, accepted values: comma separated ids | Type of resource to query. Example: 10,214,477 |
Response
Teams
3 endpointshttps://my.simplebackups.io/api/team/listList Teams
List all teams on your SimpleBackups account.
Response
{
"data": [
{
"id": 1,
"owner_id": 4,
"name": "ACME Inc",
"timezone": "UTC",
"created_at": "2025-01-01T23:19:32.000000Z"
},
{
"id": 2,
"owner_id": 4,
"name": "Jim Doe's Team",
"timezone": "UTC",
"created_at": "2025-02-01T23:19:32.000000Z"
},
{
"id": 3,
"owner_id": 4,
"name": "Smart Agency Inc",
"timezone": "UTC",
"created_at": "2025-03-01T23:19:32.000000Z"
}
]
}https://my.simplebackups.io/api/team/currentGet Current Team
Get the current team you are using on SimpleBackups.
Response
{
"data": {
"id": 1,
"owner_id": 4,
"name": "ACME Inc",
"timezone": "UTC",
"created_at": "2025-01-01T23:19:32.000000Z"
}
}https://my.simplebackups.io/api/team/{team_id}/switchSwitch Team
Switch your account to use a team you belong to, given its ID.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| team_id | integer | required | ID of the team to switch to and use for all subsequent requests. |
Response