SelfPrivacy
/
wiki.selfprivacy.org
7
1
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity
wiki.selfprivacy.org/src/rest-api/api.md

40 KiB
Raw Blame History

SelfPrivacy API

API available as Swagger documentation, markdown version is below.

Version

1.2.0

Content negotiation

URI Scheme: http

Consumes: application/json

Produces: application/json

Access control

  • bearerAuth

All endpoints

backups

Method URI Name Summary
GET /services/restic/backup/list get services restic backup list Get all restic backups
GET /services/restic/backup/reload get services restic backup reload Force reload snapshots
GET /services/restic/backup/status get services restic backup status Get backup status
PUT /services/restic/backblaze/config put services restic backblaze config Set the new key for backblaze
PUT /services/restic/backup/create put services restic backup create Initiate a new restic backup
PUT /services/restic/backup/restore put services restic backup restore Start backup restoration

bitwarden

Method URI Name Summary
POST /services/bitwarden/disable post services bitwarden disable Disable Bitwarden
POST /services/bitwarden/enable post services bitwarden enable Enable Bitwarden

email

Method URI Name Summary
GET /services/mailserver/dkim get services mailserver dkim Get DKIM key from file

gitea

Method URI Name Summary
POST /services/gitea/disable post services gitea disable Disable Gitea
POST /services/gitea/enable post services gitea enable Enable Gitea

nextcloud

Method URI Name Summary
POST /services/nextcloud/disable post services nextcloud disable Disable Nextcloud
POST /services/nextcloud/enable post services nextcloud enable Enable Nextcloud

o_cserv

Method URI Name Summary
POST /services/ocserv/disable post services ocserv disable Disable OCserv
POST /services/ocserv/enable post services ocserv enable Enable OCserv

pleroma

Method URI Name Summary
POST /services/pleroma/disable post services pleroma disable Disable Pleroma
POST /services/pleroma/enable post services pleroma enable Enable Pleroma

services

Method URI Name Summary
GET /services/status get services status Get service status

ssh

Method URI Name Summary
DELETE /services/ssh/keys/{username} delete services SSH keys username Delete SSH key
GET /services/ssh get services SSH Get current SSH settings
GET /services/ssh/keys/{username} get services SSH keys username List SSH keys
POST /services/ssh/enable post services SSH enable Enable SSH
POST /services/ssh/keys/{username} post services SSH keys username Add SSH key to the user
PUT /services/ssh put services SSH Change SSH settings
PUT /services/ssh/key/send put services SSH key send Add a SSH root key

system

Method URI Name Summary
GET /api/version get API version Get API version
GET /system/configuration/apply get system configuration apply Rebuild NixOS with nixos-rebuild switch
GET /system/configuration/autoUpgrade get system configuration auto upgrade Get current system autoupgrade settings
GET /system/configuration/pull get system configuration pull Pull Repository Changes
GET /system/configuration/rollback get system configuration rollback Rollback NixOS with nixos-rebuild switch --rollback
GET /system/configuration/timezone get system configuration timezone Get current system timezone
GET /system/configuration/upgrade get system configuration upgrade Upgrade NixOS with nixos-rebuild switch --upgrade
GET /system/pythonVersion get system python version Get python version used by this API
GET /system/reboot get system reboot Reboot the system
GET /system/version get system version Get system version from uname -a
PUT /system/configuration/autoUpgrade put system configuration auto upgrade Change system auto upgrade settings
PUT /system/configuration/timezone put system configuration timezone Change system timezone

tokens

Method URI Name Summary
DELETE /auth/tokens delete auth tokens Delete token
GET /auth/recovery_token get auth recovery token Get recovery token status
GET /auth/tokens get auth tokens Get current device tokens
POST /auth/new_device post auth new device Get new device token
POST /auth/new_device/authorize post auth new device authorize Authorize device
POST /auth/recovery_token post auth recovery token Generate recovery token
POST /auth/recovery_token/use post auth recovery token use Use recovery token
POST /auth/tokens post auth tokens Refresh token

users

Method URI Name Summary
DELETE /users/{username} delete users username Delete a user
GET /users get users Get a list of users
POST /users post users Create a new user

Paths

Delete token (DeleteAuthTokens)

DELETE /auth/tokens

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
token body DeleteAuthTokensBody DeleteAuthTokensBody ✓ Token's name to delete

All responses

Code Status Description
200 OK Token deleted
400 Bad Request Bad request
404 Not Found Token not found
Inlined models

DeleteAuthTokensBody

