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.

💡

You can globally disable the ability to delete a repository in BorgWarehouse using the environment variable DISABLE_DELETE_REPO=true

💡

You can disable this feature using the environment variable DISABLE_INTEGRATIONS=true

API v1

Version

GET

/api/v1/version

(BorgWarehouse version number)

Parameters

None

Responses

http code content-type response
200 application/json {"version":"3.0.0"}

http code	content-type	response
`200`	`application/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

key value
Authorization Bearer CRONJOB_KEY

key	value
`Authorization`	`Bearer CRONJOB_KEY`

Responses

http code content-type response
200 application/json {"success":""Status cron executed successfully"}

http code	content-type	response
`200`	`application/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

key value
Authorization Bearer CRONJOB_KEY

key	value
`Authorization`	`Bearer CRONJOB_KEY`

Responses

http code content-type response
200 application/json {"success":"Storage cron executed successfully"}

http code	content-type	response
`200`	`application/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

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"repoList": [ ... ]}

http code	content-type	response
`200`	`application/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

key type required description
alias string yes The new alias for the repository.
sshPublicKey string yes The new SSH public key for the repository.
storageSize number yes The new storage size for the repository (must be an integer > 0).
comment string no An optional comment about the repository, it can be an empty string.
alert number no The alert option (must be a valid value from the alert array below).
lanCommand boolean no Indicates if LAN command is enabled.
appendOnlyMode boolean no Indicates if append-only mode is enabled.

key	type	required	description
`alias`	`string`	yes	The new alias for the repository.
`sshPublicKey`	`string`	yes	The new SSH public key for the repository.
`storageSize`	`number`	yes	The new storage size for the repository (must be an integer > 0).
`comment`	`string`	no	An optional comment about the repository, it can be an empty string.
`alert`	`number`	no	The alert option (must be a valid value from the `alert` array below).
`lanCommand`	`boolean`	no	Indicates if LAN command is enabled.
`appendOnlyMode`	`boolean`	no	Indicates if append-only mode is enabled.

Alert Options

The alert parameter must be one of the following values:

Valid values Time (for information only)
0 Disabled
3600 1 hour
21600 6 hours
43200 12 hours
90000 1 day
172800 2 days
259200 3 days
345600 4 days
432000 5 days
518400 6 days
604800 7 days
864000 10 days
1209600 14 days
2592000 30 days

Valid values	Time (for information only)
`0`	Disabled
`3600`	1 hour
`21600`	6 hours
`43200`	12 hours
`90000`	1 day
`172800`	2 days
`259200`	3 days
`345600`	4 days
`432000`	5 days
`518400`	6 days
`604800`	7 days
`864000`	10 days
`1209600`	14 days
`2592000`	30 days

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"id": 2, "repositoryName": "c1ddd097"}

http code	content-type	response
`200`	`application/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

key type required description
repositoryName string yes The name of the repository to retrieve.

key	type	required	description
`repositoryName`	`string`	yes	The name of the repository to retrieve.

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"repo": { ... }}

http code	content-type	response
`200`	`application/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

key type required description
repositoryName string yes The name of the repository to update.

key	type	required	description
`repositoryName`	`string`	yes	The name of the repository to update.

Body Parameters

key type required description
alias string no The new alias for the repository.
sshPublicKey string no The new SSH public key for the repository.
storageSize number no The new storage size for the repository (must be an integer > 0).
comment string no An optional comment about the repository.
alert number no The alert option ID (must be a valid value from the alert array below).
lanCommand boolean no Indicates if LAN command is enabled.
appendOnlyMode boolean no Indicates if append-only mode is enabled.

key	type	required	description
`alias`	`string`	no	The new alias for the repository.
`sshPublicKey`	`string`	no	The new SSH public key for the repository.
`storageSize`	`number`	no	The new storage size for the repository (must be an integer > 0).
`comment`	`string`	no	An optional comment about the repository.
`alert`	`number`	no	The alert option ID (must be a valid value from the `alert` array below).
`lanCommand`	`boolean`	no	Indicates if LAN command is enabled.
`appendOnlyMode`	`boolean`	no	Indicates if append-only mode is enabled.

Alert Options

The alert parameter must be one of the following values:

Valid values Time
0 Disabled
3600 1 hour
21600 6 hours
43200 12 hours
90000 1 day
172800 2 days
259200 3 days
345600 4 days
432000 5 days
518400 6 days
604800 7 days
864000 10 days
1209600 14 days
2592000 30 days

Valid values	Time
`0`	Disabled
`3600`	1 hour
`21600`	6 hours
`43200`	12 hours
`90000`	1 day
`172800`	2 days
`259200`	3 days
`345600`	4 days
`432000`	5 days
`518400`	6 days
`604800`	7 days
`864000`	10 days
`1209600`	14 days
`2592000`	30 days

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"message":"Repository 5ecb2d6e has been edited"}

