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:
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:
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:
DELETE /api/v1/users/(int: id)/

Delete a single user.

Status Codes:

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:
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:
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:
DELETE /api/v1/clients/(int: id)/

Delete a single client.

Status Codes:

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:
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:
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:
DELETE /api/v1/schedules/(int: id)/

Delete a single schedule.

Status Codes:

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:
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:
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:
DELETE /api/v1/repositories/(int: id)/

Delete a single repository.

Status Codes:

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:
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:
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:
DELETE /api/v1/policies/(int: id)/

Delete a single repository.

Status Codes:
POST /api/v1/policies/(int: id)/launch/

Launch a backup job based on the policy.

Status Codes:
GET /api/v1/policies/(int: id)/calendar/

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

[DATETIME]
Status Codes:

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: