CyBorgBackup API¶

Actually, only the V1 version of the API is available. They can be access on the url /api of the webserver and the V1 api on the url /api/v1.

Main API V1¶

GET /api/v1¶

Retrieve all available submodule of the API.

Example request:

$ curl https://cyborgbackup.local/api/v1/

Example response:

{
    "ping": "/api/v1/ping",
    "config": "/api/v1/config/",
    "me": "/api/v1/me/"
}

GET /api/v1/ping¶

Test the api and get the version

{
    "version": "1.0"
    "ping": "pong"
}

GET /api/v1/config¶

Retrieve some configuration of the CyBorgBackup instance.

{
    "version": "1.0"
    "debug": true,
    "allowed_hosts" : ["127.0.0.1"]
}

GET /api/v1/me¶

Retrieve information about the current logged user.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        "id": 1,
        "type": "user",
        "url": "/api/v1/users/1/",
        "related": {},
        "summary_fields": {},
        "created": "2018-11-08T16:13:29.370148Z",
        "first_name": "",
        "last_name": "",
        "email": "admin@milkywan.fr",
        "is_superuser": true
    ]
}

Users API V1¶

GET /api/v1/users/¶

Retrieve a list of all users.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [USERS]
}

Response JSON Object:
	next (string) – URI for next set of Users. previous (string) – URI for previous set of Users. count (integer) – Total number of Users. results (array) – Array of `Users` objects.

GET /api/v1/users/(int: id)/¶

Retrieve details of a single user.

{
    "id": 3,
    "type": "user",
    "url": "/api/v1/users/3/",
    "related": {},
    "summary_fields": {},
    "created": "2018-11-11T19:43:24.261706Z",
    "first_name": "",
    "last_name": "",
    "email": "cyborg@agent.local",
    "is_superuser": true
}

Response JSON Object:

id (integer) – The ID of the user
type (string) – The object type under cyborgbackup system.
url (string) – The URL access of the user object.
related (dict) – Related property of mapped object
summary_fields (dict) – Some summary field of object relation
created (string) – The creation date of the user
first_name (string) – First name of the user
last_name (string) – Last name of the user
email (string) – Email of the user
is_superuser (boolean) – Super User

Status Codes:

200 OK – no error
404 Not Found – There is no User with this ID

POST /api/v1/users/¶

Create a single user.

{
    "first_name": "",
    "last_name": "",
    "email": "cyborg@agent.local",
    "is_superuser": true
}

Response JSON Object:
	first_name (string) – First name of the user last_name (string) – Last name of the user email (string) – Email of the user is_superuser (boolean) – Super User
Status Codes:	200 OK – no error 404 Not Found – There is no `User` with this ID

PATCH /api/v1/users/(int: id)/¶

Update a single user.

{
    "first_name": "",
    "last_name": "",
    "email": "cyborg@agent.local",
    "is_superuser": true
}

Response JSON Object:
	id (integer) – The ID of the user first_name (string) – First name of the user last_name (string) – Last name of the user email (string) – Email of the user is_superuser (boolean) – Super User
Status Codes:	200 OK – no error 404 Not Found – There is no `User` with this ID

DELETE /api/v1/users/(int: id)/¶

Delete a single user.

Status Codes:	200 OK – no error 404 Not Found – There is no `User` with this ID

Clients API V1¶

GET /api/v1/clients/¶

Retrieve a list of all clients.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [CLIENTS]
}

Response JSON Object:
	next (string) – URI for next set of Clients. previous (string) – URI for previous set of Clients. count (integer) – Total number of Clients. results (array) – Array of `Clients` objects.

GET /api/v1/clients/(int: id)/¶

Retrieve details of a single client.

{
    "id": 1,
    "type": "client",
    "url": "/api/v1/clients/1/",
    "related": {},
    "summary_fields": {},
    "created": "2018-11-22T18:17:51.831221Z",
    "modified": "2018-11-22T19:21:16.011127Z",
    "created_by": null,
    "modified_by": null,
    "hostname": "lab.example.com",
    "ip": "",
    "version": "",
    "ready": false,
    "hypervisor_ready": false,
    "hypervisor_name": "",
    "enabled": true,
    "uuid": "fa3462e3-57da-430e-bca5-3bc60d4ba5a2"
}