http code	content-type	response
`200`	`application/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

key type required description
id string yes The ID of the repository to delete.

key	type	required	description
`id`	`string`	yes	The ID of the repository to delete.

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"message":"Repository 5ecb2d6e deleted"}

http code	content-type	response
`200`	`application/json`	`{"message":"Repository 5ecb2d6e deleted"}`

Example cURL

 curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3000/api/v1/repositories/5ecb2d6e

API v0 (legacy)

⚠️

This API is deprecated and was used with Borgwarehouse v2

Version

GET

/api/version

(Get the version number)

Parameters

None

Responses

http code content-type response
200 application/json {"version":"2.1.0"}

http code	content-type	response
`200`	`application/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

key value
Authorization Bearer CRONJOB_KEY

key	value
`Authorization`	`Bearer CRONJOB_KEY`

Responses

http code content-type response
200 application/json {"success":"Status cron has been executed."}
401 application/json {"status":401,"message":"Unauthorized"}

http code	content-type	response
`200`	`application/json`	`{"success":"Status cron has been executed."}`
`401`	`application/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

key value
Authorization Bearer CRONJOB_KEY

key	value
`Authorization`	`Bearer CRONJOB_KEY`

Responses

http code content-type response
200 application/json {"success":"Storage cron has been executed."}
401 application/json {"status":401,"message":"Unauthorized"}

http code	content-type	response
`200`	`application/json`	`{"success":"Storage cron has been executed."}`
`401`	`application/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

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"repoList": [ ... ]}
401 application/json {"message":"Unauthorized"}
403 application/json {"message":"Invalid API key"}
500 application/json {"message":"Internal Server Error"}

http code	content-type	response
`200`	`application/json`	`{"repoList": [ ... ]}`
`401`	`application/json`	`{"message":"Unauthorized"}`
`403`	`application/json`	`{"message":"Invalid API key"}`
`500`	`application/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

key type required description
id string yes The ID of the repository to retrieve.

key	type	required	description
`id`	`string`	yes	The ID of the repository to retrieve.

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"repo": { ... }}
401 application/json {"message":"Unauthorized"}
403 application/json {"message":"Invalid API key"}
404 application/json {"message":"No repository with id #ID"}
500 application/json {"status":500,"message":"Internal Server Error"}

http code	content-type	response
`200`	`application/json`	`{"repo": { ... }}`
`401`	`application/json`	`{"message":"Unauthorized"}`
`403`	`application/json`	`{"message":"Invalid API key"}`
`404`	`application/json`	`{"message":"No repository with id #ID"}`
`500`	`application/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

key type required description
alias string yes The new alias for the repository.
sshPublicKey string yes The new SSH public key for the repository.
storageSize number yes The new storage size for the repository (must be an integer > 0).
comment string yes An optional comment about the repository, it can be an empty string.
alert number yes The alert option ID (must be a valid value from the alert array below).
lanCommand boolean yes Indicates if LAN command is enabled.
appendOnlyMode boolean yes Indicates if append-only mode is enabled.

key	type	required	description
`alias`	`string`	yes	The new alias for the repository.
`sshPublicKey`	`string`	yes	The new SSH public key for the repository.
`storageSize`	`number`	yes	The new storage size for the repository (must be an integer > 0).
`comment`	`string`	yes	An optional comment about the repository, it can be an empty string.
`alert`	`number`	yes	The alert option ID (must be a valid value from the `alert` array below).
`lanCommand`	`boolean`	yes	Indicates if LAN command is enabled.
`appendOnlyMode`	`boolean`	yes	Indicates if append-only mode is enabled.

Alert Options

The alert parameter must be one of the following values:

Valid values Time (for information only)
0 Disabled
3600 1 hour
21600 6 hours
43200 12 hours
90000 1 day
172800 2 days
259200 3 days
345600 4 days
432000 5 days
518400 6 days
604800 7 days
864000 10 days
1209600 14 days
2592000 30 days

Valid values	Time (for information only)
`0`	Disabled
`3600`	1 hour
`21600`	6 hours
`43200`	12 hours
`90000`	1 day
`172800`	2 days
`259200`	3 days
`345600`	4 days
`432000`	5 days
`518400`	6 days
`604800`	7 days
`864000`	10 days
`1209600`	14 days
`2592000`	30 days

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"id": 2, "repositoryName": "c1ddd097"}
401 application/json {"message":"Unauthorized"}
409 application/json {"message":"The SSH key is already used in another repository."}
422 application/json {"message":"Unexpected data"}