Properties

Name Type Go type Required Default Description Example
token string string ✓ Token name to delete

Delete SSH key (DeleteServicesSSHKeysUsername)

DELETE /services/ssh/keys/{username}

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
username path string string ✓ User to delete keys for
public_key body DeleteServicesSSHKeysUsernameBody DeleteServicesSSHKeysUsernameBody ✓ Key to delete

All responses

Code Status Description
200 OK SSH key deleted
401 Unauthorized Unauthorized
404 Not Found Key not found
Inlined models

DeleteServicesSSHKeysUsernameBody

Properties

Name Type Go type Required Default Description Example
public_key string string ✓

Delete a user (DeleteUsersUsername)

DELETE /users/{username}

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
username path string string ✓ User to delete

All responses

Code Status Description
200 OK Deleted user
400 Bad Request Bad request
401 Unauthorized Unauthorized
404 Not Found User not found

Get API version (GetAPIVersion)

GET /api/version

All responses

Code Status Description Schema
200 OK API version schema
401 Unauthorized Unauthorized

Responses

200 - API version

Status: OK

Schema
Name Type Go type Required Default Description Example
version string string API version
401 - Unauthorized

Status: Unauthorized

Get recovery token status (GetAuthRecoveryToken)

GET /auth/recovery_token

Security Requirements

  • bearerAuth

All responses

Code Status Description Has headers Schema
200 OK Recovery token status schema
400 Bad Request Bad request schema

Responses

200 - Recovery token status

Status: OK

Schema
Name Type Go type Required Default Description Example
date string string Recovery token date
exists boolean bool Recovery token exists
expiration string string Recovery token expiration date
uses_left integer int64 Recovery token uses left
valid boolean bool Recovery token is valid
400 - Bad request

Status: Bad Request

Get current device tokens (GetAuthTokens)

GET /auth/tokens

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK List of tokens
400 Bad Request Bad request

Get DKIM key from file (GetServicesMailserverDkim)

GET /services/mailserver/dkim

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK DKIM key encoded in base64
401 Unauthorized Unauthorized
404 Not Found DKIM key not found

Get all restic backups (GetServicesResticBackupList)

GET /services/restic/backup/list

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK A list of snapshots
400 Bad Request Bad request
401 Unauthorized Unauthorized

Force reload snapshots (GetServicesResticBackupReload)

GET /services/restic/backup/reload

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Snapshots reloaded
400 Bad Request Bad request
401 Unauthorized Unauthorized

Get backup status (GetServicesResticBackupStatus)

GET /services/restic/backup/status

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Backup status
400 Bad Request Bad request
401 Unauthorized Unauthorized

Get current SSH settings (GetServicesSSH)

GET /services/ssh

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK SSH settings
400 Bad Request Bad request

List SSH keys (GetServicesSSHKeysUsername)

GET /services/ssh/keys/{username}

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
username path string string ✓ User to list keys for

All responses

Code Status Description
200 OK SSH keys
401 Unauthorized Unauthorized

Get service status (GetServicesStatus)

GET /services/status

All responses

Code Status Description Schema
200 OK Service status schema
401 Unauthorized Unauthorized schema

Responses

200 - Service status

Status: OK

Schema
Name Type Go type Required Default Description Example
bitwarden integer int64 Bitwarden service status
gitea integer int64 Gitea service status
http integer int64 Nginx service status
imap integer int64 Dovecot service status
nextcloud integer int64 Nextcloud service status
ocserv integer int64 OpenConnect VPN service status
pleroma integer int64 Pleroma service status
smtp integer int64 Postfix service status
401 - Unauthorized

Status: Unauthorized

Rebuild NixOS with nixos-rebuild switch (GetSystemConfigurationApply)

GET /system/configuration/apply

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK System rebuild has started
401 Unauthorized Unauthorized

Get current system autoupgrade settings (GetSystemConfigurationAutoUpgrade)

GET /system/configuration/autoUpgrade

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Auto-upgrade settings
400 Bad Request Bad request

Pull Repository Changes (GetSystemConfigurationPull)

GET /system/configuration/pull

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Got update
201 Created Nothing to update
401 Unauthorized Unauthorized
500 Internal Server Error Something went wrong

Rollback NixOS with nixos-rebuild switch --rollback (GetSystemConfigurationRollback)

GET /system/configuration/rollback

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK System rollback has started
401 Unauthorized Unauthorized

Get current system timezone (GetSystemConfigurationTimezone)

