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.

API v1

Version

GET
/api/v1/version
(BorgWarehouse version number)
Parameters

None

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

Scheduled Tasks

POST
/api/v1/cron/status
(Check status and send alerts)
Parameters

None

Headers
keyvalue
AuthorizationBearer CRONJOB_KEY
Responses
http codecontent-typeresponse
200application/json{"success":""Status cron executed successfully"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/v1/cron/status' --header 'Authorization: Bearer CRONJOB_KEY'
POST
/api/v1/cron/storage
(Refresh storage of repositories)
Parameters

None

Headers
keyvalue
AuthorizationBearer CRONJOB_KEY
Responses
http codecontent-typeresponse
200application/json{"success":"Storage cron executed successfully"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/v1/cron/storage' --header 'Authorization: Bearer CRONJOB_KEY'

Repositories actions

GET
/api/v1/repositories
Parameters

None

Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"repoList": [ ... ]}
Example cURL 
 curl -X GET -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/v1/repositories
POST
/api/v1/repositories
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).
commentstringnoAn optional comment about the repository, it can be an empty string.
alertnumbernoThe alert option (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 (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{"id": 2, "repositoryName": "c1ddd097"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/v1/repositories' \
 --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": 3600,
     "lanCommand": true,
     "appendOnlyMode": false
 }'
GET
/api/v1/repositories/{repositoryName}
Parameters
keytyperequireddescription
repositoryNamestringyesThe name of the repository to retrieve.
Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"repo": { ... }}
Example cURL 
 curl -X GET -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/v1/repositories/6edb4d1e
PATCH
/api/v1/repositories/{repositoryName}
Parameters
keytyperequireddescription
repositoryNamestringyesThe name 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":"Repository 5ecb2d6e has been edited"}
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/v1/repositories/5ecb2d6e
DELETE
/api/v1/repositories/{repositoryName}
Parameters
keytyperequireddescription
idstringyesThe ID of the repository to delete.
Headers
keyvalue
AuthorizationBearer YOUR_API_KEY
Responses
http codecontent-typeresponse
200application/json{"message":"Repository 5ecb2d6e deleted"}
Example cURL 
 curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/v1/repositories/5ecb2d6e
POST
/api/v1/repositories/{repositoryName}/compact
(Compact a repository to reclaim disk space)

Runs borg compact on the repository server-side to free space left by deleted/pruned archives. This operation never requires the repository passphrase. Compactions on different repositories can run in parallel, but the same repository cannot be compacted twice at the same time.

Parameters
keytyperequireddescription
repositoryNamestringyesThe name of the repository to compact.
Headers
keyvalue
AuthorizationBearer <API_KEY>
Responses
http codecontent-typeresponse
200application/json{"message":"Repository 5ecb2d6e has been compacted"}
403application/json{"message":"Compaction is disabled on this server"}
409application/json{"message":"A compaction is already running for this repository"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/v1/repositories/5ecb2d6e/compact' \
 --header 'Authorization: Bearer <API_KEY>'
POST
/api/v1/repositories/{repositoryName}/break-lock
(Release a stale lock on a repository)

Runs borg break-lock on the repository to release a stale lock left behind by an interrupted operation. This operation never requires the repository passphrase. Only use it when no backup or compaction is actually running on the repository.

Parameters
keytyperequireddescription
repositoryNamestringyesThe name of the repository to release the lock from.
Headers
keyvalue
AuthorizationBearer <API_KEY>
Responses
http codecontent-typeresponse
200application/json{"message":"Lock on repository 5ecb2d6e has been released"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/v1/repositories/5ecb2d6e/break-lock' \
 --header 'Authorization: Bearer <API_KEY>'
POST
/api/v1/repositories/{repositoryName}/archive
(Archive or unarchive a repository)

Freezes (or unfreezes) a repository. Archiving disables the client’s SSH access server-side (no push, prune or restore), pauses notifications and monitoring, and makes the repository read-only. This operation never requires the repository passphrase and is fully reversible: the repository data is untouched. While a repository is archived, PATCH /api/v1/repositories/{repositoryName} returns 403 until it is unarchived.

Parameters
keytyperequireddescription
repositoryNamestringyesThe name of the repository to archive or unarchive.
Body Parameters
keytyperequireddescription
archivedbooleanyestrue to archive the repository, false to unarchive it.
Headers
keyvalue
AuthorizationBearer <API_KEY>
Responses
http codecontent-typeresponse
200application/json{"message":"Repository 5ecb2d6e has been archived"}
400application/json{"message":"archived must be a boolean"}
Example cURL 
 curl -i --request POST --url 'https://localhost:3000/api/v1/repositories/5ecb2d6e/archive' \
 --header 'Authorization: Bearer <API_KEY>' \
 --header 'Content-Type: application/json' \
 --data-raw '{ "archived": true }'
API v0 (legacy)

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{"id": 2, "repositoryName": "c1ddd097"}
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
← Import old repositories
BorgWarehouse v1.x →