http code	content-type	response
`200`	`application/json`	`{"id": 2, "repositoryName": "c1ddd097"}`
`401`	`application/json`	`{"message":"Unauthorized"}`
`409`	`application/json`	`{"message":"The SSH key is already used in another repository."}`
`422`	`application/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

key type required description
id string yes The ID of the repository to update.

key	type	required	description
`id`	`string`	yes	The ID of the repository to update.

Body Parameters

key type required description
alias string no The new alias for the repository.
sshPublicKey string no The new SSH public key for the repository.
storageSize number no The new storage size for the repository (must be an integer > 0).
comment string no An optional comment about the repository.
alert number no The alert option ID (must be a valid value from the alert array below).
lanCommand boolean no Indicates if LAN command is enabled.
appendOnlyMode boolean no Indicates if append-only mode is enabled.

key	type	required	description
`alias`	`string`	no	The new alias for the repository.
`sshPublicKey`	`string`	no	The new SSH public key for the repository.
`storageSize`	`number`	no	The new storage size for the repository (must be an integer > 0).
`comment`	`string`	no	An optional comment about the repository.
`alert`	`number`	no	The alert option ID (must be a valid value from the `alert` array below).
`lanCommand`	`boolean`	no	Indicates if LAN command is enabled.
`appendOnlyMode`	`boolean`	no	Indicates if append-only mode is enabled.

Alert Options

The alert parameter must be one of the following values:

Valid values Time
0 Disabled
3600 1 hour
21600 6 hours
43200 12 hours
90000 1 day
172800 2 days
259200 3 days
345600 4 days
432000 5 days
518400 6 days
604800 7 days
864000 10 days
1209600 14 days
2592000 30 days

Valid values	Time
`0`	Disabled
`3600`	1 hour
`21600`	6 hours
`43200`	12 hours
`90000`	1 day
`172800`	2 days
`259200`	3 days
`345600`	4 days
`432000`	5 days
`518400`	6 days
`604800`	7 days
`864000`	10 days
`1209600`	14 days
`2592000`	30 days

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"message":"success"}
400 application/json {"message":"Invalid request body"}
401 application/json {"message":"Unauthorized"}
403 application/json {"message":"Invalid API key"}
404 application/json {"message":"No repository with id #ID"}
409 application/json {"message":"The SSH key is already used in another repository."}
422 application/json {"message":"Unexpected data"}
500 application/json {"message":"Internal Server Error"}

http code	content-type	response
`200`	`application/json`	`{"message":"success"}`
`400`	`application/json`	`{"message":"Invalid request body"}`
`401`	`application/json`	`{"message":"Unauthorized"}`
`403`	`application/json`	`{"message":"Invalid API key"}`
`404`	`application/json`	`{"message":"No repository with id #ID"}`
`409`	`application/json`	`{"message":"The SSH key is already used in another repository."}`
`422`	`application/json`	`{"message":"Unexpected data"}`
`500`	`application/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

key type required description
id string yes The ID of the repository to delete.

key	type	required	description
`id`	`string`	yes	The ID of the repository to delete.

Headers

key value
Authorization Bearer YOUR_API_KEY

key	value
`Authorization`	`Bearer YOUR_API_KEY`

Responses

http code content-type response
200 application/json {"message":"success"}
401 application/json {"message":"Unauthorized"}
403 application/json {"message":"Invalid API key"}
404 application/json {"message":"No repository with id #ID"}
405 application/json {"message":"Method Not Allowed"}
500 application/json {"status":500,"message":"Internal Server Error"}

http code	content-type	response
`200`	`application/json`	`{"message":"success"}`
`401`	`application/json`	`{"message":"Unauthorized"}`
`403`	`application/json`	`{"message":"Invalid API key"}`
`404`	`application/json`	`{"message":"No repository with id #ID"}`
`405`	`application/json`	`{"message":"Method Not Allowed"}`
`500`	`application/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

API

Version #

Parameters #

Responses #

Example cURL #

Scheduled Tasks #

Parameters #

Headers #

Responses #

Example cURL #

Parameters #

Headers #

Responses #

Example cURL #

Repositories actions #

Parameters #

Headers #

Responses #

Example cURL #

Body Parameters #

Alert Options #

Headers #

Responses #

Example cURL #

Parameters #

Headers #

Responses #

Example cURL #

Parameters #

Body Parameters #

Alert Options #

Headers #

Responses #

Example cURL #

Parameters #

Headers #

Responses #

Example cURL #

Version #

Parameters #

Responses #

Example cURL #

Scheduled Tasks #

Parameters #

Headers #

Responses #

Example cURL #

Parameters #

Headers #

Responses #

Example cURL #

Repositories actions #

Parameters #

Headers #

Responses #

Example cURL #

Parameters #

Headers #

Responses #

Example cURL #

Body Parameters #

Alert Options #

Headers #

Responses #

Example cURL #

Parameters #

Body Parameters #

Alert Options #

Headers #

Responses #

Example cURL #

Parameters #

Headers #

Responses #

Example cURL #

Version

Parameters

Responses

Example cURL

Scheduled Tasks

Parameters

Headers

Responses

Example cURL

Parameters

Headers

Responses

Example cURL

Repositories actions

Parameters

Headers

Responses

Example cURL

Body Parameters

Alert Options

Headers

Responses

Example cURL

Parameters

Headers

Responses

Example cURL

Parameters

Body Parameters

Alert Options

Headers

Responses

Example cURL

Parameters

Headers

Responses

Example cURL

Version

Parameters

Responses

Example cURL

Scheduled Tasks

Parameters

Headers

Responses

Example cURL

Parameters

Headers

Responses

Example cURL

Repositories actions

Parameters

Headers

Responses

Example cURL

Parameters

Headers

Responses

Example cURL

Body Parameters

Alert Options

Headers

Responses

Example cURL

Parameters

Body Parameters

Alert Options

Headers

Responses

Example cURL

Parameters

Headers

Responses

Example cURL