Response JSON Object:

id (integer) – The ID of the client
type (string) – The object type under cyborgbackup system.
url (string) – The URL access of the client object.
related (dict) – Related property of mapped object
summary_fields (dict) – Some summary field of object relation
created (string) – The creation date of the client
modified (string) – The modification date of the client
created_by (string) – User responsible of the creation of the client
modified_by (string) – User responsible of the last modification
hostname (string) – Client Hostname
ip (string) – IP Addresses of the client
version (string) – Borg Client Version
ready (boolean) – Client prepared to be use with borg
hypervisor_name (string) – Hypervisor name of the client
hypervisor_ready (boolean) – Hypervisor prepared to be use with borg
enabled (boolean) – Client enabled
uuid (string) – Auto generated UUID

Status Codes:

200 OK – no error
404 Not Found – There is no Client with this ID

POST /api/v1/clients/¶

Create a single client.

{
    "hostname": "lab.example.com",
    "ip": "",
    "version": "",
    "ready": false,
    "hypervisor_ready": false,
    "hypervisor_name": "",
    "enabled": true,
}

Response JSON Object:
	hostname (string) – Client Hostname ip (string) – IP Addresses of the client version (string) – Borg Client Version ready (boolean) – Client prepared to be use with borg hypervisor_name (string) – Hypervisor name of the client hypervisor_ready (boolean) – Hypervisor prepared to be use with borg enabled (boolean) – Client enabled
Status Codes:	200 OK – no error 404 Not Found – There is no `Client` with this ID

PATCH /api/v1/clients/(int: id)/¶

Update a single client.

{
    "hostname": "lab.example.com",
    "ip": "",
    "version": "",
    "ready": false,
    "hypervisor_ready": false,
    "hypervisor_name": "",
    "enabled": true
}

Response JSON Object:

id (integer) – The ID of the client
hostname (string) – Client Hostname
ip (string) – IP Addresses of the client
version (string) – Borg Client Version
ready (boolean) – Client prepared to be use with borg
hypervisor_name (string) – Hypervisor name of the client
hypervisor_ready (boolean) – Hypervisor prepared to be use with borg
enabled (boolean) – Client enabled

Status Codes:

200 OK – no error
404 Not Found – There is no Client with this ID

DELETE /api/v1/clients/(int: id)/¶

Delete a single client.

Status Codes:	200 OK – no error 404 Not Found – There is no `Client` with this ID

Schedules API V1¶

GET /api/v1/schedules/¶

Retrieve a list of all schedules.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [SCHEDULES]
}

Response JSON Object:
	next (string) – URI for next set of Schedules. previous (string) – URI for previous set of Schedules. count (integer) – Total number of Schedules. results (array) – Array of `Schedule` objects.

GET /api/v1/schedules/(int: id)/¶

Retrieve details of a single schedule.

{
    "id": 1,
    "type": "schedule",
    "url": "/api/v1/schedules/1/",
    "related": {},
    "summary_fields": {},
    "created": "2018-11-22T18:17:51.831221Z",
    "modified": "2018-11-22T19:21:16.011127Z",
    "created_by": null,
    "modified_by": null,
    "name": "Every Minutes",
    "crontab": "*/1 * * * * *",
    "enabled": true,
    "uuid": "fa3462e3-57da-430e-bca5-3bc60d4ba5a2"
}

Response JSON Object:

id (integer) – The ID of the schedule
type (string) – The object type under cyborgbackup system.
url (string) – The URL access of the schedule object.
related (dict) – Related property of mapped object
summary_fields (dict) – Some summary field of object relation
created (string) – The creation date of the schedule
modified (string) – The modification date of the schedule
created_by (string) – User responsible of the creation of the schedule
modified_by (string) – User responsible of the last modification
name (string) – Schedule name
crontab (string) – Crontab schedule
enabled (boolean) – Schedule enabled
uuid (string) – Auto generated UUID