GET /system/configuration/timezone

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Timezone
400 Bad Request Bad request

Upgrade NixOS with nixos-rebuild switch --upgrade (GetSystemConfigurationUpgrade)

GET /system/configuration/upgrade

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK System upgrade has started
401 Unauthorized Unauthorized

Get python version used by this API (GetSystemPythonVersion)

GET /system/pythonVersion

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK OK
401 Unauthorized Unauthorized

Reboot the system (GetSystemReboot)

GET /system/reboot

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK System reboot has started
401 Unauthorized Unauthorized

Get system version from uname -a (GetSystemVersion)

GET /system/version

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK OK
401 Unauthorized Unauthorized

Get a list of users (GetUsers)

GET /users

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK A list of users
401 Unauthorized Unauthorized

Get new device token (PostAuthNewDevice)

POST /auth/new_device

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK New device token
400 Bad Request Bad request

Authorize device (PostAuthNewDeviceAuthorize)

POST /auth/new_device/authorize

Parameters

Name Source Type Go type Separator Required Default Description
data body PostAuthNewDeviceAuthorizeBody PostAuthNewDeviceAuthorizeBody ✓ Who is authorizing

All responses

Code Status Description
200 OK Device authorized
400 Bad Request Bad request
404 Not Found Token not found
Inlined models

PostAuthNewDeviceAuthorizeBody

Properties

Name Type Go type Required Default Description Example
device string string Device to authorize
token string string Mnemonic token to authorize

Generate recovery token (PostAuthRecoveryToken)

POST /auth/recovery_token

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
data body PostAuthRecoveryTokenBody PostAuthRecoveryTokenBody ✓ Token data

All responses

Code Status Description Schema
200 OK Recovery token generated schema
400 Bad Request Bad request

Responses

200 - Recovery token generated

Status: OK

Schema
Name Type Go type Required Default Description Example
token string string Mnemonic recovery token
400 - Bad request

Status: Bad Request

Inlined models

PostAuthRecoveryTokenBody

Properties

Name Type Go type Required Default Description Example
expiration string string Token expiration date
uses integer int64 Token uses

Use recovery token (PostAuthRecoveryTokenUse)

POST /auth/recovery_token/use

Parameters

Name Source Type Go type Separator Required Default Description
data body PostAuthRecoveryTokenUseBody PostAuthRecoveryTokenUseBody ✓ Token data

All responses

Code Status Description Schema
200 OK Recovery token used schema
400 Bad Request Bad request
404 Not Found Token not found

Responses

200 - Recovery token used

Status: OK

Schema
Name Type Go type Required Default Description Example
token string string Device authorization token
Inlined models

PostAuthRecoveryTokenUseBody

Properties

Name Type Go type Required Default Description Example
device string string Device to authorize
token string string Mnemonic recovery token

Refresh token (PostAuthTokens)

POST /auth/tokens

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Token refreshed
400 Bad Request Bad request
404 Not Found Token not found

Disable Bitwarden (PostServicesBitwardenDisable)

POST /services/bitwarden/disable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Bitwarden disabled
401 Unauthorized Unauthorized

Enable Bitwarden (PostServicesBitwardenEnable)

POST /services/bitwarden/enable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Bitwarden enabled
401 Unauthorized Unauthorized

Disable Gitea (PostServicesGiteaDisable)

POST /services/gitea/disable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Gitea disabled
401 Unauthorized Unauthorized

Enable Gitea (PostServicesGiteaEnable)

POST /services/gitea/enable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Gitea enabled
401 Unauthorized Unauthorized

Disable Nextcloud (PostServicesNextcloudDisable)

POST /services/nextcloud/disable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Nextcloud disabled
401 Unauthorized Unauthorized

Enable Nextcloud (PostServicesNextcloudEnable)

POST /services/nextcloud/enable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Nextcloud enabled
401 Unauthorized Unauthorized

Disable OCserv (PostServicesOcservDisable)

POST /services/ocserv/disable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK OCserv disabled
401 Unauthorized Unauthorized

Enable OCserv (PostServicesOcservEnable)

POST /services/ocserv/enable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK OCserv enabled
401 Unauthorized Unauthorized

Disable Pleroma (PostServicesPleromaDisable)

POST /services/pleroma/disable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Pleroma disabled
401 Unauthorized Unauthorized

Enable Pleroma (PostServicesPleromaEnable)

POST /services/pleroma/enable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Pleroma enabled
401 Unauthorized Unauthorized

Enable SSH (PostServicesSSHEnable)

POST /services/ssh/enable

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK SSH enabled
401 Unauthorized Unauthorized

Add SSH key to the user (PostServicesSSHKeysUsername)

POST /services/ssh/keys/{username}

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
username path string string ✓ User to add keys for
public_key body PostServicesSSHKeysUsernameBody PostServicesSSHKeysUsernameBody ✓

All responses

Code Status Description
201 Created SSH key added
401 Unauthorized Unauthorized
404 Not Found User not found
409 Conflict Key already exists
Inlined models

PostServicesSSHKeysUsernameBody

Properties

Name Type Go type Required Default Description Example
public_key string string ✓

Create a new user (PostUsers)

POST /users

Consumes

  • application/json

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
user body PostUsersBody PostUsersBody ✓ User to create

All responses

Code Status Description
201 Created Created user
400 Bad Request Bad request
401 Unauthorized Unauthorized
409 Conflict User already exists
Inlined models

PostUsersBody

Properties

Name Type Go type Required Default Description Example
password string string ✓ Unix password.
username string string ✓ Unix username. Must be alphanumeric and less than 32 characters

Set the new key for backblaze (PutServicesResticBackblazeConfig)

PUT /services/restic/backblaze/config

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
backblazeSettings body PutServicesResticBackblazeConfigBody PutServicesResticBackblazeConfigBody ✓ New Backblaze settings

All responses

Code Status Description
200 OK New Backblaze settings
400 Bad Request Bad request
401 Unauthorized Unauthorized
Inlined models

PutServicesResticBackblazeConfigBody

Properties

Name Type Go type Required Default Description Example
accountId string string ✓
accountKey string string ✓
bucket string string ✓

Initiate a new restic backup (PutServicesResticBackupCreate)

PUT /services/restic/backup/create

Security Requirements

  • bearerAuth

All responses

Code Status Description
200 OK Backup creation has started
400 Bad Request Bad request
401 Unauthorized Unauthorized
409 Conflict Backup already in progress

Start backup restoration (PutServicesResticBackupRestore)

PUT /services/restic/backup/restore

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
backup body PutServicesResticBackupRestoreBody PutServicesResticBackupRestoreBody ✓ Backup to restore

All responses

Code Status Description
200 OK Backup restoration process started
400 Bad Request Bad request
401 Unauthorized Unauthorized
Inlined models

PutServicesResticBackupRestoreBody

Properties

Name Type Go type Required Default Description Example
backupId string string ✓

Change SSH settings (PutServicesSSH)

PUT /services/ssh

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
sshSettings body PutServicesSSHBody PutServicesSSHBody ✓ SSH settings

All responses

Code Status Description
200 OK New settings saved
400 Bad Request Bad request
Inlined models

PutServicesSSHBody

Properties

Name Type Go type Required Default Description Example
enable boolean bool ✓
passwordAuthentication boolean bool ✓

Add a SSH root key (PutServicesSSHKeySend)

PUT /services/ssh/key/send

Consumes

  • application/json

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
body body PutServicesSSHKeySendBody PutServicesSSHKeySendBody ✓ Public key to add

All responses

Code Status Description
201 Created Key added
400 Bad Request Bad request
401 Unauthorized Unauthorized
409 Conflict Key already exists
Inlined models

PutServicesSSHKeySendBody

Properties

Name Type Go type Required Default Description Example
public_key string string ✓ ssh-ed25519 public key.

Change system auto upgrade settings (PutSystemConfigurationAutoUpgrade)

PUT /system/configuration/autoUpgrade

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
autoUpgrade body PutSystemConfigurationAutoUpgradeBody PutSystemConfigurationAutoUpgradeBody ✓ Auto upgrade settings

All responses

Code Status Description
200 OK New settings saved
400 Bad Request Bad request
Inlined models

PutSystemConfigurationAutoUpgradeBody

Properties

Name Type Go type Required Default Description Example
allowReboot boolean bool ✓
enable boolean bool ✓

Change system timezone (PutSystemConfigurationTimezone)

PUT /system/configuration/timezone

Security Requirements

  • bearerAuth

Parameters

Name Source Type Go type Separator Required Default Description
timezone body PutSystemConfigurationTimezoneBody PutSystemConfigurationTimezoneBody ✓ Timezone to set

All responses

Code Status Description
200 OK Timezone changed
400 Bad Request Bad request
Inlined models

PutSystemConfigurationTimezoneBody Properties

Name Type Go type Required Default Description Example
timezone string string ✓