SimpleBackupsSimpleBackups
v1.0.0

API Reference

Automate backups, manage servers and storage — all through the SimpleBackups API.

Base URLhttps://my.simplebackups.io/api

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 endpoints
POSThttps://my.simplebackups.io/api/backup/create

Create Backup

Create a backup of an existing resource (server), to be stored on an existing cloud storage.

JSON Body Fields

FieldRequiredDescription
namerequiredVPS-Server-Backup
typerequiredfull, file or db
db_typerequired unless type=fileMySQL, mongoDB or PostgreSQL
db_hostrequired unless type=filedb hostname, ex: 127.0.0.1
db_portrequired unless type=filedb port, ex: 3306
db_useroptionaldb user, ex: dbuser
db_pswoptionaldb password, ex: dbpass123
project_idoptionalproject id, ex: 2
db_namerequired unless type=filedatabase name or * for all MySQL databases
db_connection_stringeither this field or individual database fields should be passed for db backupsdatabase full connection string
file_pathrequired unless type=dbpath(s) to back up /home/sbio
excluded_file_pathrequired unless type=dbpath(s) to exclude from backup, ex: /home/*/vendor
server_idrequiredID of the server to dumps your backup on
tunnel_server_idoptionalID of the tunnel/bastion server tunnel your database connection through
storage_pathoptionalCustom path under your storage for the backup, example daily/db-backups
storage_idrequiredID of the storage to send your backup to
schedulerequiredon-demand, twice-daily, hourly, daily, weekly, custom
schedule_cronrequired when schedule=customcron expression, example: 0 23 * * 1-5
retentionrequirednumber of retained backups, example: 7
metaoptional, arrayadditional options for backup
secondary_schedulesoptional, arrayadditional schedules for backup
secondary_storagesoptional, arrayadditional storages for backup

JSON Meta Fields

Meta fieldRequiredDescription
backup_is_incrementaloptionalfalse or true
backup_tar_donot_expand_symlinksoptionalfalse or true
backup_tar_no_compressionoptionalfalse or true
backup_file_flatten_archive_contentsoptionalfalse or true
backup_file_streamingoptionalfalse or true
backup_tar_donot_ignore_failed_readoptionalfalse or true
backup_file_using_sudooptionalfalse or true
backup_store_uncompressed_dboptionalfalse or true
backup_is_incremental_databaseoptionalfalse or true
backup_db_streamingoptionalfalse or true
backup_db_dumpall_singleoptionalfalse or true
backup_postgres_quickoptionalfalse or true
backup_encryption_keyoptionalRSA 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": []
  }
}
PATCHhttps://my.simplebackups.io/api/backup/{backup_id}/update

Update Backup

Update a backup. Note that storage_id, server_id and type cannot be updated.

JSON Body Fields

FieldRequiredDescription
namerequiredVPS-Server-Backup
db_typerequired unless type=fileMySQL, mongoDB or PostgreSQL
db_hostrequired unless type=filedb hostname, ex: 127.0.0.1
db_portrequired unless type=filedb port, ex: 3306
db_useroptionaldb user, ex: dbuser
db_pswoptionaldb password, ex: dbpass123
project_idoptionalproject id, ex: 2
db_namerequired unless type=filedatabase name or * for all MySQL databases
db_connection_stringeither this field or individual database fields should be passed for db backupsdatabase full connection string
file_pathrequired unless type=dbpath(s) to back up /home/sbio
excluded_file_pathrequired unless type=dbpath(s) to exclude from backup, ex: /home/*/vendor
storage_pathoptionalCustom path under your storage for the backup, example daily/db-backups
schedulerequiredon-demand, daily, weekly, custom
schedule_cronrequired when schedule=customcron expression, example: 0 23 * * 1-5
retentionrequirednumber of retained backups, example: 7
metaoptional, arrayadditional options for backup
secondary_schedulesoptional, arrayadditional schedules for backup
secondary_storagesoptional, arrayadditional storages for backup

JSON Meta Fields

Meta fieldRequiredDescription
backup_is_incrementaloptionalfalse or true
backup_tar_donot_expand_symlinksoptionalfalse or true
backup_tar_no_compressionoptionalfalse or true
backup_file_flatten_archive_contentsoptionalfalse or true
backup_file_streamingoptionalfalse or true
backup_tar_donot_ignore_failed_readoptionalfalse or true
backup_file_using_sudooptionalfalse or true
backup_store_uncompressed_dboptionalfalse or true
backup_is_incremental_databaseoptionalfalse or true
backup_db_streamingoptionalfalse or true
backup_db_dumpall_singleoptionalfalse or true
backup_postgres_quickoptionalfalse or true
backup_encryption_keyoptionalRSA 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": []
  }
}
GEThttps://my.simplebackups.io/api/backup/list

List Backups

List all backups on your SimpleBackups account.

Available filters:

  • id passed as URL parameter filters[id]=backup_id
  • name passed as URL parameter filters[name]=BackupName
  • status passed as URL parameter filters[status]=0 or filters[status]=1
  • type passed as URL parameter filters[type]=db (db, file, full, sync, recipe)
  • server passed as URL parameter filters[server]=server_id
  • storage passed as URL parameter filters[storage]=storage_id

Response

OK
GEThttps://my.simplebackups.io/api/backup/{backup_id}/run