Status Codes:

200 OK – no error
404 Not Found – There is no Schedule with this ID

POST /api/v1/schedules/¶

Create a single schedule.

{
    "name": "Every Minutes",
    "crontab": "*/1 * * * * *",
    "enabled": true
}

Response JSON Object:
	name (string) – Schedule name crontab (string) – Crontab schedule enabled (boolean) – Schedule enabled
Status Codes:	200 OK – no error 404 Not Found – There is no `Schedule` with this ID

PATCH /api/v1/schedules/(int: id)/¶

Update a single schedule.

{
    "name": "Every Monday",
    "crontab": "0 5 * * MON *",
    "enabled": true
}

Response JSON Object:
	id (integer) – The ID of the schedule name (string) – Schedule name crontab (string) – Crontab schedule enabled (boolean) – Schedule enabled
Status Codes:	200 OK – no error 404 Not Found – There is no `Schedule` with this ID

DELETE /api/v1/schedules/(int: id)/¶

Delete a single schedule.

Status Codes:	200 OK – no error 404 Not Found – There is no `Schedule` with this ID

Repositories API V1¶

GET /api/v1/repositories/¶

Retrieve a list of all repositories.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [REPOSITORIES]
}

Response JSON Object:
	next (string) – URI for next set of Repositories. previous (string) – URI for previous set of Repositories. count (integer) – Total number of Repositories. results (array) – Array of `Repository` objects.

GET /api/v1/repositories/(int: id)/¶

Retrieve details of a single repository.

{
    "id": 1,
    "type": "repository",
    "url": "/api/v1/repositories/1/",
    "related": {},
    "summary_fields": {},
    "created": "2018-11-22T18:17:51.831221Z",
    "modified": "2018-11-22T19:21:16.011127Z",
    "created_by": null,
    "modified_by": null,
    "name": "Main Repo",
    "path": "cyborgbackup@backup:/repository",
    "repository_key": "0123456789abcdef",
    "original_size": 722,
    "compressed_size": 747,
    "deduplicated_size": 747,
    "ready": true,
    "enabled": true,
    "uuid": "fa3462e3-57da-430e-bca5-3bc60d4ba5a2"
}

Response JSON Object:

id (integer) – The ID of the repository
type (string) – The object type under cyborgbackup system.
url (string) – The URL access of the repository object.
related (dict) – Related property of mapped object
summary_fields (dict) – Some summary field of object relation
created (string) – The creation date of the repository
modified (string) – The modification date of the repository
created_by (string) – User responsible of the creation of the repository
modified_by (string) – User responsible of the last modification
name (string) – Repository name
path (string) – URI path to access the repository from each client
repository_key (string) – Key used to encrypt the repository
original_size (integer) – Calculated size of all archives
compressed_size (integer) – Calculated compressed size of all archives
deduplicated_size (integer) – Calculated deduplicated size of all archives
ready (boolean) – Repository prepared to be use with borg
enabled (boolean) – Repository enabled
uuid (string) – Auto generated UUID

Status Codes:

200 OK – no error
404 Not Found – There is no Repository with this ID

POST /api/v1/repositories/¶

Create a single repository.

{
    "name": "Main Repo",
    "path": "cyborgbackup@backup:/repository",
    "repository_key": "0123456789abcdef",
    "ready": true,
    "enabled": true
}

Response JSON Object:
	name (string) – Repository name path (string) – URI path to access the repository from each client repository_key (string) – Key used to encrypt the repository ready (boolean) – Repository prepared to be use with borg enabled (boolean) – Repository enabled
Status Codes:	200 OK – no error 404 Not Found – There is no `Repository` with this ID

PATCH /api/v1/repositories/(int: id)/¶

Update a single repository.

{
    "name": "Main Repo",
    "path": "cyborgbackup@backup:/repository",
    "repository_key": "0123456789abcdef",
    "ready": true,
    "enabled": true
}

Response JSON Object:
	id (integer) – The ID of the repository name (string) – Repository name path (string) – URI path to access the repository from each client repository_key (string) – Key used to encrypt the repository ready (boolean) – Repository prepared to be use with borg enabled (boolean) – Repository enabled
Status Codes:	200 OK – no error 404 Not Found – There is no `Repository` with this ID

DELETE /api/v1/repositories/(int: id)/¶

Delete a single repository.

Status Codes:	200 OK – no error 404 Not Found – There is no `Repository` with this ID

Policies API V1¶

GET /api/v1/policies/¶

Retrieve a list of all policies.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [POLICIES]
}

Response JSON Object:
	next (string) – URI for next set of Policies. previous (string) – URI for previous set of Policies. count (integer) – Total number of Policies. results (array) – Array of `Policy` objects.

GET /api/v1/policies/(int: id)/¶

Retrieve details of a single policy.

{
    "id": 1,
    "type": "policy",
    "url": "/api/v1/policies/1/",
    "related": {
        "launch": "/api/v1/policies/1/launch/",
        "calendar": "/api/v1/policies/1/calendar/",
        "schedule": "/api/v1/schedules/1/",
        "repository": "/api/v1/repositories/1/"
    },
    "summary_fields": {
        "repository": {
            "id": 1,
            "name": "Main Repo",
            "path": "cyborgbackup@backup:/repository"
        },
        "schedule": {
            "id": 1,
            "name": "Each Monday",
            "crontab": "0 5 * * MON *"
        }
    },
    "created": "2018-11-22T18:51:22.894984Z",
    "modified": "2018-11-23T20:54:51.013495Z",
    "created_by": null,
    "modified_by": null,
    "uuid": "3a67b010-bbc4-43de-937e-11270c710aad",
    "name": "Full Features",
    "extra_vars": "",
    "clients": [
        1
    ],
    "repository": 1,
    "schedule": 1,
    "policy_type": "vm",
    "keep_hourly": 1,
    "keep_yearly": null,
    "keep_daily": null,
    "keep_weekly": null,
    "keep_monthly": null,
    "vmprovider": "proxmox",
    "next_run": "2018-11-26T05:00:00Z",
    "mode_pull": false,
    "enabled": true
}

Response JSON Object:

id (integer) – The ID of the policy
type (string) – The object type under cyborgbackup system.
url (string) – The URL access of the policy object.
related (dict) – Related property of mapped object
summary_fields (dict) – Some summary field of object relation
created (string) – The creation date of the policy
modified (string) – The modification date of the policy
created_by (string) – User responsible of the creation of the policy
modified_by (string) – User responsible of the last modification
name (string) – Policy name
extra_vars (string) – JSON Dictionnary of variable used by the system
clients (array) – Array of Client ID
repository (integer) – Repository ID
schedule (integer) – Schedule ID
policy_type (string) – Policy Backup Type
keep_hourly (integer) – Number of hourly archives to keep
keep_daily (integer) – Number of daily archives to keep
keep_weekly (integer) – Number of weekly archives to keep
keep_monthly (integer) – Number of monthly archives to keep
keep_yearly (integer) – Number of yearly archives to keep
vmprovider (string) – Name of the VM module provider
next_run (string) – Date of the next run of the backup job
mode_pull (boolean) – Backup in pull mode
enabled (boolean) – Policy enabled
uuid (string) – Auto generated UUID

Status Codes:

200 OK – no error
404 Not Found – There is no Policy with this ID

POST /api/v1/policies/¶

Create a single policy.

{
    "name": "Full Features",
    "extra_vars": "",
    "clients": [
        1
    ],
    "repository": 1,
    "schedule": 1,
    "policy_type": "vm",
    "keep_hourly": 1,
    "keep_yearly": null,
    "keep_daily": null,
    "keep_weekly": null,
    "keep_monthly": null,
    "vmprovider": "proxmox",
    "mode_pull": false,
    "enabled": true
}

Response JSON Object:

name (string) – Policy name
extra_vars (string) – JSON Dictionnary of variable used by the system
clients (array) – Array of Client ID
repository (integer) – Repository ID
schedule (integer) – Schedule ID
policy_type (string) – Policy Backup Type
keep_hourly (integer) – Number of hourly archives to keep
keep_daily (integer) – Number of daily archives to keep
keep_weekly (integer) – Number of weekly archives to keep
keep_monthly (integer) – Number of monthly archives to keep
keep_yearly (integer) – Number of yearly archives to keep
vmprovider (string) – Name of the VM module provider
mode_pull (boolean) – Backup in pull mode
enabled (boolean) – Policy enabled

Status Codes:

200 OK – no error
404 Not Found – There is no Policy with this ID

PATCH /api/v1/policies/(int: id)/¶

Update a single repository.

{
    "name": "Main Repo",
    "path": "cyborgbackup@backup:/repository",
    "repository_key": "0123456789abcdef",
    "ready": true,
    "enabled": true
}

Response JSON Object:

name (string) – Policy name
extra_vars (string) – JSON Dictionnary of variable used by the system
clients (array) – Array of Client ID
repository (integer) – Repository ID
schedule (integer) – Schedule ID
policy_type (string) – Policy Backup Type
keep_hourly (integer) – Number of hourly archives to keep
keep_daily (integer) – Number of daily archives to keep
keep_weekly (integer) – Number of weekly archives to keep
keep_monthly (integer) – Number of monthly archives to keep
keep_yearly (integer) – Number of yearly archives to keep
vmprovider (string) – Name of the VM module provider
mode_pull (boolean) – Backup in pull mode
enabled (boolean) – Policy enabled

Status Codes:

200 OK – no error
404 Not Found – There is no Policy with this ID

DELETE /api/v1/policies/(int: id)/¶

Delete a single repository.

Status Codes:	200 OK – no error 404 Not Found – There is no `Policy` with this ID

POST /api/v1/policies/(int: id)/launch/¶

Launch a backup job based on the policy.

Status Codes:	200 OK – no error 404 Not Found – There is no `Policy` with this ID

GET /api/v1/policies/(int: id)/calendar/¶

Get all datetime of the current month for each run of the policy

[DATETIME]

Status Codes:	200 OK – no error 404 Not Found – There is no `Policy` with this ID

Catalogs API V1¶

GET /api/v1/catalogs/¶

Retrieve a list of all catalogs entries.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [CATALOGS]
}

Response JSON Object:
	next (string) – URI for next set of Catalogs. previous (string) – URI for previous set of Catalogs. count (integer) – Total number of Catalogs. results (array) – Array of `Catalog` objects.

GET /api/v1/catalogs/(int: id)/¶

Retrieve details of a single catalog entry.

{
    "id": 1,
    "url": "/api/v1/catalogs/1/",
    "archive_name": "vm-lab.example.com-2018-11-23_22-02",
    "path": "stdin",
    "job": 1,
    "mode": "-rw-rw----",
    "mtime": "2018-11-23T23:03:52Z",
    "owner": "root",
    "group": "root",
    "size": 12,
    "healthy": true
}

Response JSON Object:

id (integer) – The ID of the catalog entry
url (string) – The URL access of the repository object.
archive_name (string) – The Borg Backup archive name
path (string) – Full path of the file in the archive
job (integer) – Job ID catalog entry related
mode (string) – Unix mode of the file
mtime (string) – Latest modification date of the file
owner (string) – Owner of the file
group (string) – Group of the file
size (integer) – Size of the file in Bytes
healthy (boolean) – Healthy state of the file

Status Codes:

200 OK – no error
404 Not Found – There is no Repository with this ID

CyBorgBackup API¶

Main API V1¶

Users API V1¶

Clients API V1¶

Schedules API V1¶

Repositories API V1¶

Policies API V1¶

Catalogs API V1¶

Useful Links

Table of Contents

Related Topics