API

BorgBackup server control via REST API now available with BorgWarehouse !

BorgWarehouse’s API makes it even more powerful! Generate easily API tokens from the web interface and retrieve information from your repositories, create new ones, modify them…

To create new tokens, go to Account > Integrations in BorgWarehouse. The permissions are simple :

  • create : you can add new repositories
  • read : you can retrieve informations about your repositories
  • update : you can modify some informations on a repository
  • delete : you can delete repositories

The authentication is a Bearer authentication, it should be passed as HTTP HEADER and the content type for data is application/json :

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Examples of curl commands are provided in the endpoint documentation below.

Version

GET
/api/version
(Get the version number)
Parameters

None

Responses
http codecontent-typeresponse
200application/json{"version":"2.1.0"}
Example cURL 
 curl -X GET -H "Content-Type: application/json" https://localhost:3000/api/version

Scheduled Tasks

POST
/api/cronjob/checkStatus
(Check status and send alerts)
Parameters

None

Headers
keyvalue
AuthorizationBearer CRONJOB_KEY
Responses
http codecontent-typeresponse
200application/json{"success":"Status cron has been executed."}
401application/json{"status":401,"message":"Unauthorized"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/cronjob/checkStatus' --header 'Authorization: Bearer CRONJOB_KEY'
POST
/api/cronjob/getStorageUsed
(Retrieve storage of repositories)
Parameters

None

Headers
keyvalue
AuthorizationBearer CRONJOB_KEY
Responses
http codecontent-typeresponse
200application/json{"success":"Storage cron has been executed."}
401application/json{"status":401,"message":"Unauthorized"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/cronjob/getStorageUsed' --header 'Authorization: Bearer CRONJOB_KEY'

Repositories actions

GET
/api/repo
(Retrieve a list of repositories)
Parameters

None

Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"repoList": [ ... ]}
401application/json{"message":"Unauthorized"}
403application/json{"message":"Invalid API key"}
500application/json{"message":"Internal Server Error"}
Example cURL 
 curl -X GET -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/repo
GET
/api/repo/id/[id]
(Retrieve details of a specific repository by ID)
Parameters
keytyperequireddescription
idstringyesThe ID of the repository to retrieve.
Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"repo": { ... }}
401application/json{"message":"Unauthorized"}
403application/json{"message":"Invalid API key"}
404application/json{"message":"No repository with id #ID"}
500application/json{"status":500,"message":"Internal Server Error"}
Example cURL 
 curl -X GET -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/repo/id/1
POST
/api/repo/add
(Create a new repository)
Body Parameters
keytyperequireddescription
aliasstringyesThe new alias for the repository.
sshPublicKeystringyesThe new SSH public key for the repository.
storageSizenumberyesThe new storage size for the repository (must be an integer > 0).
commentstringyesAn optional comment about the repository, it can be an empty string.
alertnumberyesThe alert option ID (must be a valid value from the alert array below).
lanCommandbooleanyesIndicates if LAN command is enabled.
appendOnlyModebooleanyesIndicates if append-only mode is enabled.
Alert Options

The alert parameter must be one of the following values:

Valid valuesTime (for information only)
0Disabled
36001 hour
216006 hours
4320012 hours
900001 day
1728002 days
2592003 days
3456004 days
4320005 days
5184006 days
6048007 days
86400010 days
120960014 days
259200030 days
Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"message":"success"}
401application/json{"message":"Unauthorized"}
409application/json{"message":"The SSH key is already used in another repository."}
422application/json{"message":"Unexpected data"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/repo/add' \
 --header 'Authorization: Bearer YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data-raw '{
     "alias": "MyRepoAlias",
     "sshPublicKey": "ssh-rsa AAAA...",
     "storageSize": 100,
     "comment": "This is my new repo",
     "alert": 1,
     "lanCommand": true,
     "appendOnlyMode": false
 }'
PATCH
/api/repo/id/[id]/edit
(Update a specific repository by ID)
Parameters
keytyperequireddescription
idstringyesThe ID of the repository to update.
Body Parameters
keytyperequireddescription
aliasstringnoThe new alias for the repository.
sshPublicKeystringnoThe new SSH public key for the repository.
storageSizenumbernoThe new storage size for the repository (must be an integer > 0).
commentstringnoAn optional comment about the repository.
alertnumbernoThe alert option ID (must be a valid value from the alert array below).
lanCommandbooleannoIndicates if LAN command is enabled.
appendOnlyModebooleannoIndicates if append-only mode is enabled.
Alert Options

The alert parameter must be one of the following values:

Valid valuesTime
0Disabled
36001 hour
216006 hours
4320012 hours
900001 day
1728002 days
2592003 days
3456004 days
4320005 days
5184006 days
6048007 days
86400010 days
120960014 days
259200030 days
Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"message":"success"}
400application/json{"message":"Invalid request body"}
401application/json{"message":"Unauthorized"}
403application/json{"message":"Invalid API key"}
404application/json{"message":"No repository with id #ID"}
409application/json{"message":"The SSH key is already used in another repository."}
422application/json{"message":"Unexpected data"}
500application/json{"message":"Internal Server Error"}
Example cURL 
 curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
 --data-raw '{
     "alias": "UpdatedRepoAlias",
     "sshPublicKey": "ssh-rsa AAAA...",
     "storageSize": 200,
     "comment": "Updated comment",
     "alert": 3600,
     "lanCommand": false,
     "appendOnlyMode": true
 }' https://localhost:3000/api/repo/id/1/edit
DELETE
/api/repo/id/[id]/delete
(Delete a specific repository by ID)
Parameters
keytyperequireddescription
idstringyesThe ID of the repository to delete.
Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"message":"success"}
401application/json{"message":"Unauthorized"}
403application/json{"message":"Invalid API key"}
404application/json{"message":"No repository with id #ID"}
405application/json{"message":"Method Not Allowed"}
500application/json{"status":500,"message":"Internal Server Error"}
Example cURL 
 curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/repo/id/1234/delete
← How to update ?
BorgWarehouse v1.x →