Run Backup

Run a backup given its ID.

Path Parameters

NameTypeRequiredDescription
backup_idintegerrequiredID 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"
  }
}
PATCHhttps://my.simplebackups.io/api/backup/{backup_id}/pause

Pause Backup

Pause a backup schedule given its ID.

Path Parameters

NameTypeRequiredDescription
backup_idintegerrequiredID 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": []
}
PATCHhttps://my.simplebackups.io/api/backup/{backup_id}/resume

Resume Backup

Resume a backup schedule given its ID.

Path Parameters

NameTypeRequiredDescription
backup_idintegerrequiredID 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": []
}
POSThttps://my.simplebackups.io/api/backup/{backup_id}/delete

Delete Backup

Delete a backup job. This will not remove the backup copies stored on your storage.

Path Parameters

NameTypeRequiredDescription
backup_idintegerrequiredID of the backup to delete.

Response

{
  "success": true,
  "message": "Backup was successfully deleted!",
  "errors": [],
  "data": []
}

Servers

4 endpoints
GEThttps://my.simplebackups.io/api/server/list

List Servers

List all servers providers added to your SimpleBackups account.

Response

OK
POSThttps://my.simplebackups.io/api/server/add

Add 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

FieldType/ExampleDescription
namerequired, integer, My-Amazon-VPSName your server
connection_typerequired, string, passwordHow you connect to your server, can be ssh for SSH key authentication or password
hostrequired, string, 1.1.1.1SSH hostname or IP of your server
portrequired, integer, 22SSH port
userrequired, string, ubuntuSSH user
passwordoptional, string, mysteri0usFlyte$SSH password, required for password authentication
temp_directoryoptional, string, /home/ubuntuA directory used for temporary operations and retaining SimpleBackups settings on your server. Must have write access to it
project_idoptionalproject 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"
    }
  }
}
GEThttps://my.simplebackups.io/api/server/{server_id}/validate-connection

Validate 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

NameTypeRequiredDescription
server_idintegerrequiredID of the server to validate its connection.

Request Body

{}

Response

{
  "success": true,
  "data": {
    "status": true,
    "message": ""
  }
}
POSThttps://my.simplebackups.io/api/server/{server_id}/remove

Remove Server

Removes a server from your SimpleBackups dashboard, and also removes SimpleBackups' ability to connect to that server.

Path Parameters

NameTypeRequiredDescription
server_idintegerrequiredID of the server to remove.

Request Body

{}

Response

{
  "success": true,
  "message": "Server removal queued! May take a couple of minutes.",
  "errors": [],
  "data": []
}

Storage

1 endpoint
GEThttps://my.simplebackups.io/api/storage/list

List Storage

List all storage providers added to your SimpleBackups account.

Available URL filters

FieldExampleDescription
namefilters[name]=ServerName
statusfilters[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 endpoints
GEThttps://my.simplebackups.io/api/stats/activity

List Job Activity

Returns a list of jobs, ordered by descending creation date.

Available filters

FieldTypeDescription
date_fromoptional, date, default:1 month agoQuery from that date. Example: 2022-01-01
date_tooptional, date, default:nowQuery until that date. Example: 2022-01-31
typerequired, string, accepted values: backup, snapshot, cloudsyncType of resource to query. Example: backup
resource_idsoptional, string, accepted values: comma-separated idsType of resource to query. Example: 10,214,477

Response fields

FieldsTypeDescription
statusstringPossible values: success, error, rotated

Response

OK
GEThttps://my.simplebackups.io/api/stats/resource

List Resource Activity

Returns a list of resources (backup, snapshot or cloudsync), with their job activity and next scheduled jobs.

Available filters

FieldTypeDescription
date_fromoptional, date, default:1 month agoQuery from that date. Example: 2022-01-01
date_tooptional, date, default:nowQuery until that date. Example: 2022-01-31
typerequired, string, accepted values: backup, snapshot, cloudsyncType of resource to query. Example: backup
resource_idsoptional, string, accepted values: comma separated idsType 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": []
    }
  ]
}
GEThttps://my.simplebackups.io/api/stats/report

Activity 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

FieldTypeDescription
date_fromoptional, date, default:1 month agoQuery from that date. Example: 2022-01-01
date_tooptional, date, default:nowQuery until that date. Example: 2022-01-31

Response

OK
GEThttps://my.simplebackups.io/api/stats/schedule

Scheduled jobs list

Returns a list of the next 5 scheduled date for each resources.

Available filters

FieldTypeDescription
typerequired, string, accepted values: backup, snapshot, cloudsyncType of resource to query. Example: backup
resource_idsoptional, string, accepted values: comma separated idsType of resource to query. Example: 10,214,477

Response

OK

Teams

3 endpoints
GEThttps://my.simplebackups.io/api/team/list

List 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"
    }
  ]
}
GEThttps://my.simplebackups.io/api/team/current

Get 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"
  }
}
PATCHhttps://my.simplebackups.io/api/team/{team_id}/switch

Switch Team

Switch your account to use a team you belong to, given its ID.

Path Parameters

NameTypeRequiredDescription
team_idintegerrequiredID of the team to switch to and use for all subsequent requests.

Response

No Content
SimpleBackups Automation API — 1.0.0