2020-09-06 09:40:31 +00:00
openapi : 3.0 .3
2021-03-06 16:08:24 +00:00
tags :
- name : healthcheck
- name : token
- name : maintenance
- name : admins
2021-08-17 16:08:32 +00:00
- name : API keys
2021-03-06 16:08:24 +00:00
- name : connections
2023-02-09 08:33:33 +00:00
- name : IP Lists
2021-03-06 16:08:24 +00:00
- name : defender
- name : quota
- name : folders
2022-04-25 13:49:11 +00:00
- name : groups
2022-11-16 18:04:50 +00:00
- name : roles
2021-03-06 16:08:24 +00:00
- name : users
2021-09-25 10:20:31 +00:00
- name : data retention
2021-10-20 17:39:49 +00:00
- name : events
2021-12-16 17:18:36 +00:00
- name : metadata
2021-11-06 13:13:20 +00:00
- name : user APIs
- name : public shares
2022-07-11 06:17:36 +00:00
- name : event manager
2019-07-20 10:26:52 +00:00
info :
title : SFTPGo
2021-05-20 16:16:27 +00:00
description : |
2022-04-02 16:32:46 +00:00
SFTPGo allows you to securely share your files over SFTP and optionally over HTTP/S, FTP/S and WebDAV as well.
Several storage backends are supported and they are configurable per-user, so you can serve a local directory for a user and an S3 bucket (or part of it) for another one.
2023-02-09 08:33:33 +00:00
SFTPGo also supports virtual folders, a virtual folder can use any of the supported storage backends. So you can have, for example, a user with the S3 backend mapping a Google Cloud Storage bucket (or part of it) on a specified path and an encrypted local filesystem on another one.
2021-05-20 16:16:27 +00:00
Virtual folders can be private or shared among multiple users, for shared virtual folders you can define different quota limits for each user.
2022-04-25 13:49:11 +00:00
SFTPGo supports groups to simplify the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user.
2022-03-17 13:59:02 +00:00
The SFTPGo WebClient allows end users to change their credentials, browse and manage their files in the browser and setup two-factor authentication which works with Authy, Google Authenticator and other compatible apps.
From the WebClient each authorized user can also create HTTP/S links to externally share files and folders securely, by setting limits to the number of downloads/uploads, protecting the share with a password, limiting access by source IP address, setting an automatic expiration date.
2024-05-15 19:25:42 +00:00
version : 2.6 .99 -dev
2021-03-06 16:08:24 +00:00
contact :
2021-04-28 17:16:15 +00:00
name : API support
2021-03-06 16:08:24 +00:00
url : 'https://github.com/drakkan/sftpgo'
license :
2022-07-17 18:16:00 +00:00
name : AGPL-3.0-only
2021-03-06 16:08:24 +00:00
url : 'https://www.gnu.org/licenses/agpl-3.0.en.html'
2019-07-20 10:26:52 +00:00
servers :
2021-01-17 21:29:08 +00:00
- url : /api/v2
2020-02-03 23:08:00 +00:00
security :
2021-01-17 21:29:08 +00:00
- BearerAuth : [ ]
2021-08-17 16:08:32 +00:00
- APIKeyAuth : [ ]
2019-07-20 10:26:52 +00:00
paths :
2020-11-01 09:39:10 +00:00
/healthz :
get :
2020-11-22 20:53:04 +00:00
security : [ ]
2020-11-01 09:39:10 +00:00
servers :
2021-03-06 16:08:24 +00:00
- url : /
2020-11-01 09:39:10 +00:00
tags :
- healthcheck
summary : health check
2021-03-07 17:41:56 +00:00
description : This endpoint can be used to check if the application is running and responding to requests
2021-03-06 16:08:24 +00:00
operationId : healthz
2020-11-01 09:39:10 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2020-11-01 09:39:10 +00:00
description : successful operation
content :
2022-12-19 17:38:23 +00:00
text/plain; charset=utf-8 :
2020-11-01 09:39:10 +00:00
schema :
type : string
example : ok
2021-11-06 13:13:20 +00:00
/shares/{id}:
parameters :
- name : id
in : path
description : the share id
required : true
schema :
type : string
get :
security :
- BasicAuth : [ ]
tags :
- public shares
summary : Download shared files and folders as a single zip file
description : A zip file, containing the shared files and folders, will be generated on the fly and returned as response body. Only folders and regular files will be included in the zip. The share must be defined with the read scope and the associated user must have list and download permissions
operationId : get_share
2021-11-30 19:32:10 +00:00
parameters :
- in : query
name : compress
schema :
type : boolean
default : true
required : false
2021-11-06 13:13:20 +00:00
responses :
'200' :
description : successful operation
content :
2021-11-30 19:32:10 +00:00
'*/*' :
2021-11-06 13:13:20 +00:00
schema :
type : string
format : binary
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
security :
- BasicAuth : [ ]
tags :
- public shares
summary : Upload one or more files to the shared path
2021-12-08 18:25:22 +00:00
description : The share must be defined with the write scope and the associated user must have the upload permission
2021-11-06 13:13:20 +00:00
operationId : upload_to_share
requestBody :
content :
multipart/form-data :
schema :
type : object
properties :
filenames :
type : array
items :
type : string
format : binary
minItems : 1
uniqueItems : true
required : true
responses :
'201' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-11-06 13:13:20 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
2021-11-22 11:25:36 +00:00
'413' :
$ref : '#/components/responses/RequestEntityTooLarge'
2021-11-06 13:13:20 +00:00
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2022-02-06 15:46:43 +00:00
/shares/{id}/files:
parameters :
- name : id
in : path
description : the share id
required : true
schema :
type : string
get :
security :
- BasicAuth : [ ]
tags :
- public shares
summary : Download a single file
description : Returns the file contents as response body. The share must have exactly one path defined and it must be a directory for this to work
operationId : download_share_file
parameters :
- in : query
name : path
required : true
description : Path to the file to download. It must be URL encoded, for example the path "my dir/àdir/file.txt" must be sent as "my%20dir%2F%C3%A0dir%2Ffile.txt"
schema :
type : string
- in : query
name : inline
required : false
description : 'If set, the response will not have the Content-Disposition header set to `attachment`'
schema :
type : string
responses :
'200' :
description : successful operation
content :
'*/*' :
schema :
type : string
format : binary
'206' :
description : successful operation
content :
'*/*' :
schema :
type : string
format : binary
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/shares/{id}/dirs:
parameters :
- name : id
in : path
description : the share id
required : true
schema :
type : string
get :
security :
- BasicAuth : [ ]
tags :
- public shares
summary : Read directory contents
description : Returns the contents of the specified directory for the specified share. The share must have exactly one path defined and it must be a directory for this to work
operationId : get_share_dir_contents
parameters :
- in : query
name : path
2022-03-03 11:44:56 +00:00
description : Path to the folder to read. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir". If empty or missing the user's start directory is assumed. If relative, the user's start directory is used as the base
2022-02-06 15:46:43 +00:00
schema :
type : string
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-02-06 15:46:43 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/DirEntry'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-12-08 18:25:22 +00:00
/shares/{id}/{fileName}:
parameters :
- name : id
in : path
description : the share id
required : true
schema :
type : string
- name : fileName
in : path
description : the name of the new file. It must be path encoded. Sub directories are not accepted
required : true
schema :
type : string
- name : X-SFTPGO-MTIME
in : header
schema :
type : integer
description : File modification time as unix timestamp in milliseconds
post :
security :
- BasicAuth : [ ]
tags :
- public shares
summary : Upload a single file to the shared path
description : The share must be defined with the write scope and the associated user must have the upload/overwrite permissions
operationId : upload_single_to_share
requestBody :
content :
application/* :
schema :
type : string
format : binary
text/* :
schema :
type : string
format : binary
image/* :
schema :
type : string
format : binary
audio/* :
schema :
type : string
format : binary
video/* :
schema :
type : string
format : binary
required : true
responses :
'201' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-12-08 18:25:22 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-12-08 18:25:22 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'413' :
$ref : '#/components/responses/RequestEntityTooLarge'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-01-17 21:29:08 +00:00
/token :
get :
security :
- BasicAuth : [ ]
tags :
- token
2021-06-05 14:07:09 +00:00
summary : Get a new admin access token
2021-03-06 16:08:24 +00:00
description : Returns an access token and its expiration
2021-01-17 21:29:08 +00:00
operationId : get_token
2021-09-04 10:11:04 +00:00
parameters :
- in : header
name : X-SFTPGO-OTP
schema :
type : string
required : false
description : 'If you have 2FA configured for the admin attempting to log in you need to set the authentication code using this header parameter'
2021-01-17 21:29:08 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-17 21:29:08 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Token'
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-01-26 21:35:36 +00:00
/logout :
get :
2021-08-17 16:08:32 +00:00
security :
- BearerAuth : [ ]
2021-01-26 21:35:36 +00:00
tags :
- token
2021-06-05 14:07:09 +00:00
summary : Invalidate an admin access token
description : Allows to invalidate an admin token before its expiration
2021-01-26 21:35:36 +00:00
operationId : logout
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-26 21:35:36 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-26 21:35:36 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
'401' :
2021-01-26 21:35:36 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-26 21:35:36 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-26 21:35:36 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-05 14:07:09 +00:00
/user/token :
get :
security :
- BasicAuth : [ ]
tags :
- token
summary : Get a new user access token
description : Returns an access token and its expiration
operationId : get_user_token
2021-09-04 10:11:04 +00:00
parameters :
- in : header
name : X-SFTPGO-OTP
schema :
type : string
required : false
description : 'If you have 2FA configured, for the HTTP protocol, for the user attempting to log in you need to set the authentication code using this header parameter'
2021-06-05 14:07:09 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-05 14:07:09 +00:00
schema :
$ref : '#/components/schemas/Token'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/logout :
get :
2021-08-17 16:08:32 +00:00
security :
- BearerAuth : [ ]
2021-06-05 14:07:09 +00:00
tags :
- token
summary : Invalidate a user access token
description : Allows to invalidate a client token before its expiration
operationId : client_logout
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-05 14:07:09 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-08-08 08:01:33 +00:00
/version :
get :
tags :
2020-12-08 10:18:34 +00:00
- maintenance
2019-08-08 08:01:33 +00:00
summary : Get version details
2021-03-07 17:41:56 +00:00
description : 'Returns version details such as the version number, build date, commit hash and enabled features'
2019-08-08 08:01:33 +00:00
operationId : get_version
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-08-08 08:01:33 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-08-08 08:01:33 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/VersionInfo'
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-05 14:07:09 +00:00
/admin/changepwd :
2021-01-17 21:29:08 +00:00
put :
2021-08-17 16:08:32 +00:00
security :
- BearerAuth : [ ]
2021-01-17 21:29:08 +00:00
tags :
- admins
2021-03-06 16:08:24 +00:00
summary : Change admin password
2021-03-07 17:41:56 +00:00
description : Changes the password for the logged in admin
2021-01-17 21:29:08 +00:00
operationId : change_admin_password
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
$ref : '#/components/schemas/PwdChange'
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-17 21:29:08 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-29 16:46:15 +00:00
/admin/profile :
2021-09-06 16:46:35 +00:00
get :
security :
- BearerAuth : [ ]
tags :
- admins
2021-09-30 08:23:25 +00:00
summary : Get admin profile
2021-09-29 16:46:15 +00:00
description : 'Returns the profile for the logged in admin'
operationId : get_admin_profile
2021-09-06 16:46:35 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-06 16:46:35 +00:00
schema :
2021-09-29 16:46:15 +00:00
$ref : '#/components/schemas/AdminProfile'
2021-09-06 16:46:35 +00:00
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
security :
- BearerAuth : [ ]
tags :
- admins
2021-09-29 16:46:15 +00:00
summary : Update admin profile
description : 'Allows to update the profile for the logged in admin'
operationId : update_admin_profile
2021-09-06 16:46:35 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-06 16:46:35 +00:00
schema :
2021-09-29 16:46:15 +00:00
$ref : '#/components/schemas/AdminProfile'
2021-09-06 16:46:35 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-06 16:46:35 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-04 10:11:04 +00:00
/admin/2fa/recoverycodes :
get :
security :
- BearerAuth : [ ]
tags :
- admins
summary : Get recovery codes
description : 'Returns the recovery codes for the logged in admin. Recovery codes can be used if the admin loses access to their second factor auth device. Recovery codes are returned unencrypted'
operationId : get_admin_recovery_codes
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/RecoveryCode'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
security :
- BearerAuth : [ ]
tags :
- admins
summary : Generate recovery codes
description : 'Generates new recovery codes for the logged in admin. Generating new recovery codes you automatically invalidate old ones'
operationId : generate_admin_recovery_codes
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : array
items :
type : string
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/admin/totp/configs :
get :
security :
- BearerAuth : [ ]
tags :
- admins
summary : Get available TOTP configuration
description : Returns the available TOTP configurations for the logged in admin
operationId : get_admin_totp_configs
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/TOTPConfig'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/admin/totp/generate :
post :
security :
- BearerAuth : [ ]
tags :
- admins
summary : Generate a new TOTP secret
description : 'Generates a new TOTP secret, including the QR code as png, using the specified configuration for the logged in admin'
operationId : generate_admin_totp_secret
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : object
properties :
config_name :
type : string
description : 'name of the configuration to use to generate the secret'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : object
properties :
config_name :
type : string
issuer :
type : string
secret :
type : string
2023-11-18 19:06:31 +00:00
url :
type : string
2021-09-04 10:11:04 +00:00
qr_code :
type : string
format : byte
description : 'QR code png encoded as BASE64'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/admin/totp/validate :
post :
security :
- BearerAuth : [ ]
tags :
- admins
summary : Validate a one time authentication code
description : 'Checks if the given authentication code can be validated using the specified secret and config name'
operationId : validate_admin_totp_secret
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : object
properties :
config_name :
type : string
description : 'name of the configuration to use to validate the passcode'
passcode :
type : string
description : 'passcode to validate'
secret :
type : string
description : 'secret to use to validate the passcode'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Passcode successfully validated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/admin/totp/save :
post :
security :
- BearerAuth : [ ]
tags :
- admins
summary : Save a TOTP config
description : 'Saves the specified TOTP config for the logged in admin'
operationId : save_admin_totp_config
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/AdminTOTPConfig'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : TOTP configuration saved
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-01-17 21:29:08 +00:00
/connections :
2019-07-20 10:26:52 +00:00
get :
tags :
2020-11-01 09:39:10 +00:00
- connections
2021-03-06 16:08:24 +00:00
summary : Get connections details
2021-03-07 17:41:56 +00:00
description : Returns the active users and info about their current uploads/downloads
2019-08-24 12:41:15 +00:00
operationId : get_connections
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-07-20 10:26:52 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
type : array
items :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ConnectionStatus'
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-03-06 16:08:24 +00:00
'/connections/{connectionID}' :
2019-07-20 10:26:52 +00:00
delete :
tags :
2020-11-01 09:39:10 +00:00
- connections
2021-03-06 16:08:24 +00:00
summary : Close connection
2021-03-07 17:41:56 +00:00
description : Terminates an active connection
2019-08-24 12:41:15 +00:00
operationId : close_connection
2019-11-13 10:36:21 +00:00
parameters :
2020-11-01 09:39:10 +00:00
- name : connectionID
in : path
description : ID of the connection to close
required : true
schema :
type : string
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-07-20 10:26:52 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2021-03-06 16:08:24 +00:00
message : Connection closed
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2023-02-09 08:33:33 +00:00
/iplists/{type}:
parameters :
- name : type
in : path
description : IP list type
required : true
schema :
$ref : '#/components/schemas/IPListType'
get :
tags :
- IP Lists
summary : Get IP list entries
description : Returns an array with one or more IP list entry
operationId : get_ip_list_entries
parameters :
- in : query
name : filter
schema :
type : string
description : restrict results to ipornet matching or starting with this filter
- in : query
name : from
schema :
type : string
description : ipornet to start from
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering entries by ipornet field. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/IPListEntry'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- IP Lists
summary : Add a new IP list entry
description : Add an IP address or a CIDR network to a supported list
operationId : add_ip_list_entry
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
$ref : '#/components/schemas/IPListEntry'
responses :
'201' :
description : successful operation
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Entry added
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/iplists/{type}/{ipornet}:
parameters :
- name : type
in : path
description : IP list type
required : true
schema :
$ref : '#/components/schemas/IPListType'
- name : ipornet
in : path
required : true
schema :
type : string
get :
tags :
- IP Lists
summary : Find entry by ipornet
description : Returns the entry with the given ipornet if it exists.
operationId : get_ip_list_by_ipornet
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
$ref : '#/components/schemas/IPListEntry'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- IP Lists
summary : Update IP list entry
description : Updates an existing IP list entry
operationId : update_ip_list_entry
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
$ref : '#/components/schemas/IPListEntry'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Entry updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- IP Lists
summary : Delete IP list entry
description : Deletes an existing IP list entry
operationId : delete_ip_list_entry
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-02-09 08:33:33 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Entry deleted
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-07 19:52:43 +00:00
/defender/hosts :
get :
tags :
- defender
summary : Get hosts
description : Returns hosts that are banned or for which some violations have been detected
operationId : get_defender_hosts
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/DefenderEntry'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/defender/hosts/{id}:
parameters :
- name : id
in : path
description : host id
required : true
schema :
type : string
get :
tags :
- defender
summary : Get host by id
description : Returns the host with the given id, if it exists
operationId : get_defender_host_by_id
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/DefenderEntry'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- defender
summary : Removes a host from the defender lists
description : Unbans the specified host or clears its violations
operationId : delete_defender_host_by_id
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-25 10:20:31 +00:00
/retention/users/checks :
get :
tags :
- data retention
summary : Get retention checks
description : Returns the active retention checks
operationId : get_users_retention_checks
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-25 10:20:31 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/RetentionCheck'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/retention/users/{username}/check:
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
2021-10-03 13:17:49 +00:00
- name : notifications
2021-10-02 20:25:41 +00:00
in : query
2021-10-03 13:17:49 +00:00
description : 'specify how to notify results'
explode : false
2021-10-02 20:25:41 +00:00
schema :
2021-10-03 13:17:49 +00:00
type : array
items :
$ref : '#/components/schemas/RetentionCheckNotification'
2021-09-25 10:20:31 +00:00
post :
tags :
- data retention
summary : Start a retention check
description : 'Starts a new retention check for the given user. If a retention check for this user is already active a 409 status code is returned'
operationId : start_user_retention_check
requestBody :
required : true
description : 'Defines virtual paths to check and their retention time in hours'
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-25 10:20:31 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/FolderRetention'
responses :
'202' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-25 10:20:31 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Check started
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'409' :
$ref : '#/components/responses/Conflict'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-07 19:52:43 +00:00
/quotas/users/scans :
get :
tags :
- quota
summary : Get active user quota scans
description : Returns the active user quota scans
operationId : get_users_quota_scans
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/QuotaScan'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/quotas/users/{username}/scan:
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
post :
tags :
- quota
summary : Start a user quota scan
description : Starts a new quota scan for the given user. A quota scan updates the number of files and their total size for the specified user and the virtual folders, if any, included in his quota
operationId : start_user_quota_scan
responses :
'202' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Scan started
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'409' :
$ref : '#/components/responses/Conflict'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/quotas/users/{username}/usage:
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
- in : query
name : mode
required : false
description : the update mode specifies if the given quota usage values should be added or replace the current ones
schema :
type : string
enum :
- add
- reset
description : |
Update type :
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example : reset
put :
tags :
- quota
2022-01-30 10:42:36 +00:00
summary : Update disk quota usage limits
2021-06-07 19:52:43 +00:00
description : Sets the current used quota limits for the given user
operationId : user_quota_update_usage
requestBody :
required : true
description : 'If used_quota_size and used_quota_files are missing they will default to 0, this means that if mode is "add" the current value, for the missing field, will remain unchanged, if mode is "reset" the missing field is set to 0'
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/QuotaUsage'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Quota updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'409' :
$ref : '#/components/responses/Conflict'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2022-01-30 10:42:36 +00:00
/quotas/users/{username}/transfer-usage:
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
- in : query
name : mode
required : false
description : the update mode specifies if the given quota usage values should be added or replace the current ones
schema :
type : string
enum :
- add
- reset
description : |
Update type :
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example : reset
put :
tags :
- quota
summary : Update transfer quota usage limits
description : Sets the current used transfer quota limits for the given user
operationId : user_transfer_quota_update_usage
requestBody :
required : true
description : 'If used_upload_data_transfer and used_download_data_transfer are missing they will default to 0, this means that if mode is "add" the current value, for the missing field, will remain unchanged, if mode is "reset" the missing field is set to 0'
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-01-30 10:42:36 +00:00
schema :
$ref : '#/components/schemas/TransferQuotaUsage'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-01-30 10:42:36 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Quota updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'409' :
$ref : '#/components/responses/Conflict'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-07 19:52:43 +00:00
/quotas/folders/scans :
get :
tags :
- quota
summary : Get active folder quota scans
description : Returns the active folder quota scans
operationId : get_folders_quota_scans
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/FolderQuotaScan'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/quotas/folders/{name}/scan:
parameters :
- name : name
in : path
description : folder name
required : true
schema :
type : string
post :
tags :
- quota
summary : Start a folder quota scan
description : Starts a new quota scan for the given folder. A quota scan update the number of files and their total size for the specified folder
operationId : start_folder_quota_scan
responses :
'202' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Scan started
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'409' :
$ref : '#/components/responses/Conflict'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/quotas/folders/{name}/usage:
parameters :
- name : name
in : path
description : folder name
required : true
schema :
type : string
- in : query
name : mode
required : false
description : the update mode specifies if the given quota usage values should be added or replace the current ones
schema :
type : string
enum :
- add
- reset
description : |
Update type :
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example : reset
put :
tags :
- quota
summary : Update folder quota usage limits
description : Sets the current used quota limits for the given folder
operationId : folder_quota_update_usage
parameters :
- in : query
name : mode
required : false
description : the update mode specifies if the given quota usage values should be added or replace the current ones
schema :
type : string
enum :
- add
- reset
description : |
Update type :
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example : reset
requestBody :
required : true
description : 'If used_quota_size and used_quota_files are missing they will default to 0, this means that if mode is "add" the current value, for the missing field, will remain unchanged, if mode is "reset" the missing field is set to 0'
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/QuotaUsage'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-07 19:52:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Quota updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'409' :
$ref : '#/components/responses/Conflict'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-01-17 21:29:08 +00:00
/folders :
2020-06-07 21:30:18 +00:00
get :
tags :
2020-11-01 09:39:10 +00:00
- folders
2021-03-06 16:08:24 +00:00
summary : Get folders
description : Returns an array with one or more folders
2020-06-07 21:30:18 +00:00
operationId : get_folders
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
2021-03-06 16:08:24 +00:00
description : 'The maximum number of items to return. Max value is 500, default is 100'
2020-06-07 21:30:18 +00:00
- in : query
name : order
required : false
2022-04-25 13:49:11 +00:00
description : Ordering folders by name. Default ASC
2020-06-07 21:30:18 +00:00
schema :
2021-03-06 16:08:24 +00:00
type : string
enum :
- ASC
- DESC
example : ASC
2020-06-07 21:30:18 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2020-06-07 21:30:18 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-06-07 21:30:18 +00:00
schema :
type : array
items :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/BaseVirtualFolder'
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2020-06-07 21:30:18 +00:00
post :
tags :
2020-11-01 09:39:10 +00:00
- folders
2021-03-07 17:41:56 +00:00
summary : Add folder
2020-06-07 21:30:18 +00:00
operationId : add_folder
2021-03-07 17:41:56 +00:00
description : Adds a new folder. A quota scan is required to update the used files/size
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2020-06-07 21:30:18 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-06-07 21:30:18 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/BaseVirtualFolder'
2020-06-07 21:30:18 +00:00
responses :
2021-03-06 16:08:24 +00:00
'201' :
2020-06-07 21:30:18 +00:00
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2020-06-07 21:30:18 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-06-07 21:30:18 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/BaseVirtualFolder'
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-03-06 16:08:24 +00:00
'/folders/{name}' :
2021-02-01 18:04:15 +00:00
parameters :
- name : name
in : path
description : folder name
required : true
schema :
type : string
get :
tags :
- folders
2021-03-07 17:41:56 +00:00
summary : Find folders by name
description : Returns the folder with the given name if it exists.
2021-02-01 18:04:15 +00:00
operationId : get_folder_by_name
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2021-02-01 18:04:15 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-02-01 18:04:15 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-02-01 18:04:15 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/BaseVirtualFolder'
'400' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- folders
2021-03-06 16:08:24 +00:00
summary : Update folder
2021-03-07 17:41:56 +00:00
description : Updates an existing folder
2021-02-01 18:04:15 +00:00
operationId : update_folder
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-02-01 18:04:15 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/BaseVirtualFolder'
2021-02-01 18:04:15 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-02-01 18:04:15 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-02-01 18:04:15 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-02-01 18:04:15 +00:00
example :
2022-07-11 06:17:36 +00:00
message : Folder updated
2021-03-06 16:08:24 +00:00
'400' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2021-02-01 18:04:15 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2020-06-07 21:30:18 +00:00
delete :
tags :
2020-11-01 09:39:10 +00:00
- folders
2021-03-06 16:08:24 +00:00
summary : Delete folder
2021-03-07 17:41:56 +00:00
description : Deletes an existing folder
2020-06-07 21:30:18 +00:00
operationId : delete_folder
responses :
2021-03-06 16:08:24 +00:00
'200' :
2020-06-07 21:30:18 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-06-07 21:30:18 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2020-06-07 21:30:18 +00:00
example :
2021-03-06 16:08:24 +00:00
message : User deleted
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2022-04-25 13:49:11 +00:00
/groups :
get :
tags :
- groups
summary : Get groups
description : Returns an array with one or more groups
operationId : get_groups
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering groups by name. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/Group'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- groups
summary : Add group
operationId : add_group
description : Adds a new group
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2022-04-25 13:49:11 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
$ref : '#/components/schemas/Group'
responses :
'201' :
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2022-04-25 13:49:11 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
$ref : '#/components/schemas/Group'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/groups/{name}' :
parameters :
- name : name
in : path
description : group name
required : true
schema :
type : string
get :
tags :
- groups
summary : Find groups by name
description : Returns the group with the given name if it exists.
operationId : get_group_by_name
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2022-04-25 13:49:11 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
$ref : '#/components/schemas/Group'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- groups
summary : Update group
description : Updates an existing group
operationId : update_group
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
$ref : '#/components/schemas/Group'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
2022-07-11 06:17:36 +00:00
message : Group updated
2022-04-25 13:49:11 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- groups
2022-07-11 06:17:36 +00:00
summary : Delete group
2022-04-25 13:49:11 +00:00
description : Deletes an existing group
operationId : delete_group
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-04-25 13:49:11 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
2022-07-11 06:17:36 +00:00
message : Group deleted
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2022-11-16 18:04:50 +00:00
/roles :
get :
tags :
- roles
summary : Get roles
description : Returns an array with one or more roles
operationId : get_roles
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering groups by name. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/Role'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- roles
summary : Add role
operationId : add_role
description : Adds a new role
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
$ref : '#/components/schemas/Role'
responses :
'201' :
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2022-11-16 18:04:50 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
$ref : '#/components/schemas/Role'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/roles/{name}' :
parameters :
- name : name
in : path
description : role name
required : true
schema :
type : string
get :
tags :
- roles
summary : Find roles by name
description : Returns the role with the given name if it exists.
operationId : get_role_by_name
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
$ref : '#/components/schemas/Role'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- roles
summary : Update role
description : Updates an existing role
operationId : update_role
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
$ref : '#/components/schemas/Role'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Group updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- roles
summary : Delete role
description : Deletes an existing role
operationId : delete_role
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-11-16 18:04:50 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Group deleted
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2022-07-11 06:17:36 +00:00
/eventactions :
get :
tags :
- event manager
summary : Get event actions
description : Returns an array with one or more event actions
operationId : get_event_actons
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering actions by name. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/BaseEventAction'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- event manager
summary : Add event action
operationId : add_event_action
description : Adds a new event actions
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2022-07-11 06:17:36 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/BaseEventAction'
responses :
'201' :
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2022-07-11 06:17:36 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/BaseEventAction'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/eventactions/{name}' :
parameters :
- name : name
in : path
description : action name
required : true
schema :
type : string
get :
tags :
- event manager
summary : Find event actions by name
description : Returns the event action with the given name if it exists.
operationId : get_event_action_by_name
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2022-07-11 06:17:36 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/BaseEventAction'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- event manager
summary : Update event action
description : Updates an existing event action
operationId : update_event_action
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/BaseEventAction'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Event action updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- event manager
summary : Delete event action
description : Deletes an existing event action
operationId : delete_event_action
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Event action deleted
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/eventrules :
get :
tags :
- event manager
summary : Get event rules
description : Returns an array with one or more event rules
operationId : get_event_rules
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering rules by name. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/EventRule'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- event manager
summary : Add event rule
operationId : add_event_rule
description : Adds a new event rule
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2022-07-11 06:17:36 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/EventRuleMinimal'
responses :
'201' :
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2022-07-11 06:17:36 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/EventRule'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/eventrules/{name}' :
parameters :
- name : name
in : path
description : rule name
required : true
schema :
type : string
get :
tags :
- event manager
summary : Find event rules by name
description : Returns the event rule with the given name if it exists.
operationId : get_event_rile_by_name
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2022-07-11 06:17:36 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/EventRule'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- event manager
summary : Update event rule
description : Updates an existing event rule
operationId : update_event_rule
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/EventRuleMinimal'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Event rules updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- event manager
summary : Delete event rule
description : Deletes an existing event rule
operationId : delete_event_rule
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-07-11 06:17:36 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Event rules deleted
2022-04-25 13:49:11 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2023-01-21 14:41:24 +00:00
'/eventrules/run/{name}' :
parameters :
- name : name
in : path
description : on -demand rule name
required : true
schema :
type : string
post :
tags :
- event manager
summary : Run an on-demand event rule
description : The rule's actions will run in background. SFTPGo will not monitor any concurrency and such. If you want to be notified at the end of the execution please add an appropriate action
operationId : run_event_rule
responses :
'202' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-01-21 14:41:24 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Event rule started
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-10-20 17:39:49 +00:00
/events/fs :
get :
tags :
- events
summary : Get filesystem events
description : 'Returns an array with one or more filesystem events applying the specified filters. This API is only available if you configure an "eventsearcher" plugin'
operationId : get_fs_events
parameters :
- in : query
name : start_timestamp
schema :
type : integer
format : int64
minimum : 0
default : 0
required : false
description : 'the event timestamp, unix timestamp in nanoseconds, must be greater than or equal to the specified one. 0 or missing means omit this filter'
- in : query
name : end_timestamp
schema :
type : integer
format : int64
minimum : 0
default : 0
required : false
description : 'the event timestamp, unix timestamp in nanoseconds, must be less than or equal to the specified one. 0 or missing means omit this filter'
- in : query
name : actions
schema :
type : array
items :
$ref : '#/components/schemas/FsEventAction'
description : 'the event action must be included among those specified. Empty or missing means omit this filter. Actions must be specified comma separated'
explode : false
required : false
- in : query
name : username
schema :
type : string
description : 'the event username must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : ip
schema :
type : string
description : 'the event IP must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : ssh_cmd
schema :
type : string
description : 'the event SSH command must be the same as the one specified. Empty or missing means omit this filter'
required : false
2022-01-03 16:02:52 +00:00
- in : query
name : fs_provider
schema :
2022-01-16 08:50:23 +00:00
$ref : '#/components/schemas/FsProviders'
2022-01-03 16:02:52 +00:00
description : 'the event filesystem provider must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : bucket
schema :
type : string
description : 'the bucket must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : endpoint
schema :
type : string
description : 'the endpoint must be the same as the one specified. Empty or missing means omit this filter'
required : false
2021-10-20 17:39:49 +00:00
- in : query
name : protocols
schema :
type : array
items :
$ref : '#/components/schemas/EventProtocols'
description : 'the event protocol must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
name : statuses
schema :
type : array
items :
$ref : '#/components/schemas/FsEventStatus'
description : 'the event status must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
name : instance_ids
schema :
type : array
items :
type : string
description : 'the event instance id must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
2023-05-12 16:34:59 +00:00
name : from_id
2021-10-20 17:39:49 +00:00
schema :
2023-05-12 16:34:59 +00:00
type : string
description : 'the event id to start from. This is useful for cursor based pagination. Empty or missing means omit this filter.'
2021-10-20 17:39:49 +00:00
required : false
2022-12-03 10:45:27 +00:00
- in : query
name : role
schema :
type : string
description : 'User role. Empty or missing means omit this filter. Ignored if the admin has a role'
required : false
2022-12-07 17:47:38 +00:00
- in : query
name : csv_export
schema :
type : boolean
default : false
required : false
description : 'If enabled, events are exported as a CSV file'
2021-10-20 17:39:49 +00:00
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 1000
default : 100
required : false
2022-12-07 17:47:38 +00:00
description : 'The maximum number of items to return. Max value is 1000, default is 100'
2021-10-20 17:39:49 +00:00
- in : query
name : order
required : false
description : Ordering events by timestamp. Default DESC
schema :
type : string
enum :
- ASC
- DESC
example : DESC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-10-20 17:39:49 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/FsEvent'
2022-12-07 17:47:38 +00:00
text/csv :
schema :
type : string
2021-10-20 17:39:49 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/events/provider :
get :
tags :
- events
summary : Get provider events
description : 'Returns an array with one or more provider events applying the specified filters. This API is only available if you configure an "eventsearcher" plugin'
operationId : get_provider_events
parameters :
- in : query
name : start_timestamp
schema :
type : integer
format : int64
minimum : 0
default : 0
required : false
description : 'the event timestamp, unix timestamp in nanoseconds, must be greater than or equal to the specified one. 0 or missing means omit this filter'
- in : query
name : end_timestamp
schema :
type : integer
format : int64
minimum : 0
default : 0
required : false
description : 'the event timestamp, unix timestamp in nanoseconds, must be less than or equal to the specified one. 0 or missing means omit this filter'
- in : query
name : actions
schema :
type : array
items :
$ref : '#/components/schemas/ProviderEventAction'
description : 'the event action must be included among those specified. Empty or missing means omit this filter. Actions must be specified comma separated'
explode : false
required : false
- in : query
name : username
schema :
type : string
description : 'the event username must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : ip
schema :
type : string
description : 'the event IP must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : object_name
schema :
type : string
description : 'the event object name must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : object_types
schema :
type : array
items :
$ref : '#/components/schemas/ProviderEventObjectType'
description : 'the event object type must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
name : instance_ids
schema :
type : array
items :
type : string
description : 'the event instance id must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
2023-05-12 16:34:59 +00:00
name : from_id
2021-10-20 17:39:49 +00:00
schema :
2023-05-12 16:34:59 +00:00
type : string
description : 'the event id to start from. This is useful for cursor based pagination. Empty or missing means omit this filter.'
2021-10-20 17:39:49 +00:00
required : false
2022-12-03 10:45:27 +00:00
- in : query
name : role
schema :
type : string
description : 'Admin role. Empty or missing means omit this filter. Ignored if the admin has a role'
required : false
2022-12-07 17:47:38 +00:00
- in : query
name : csv_export
schema :
type : boolean
default : false
required : false
description : 'If enabled, events are exported as a CSV file'
2022-12-08 09:02:12 +00:00
- in : query
name : omit_object_data
schema :
type : boolean
default : false
required : false
description : 'If enabled, returned events will not contain the `object_data` field'
2021-10-20 17:39:49 +00:00
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 1000
default : 100
required : false
2022-12-07 17:47:38 +00:00
description : 'The maximum number of items to return. Max value is 1000, default is 100'
2021-10-20 17:39:49 +00:00
- in : query
name : order
required : false
description : Ordering events by timestamp. Default DESC
schema :
type : string
enum :
- ASC
- DESC
example : DESC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-10-20 17:39:49 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/ProviderEvent'
2022-12-07 17:47:38 +00:00
text/csv :
schema :
type : string
2021-10-20 17:39:49 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2023-05-12 16:34:59 +00:00
/events/log :
get :
tags :
- events
summary : Get log events
description : 'Returns an array with one or more log events applying the specified filters. This API is only available if you configure an "eventsearcher" plugin'
operationId : get_log_events
parameters :
- in : query
name : start_timestamp
schema :
type : integer
format : int64
minimum : 0
default : 0
required : false
description : 'the event timestamp, unix timestamp in nanoseconds, must be greater than or equal to the specified one. 0 or missing means omit this filter'
- in : query
name : end_timestamp
schema :
type : integer
format : int64
minimum : 0
default : 0
required : false
description : 'the event timestamp, unix timestamp in nanoseconds, must be less than or equal to the specified one. 0 or missing means omit this filter'
- in : query
name : events
schema :
type : array
items :
$ref : '#/components/schemas/LogEventType'
description : 'the log events must be included among those specified. Empty or missing means omit this filter. Events must be specified comma separated'
explode : false
required : false
- in : query
name : username
schema :
type : string
description : 'the event username must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : ip
schema :
type : string
description : 'the event IP must be the same as the one specified. Empty or missing means omit this filter'
required : false
- in : query
name : protocols
schema :
type : array
items :
$ref : '#/components/schemas/EventProtocols'
description : 'the event protocol must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
name : instance_ids
schema :
type : array
items :
type : string
description : 'the event instance id must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode : false
required : false
- in : query
name : from_id
schema :
type : string
description : 'the event id to start from. This is useful for cursor based pagination. Empty or missing means omit this filter.'
required : false
- in : query
name : role
schema :
type : string
description : 'User role. Empty or missing means omit this filter. Ignored if the admin has a role'
required : false
- in : query
name : csv_export
schema :
type : boolean
default : false
required : false
description : 'If enabled, events are exported as a CSV file'
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 1000
default : 100
required : false
description : 'The maximum number of items to return. Max value is 1000, default is 100'
- in : query
name : order
required : false
description : Ordering events by timestamp. Default DESC
schema :
type : string
enum :
- ASC
- DESC
example : DESC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2023-05-12 16:34:59 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/LogEvent'
text/csv :
schema :
type : string
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-08-17 16:08:32 +00:00
/apikeys :
get :
security :
- BearerAuth : [ ]
tags :
- API keys
summary : Get API keys
description : Returns an array with one or more API keys. For security reasons hashed keys are omitted in the response
operationId : get_api_keys
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering API keys by id. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/APIKey'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
security :
- BearerAuth : [ ]
tags :
- API keys
summary : Add API key
description : Adds a new API key
operationId : add_api_key
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
$ref : '#/components/schemas/APIKey'
responses :
'201' :
description : successful operation
headers :
X-Object-ID :
schema :
type : string
description : ID for the new created API key
Location :
schema :
type : string
2022-12-23 12:08:04 +00:00
description : URI to retrieve the details for the new created API key
2021-08-17 16:08:32 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
type : object
properties :
mesage :
type : string
example : 'API key created. This is the only time the API key is visible, please save it.'
key :
type : string
description : 'generated API key'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/apikeys/{id}' :
parameters :
- name : id
in : path
description : the key id
required : true
schema :
type : string
get :
security :
- BearerAuth : [ ]
tags :
- API keys
summary : Find API key by id
description : Returns the API key with the given id, if it exists. For security reasons the hashed key is omitted in the response
operationId : get_api_key_by_id
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
$ref : '#/components/schemas/APIKey'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
security :
- BearerAuth : [ ]
tags :
- API keys
summary : Update API key
description : Updates an existing API key. You cannot update the key itself, the creation date and the last use
operationId : update_api_key
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
$ref : '#/components/schemas/APIKey'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : API key updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
security :
- BearerAuth : [ ]
tags :
- API keys
summary : Delete API key
description : Deletes an existing API key
operationId : delete_api_key
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-08-17 16:08:32 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Admin deleted
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-01-17 21:29:08 +00:00
/admins :
2019-07-20 10:26:52 +00:00
get :
tags :
2021-01-17 21:29:08 +00:00
- admins
2021-03-07 17:41:56 +00:00
summary : Get admins
description : Returns an array with one or more admins. For security reasons hashed passwords are omitted in the response
2021-01-17 21:29:08 +00:00
operationId : get_admins
2019-07-20 10:26:52 +00:00
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
2021-03-06 16:08:24 +00:00
description : 'The maximum number of items to return. Max value is 500, default is 100'
2019-07-20 10:26:52 +00:00
- in : query
name : order
required : false
2021-01-17 21:29:08 +00:00
description : Ordering admins by username. Default ASC
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
type : string
enum :
- ASC
- DESC
example : ASC
2021-01-17 21:29:08 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-17 21:29:08 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
type : array
items :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Admin'
'400' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- admins
2021-03-06 16:08:24 +00:00
summary : Add admin
2021-09-04 10:11:04 +00:00
description: 'Adds a new admin. Recovery codes and TOTP configuration cannot be set using this API : each admin must use the specific APIs'
2021-01-17 21:29:08 +00:00
operationId : add_admin
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Admin'
2021-01-17 21:29:08 +00:00
responses :
2021-03-06 16:08:24 +00:00
'201' :
2021-01-17 21:29:08 +00:00
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2021-01-17 21:29:08 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Admin'
'400' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-03-06 16:08:24 +00:00
'/admins/{username}' :
2021-02-01 18:04:15 +00:00
parameters :
- name : username
in : path
description : the admin username
required : true
schema :
type : string
2021-01-17 21:29:08 +00:00
get :
tags :
- admins
2021-03-07 17:41:56 +00:00
summary : Find admins by username
2021-09-04 10:11:04 +00:00
description : 'Returns the admin with the given username, if it exists. For security reasons the hashed password is omitted in the response'
2021-01-17 21:29:08 +00:00
operationId : get_admin_by_username
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-17 21:29:08 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Admin'
'400' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- admins
2021-03-06 16:08:24 +00:00
summary : Update admin
2021-09-04 10:11:04 +00:00
description: 'Updates an existing admin. Recovery codes and TOTP configuration cannot be set/updated using this API : each admin must use the specific APIs. You are not allowed to update the admin impersonated using an API key'
2021-01-17 21:29:08 +00:00
operationId : update_admin
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Admin'
2021-01-17 21:29:08 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-17 21:29:08 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-01-17 21:29:08 +00:00
example :
2021-03-06 16:08:24 +00:00
message : Admin updated
'400' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- admins
2021-03-06 16:08:24 +00:00
summary : Delete admin
2021-03-07 17:41:56 +00:00
description : Deletes an existing admin
2021-01-17 21:29:08 +00:00
operationId : delete_admin
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-17 21:29:08 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-17 21:29:08 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-01-17 21:29:08 +00:00
example :
2021-03-06 16:08:24 +00:00
message : Admin deleted
'400' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-17 21:29:08 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-04 10:11:04 +00:00
'/admins/{username}/2fa/disable' :
parameters :
- name : username
in : path
description : the admin username
required : true
schema :
type : string
put :
tags :
- admins
summary : Disable second factor authentication
description : 'Disables second factor authentication for the given admin. This API must be used if the admin loses access to their second factor auth device and has no recovery codes'
operationId : disable_admin_2fa
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : 2FA disabled
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-11-13 12:25:43 +00:00
'/admins/{username}/forgot-password' :
parameters :
- name : username
in : path
description : the admin username
required : true
schema :
type : string
post :
security : [ ]
tags :
- admins
summary : Send a password reset code by email
description : 'You must set up an SMTP server and the account must have a valid email address, in which case SFTPGo will send a code via email to reset the password. If the specified admin does not exist, the request will be silently ignored (a success response will be returned) to avoid disclosing existing admins'
operationId : admin_forgot_password
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-13 12:25:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/admins/{username}/reset-password' :
parameters :
- name : username
in : path
description : the admin username
required : true
schema :
type : string
post :
security : [ ]
tags :
- admins
summary : Reset the password
description : 'Set a new password using the code received via email'
operationId : admin_reset_password
requestBody :
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-13 12:25:43 +00:00
schema :
type : object
properties :
code :
type : string
password :
type : string
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-13 12:25:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-01-17 21:29:08 +00:00
/users :
get :
tags :
- users
2021-03-07 17:41:56 +00:00
summary : Get users
description : Returns an array with one or more users. For security reasons hashed passwords are omitted in the response
2021-01-17 21:29:08 +00:00
operationId : get_users
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
2021-03-06 16:08:24 +00:00
description : 'The maximum number of items to return. Max value is 500, default is 100'
2019-07-20 10:26:52 +00:00
- in : query
2021-01-17 21:29:08 +00:00
name : order
2019-07-20 10:26:52 +00:00
required : false
2021-01-17 21:29:08 +00:00
description : Ordering users by username. Default ASC
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
type : string
enum :
- ASC
- DESC
example : ASC
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-07-20 10:26:52 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
type : array
items :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/User'
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
post :
tags :
2020-11-01 09:39:10 +00:00
- users
2021-03-06 16:08:24 +00:00
summary : Add user
2021-09-04 10:11:04 +00:00
description: 'Adds a new user.Recovery codes and TOTP configuration cannot be set using this API : each user must use the specific APIs'
2019-07-20 10:26:52 +00:00
operationId : add_user
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the hash of the password and the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2019-07-20 10:26:52 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/User'
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'201' :
2019-07-20 10:26:52 +00:00
description : successful operation
2022-12-23 12:08:04 +00:00
headers :
Location :
schema :
type : string
description : 'URI of the newly created object'
2019-07-20 10:26:52 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/User'
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-03-06 16:08:24 +00:00
'/users/{username}' :
2021-02-01 18:04:15 +00:00
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
2019-07-20 10:26:52 +00:00
get :
tags :
2020-11-01 09:39:10 +00:00
- users
2021-03-07 17:41:56 +00:00
summary : Find users by username
description : Returns the user with the given username if it exists. For security reasons the hashed password is omitted in the response
2021-01-17 21:29:08 +00:00
operationId : get_user_by_username
2023-04-18 16:11:23 +00:00
parameters :
- in : query
name : confidential_data
schema :
type : integer
2024-11-10 09:35:23 +00:00
description : 'If set to 1 confidential data will not be hidden. This means that the response will contain the hash of the password and the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.'
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-07-20 10:26:52 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/User'
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
put :
tags :
2020-11-01 09:39:10 +00:00
- users
2021-03-06 16:08:24 +00:00
summary : Update user
2023-04-06 16:22:09 +00:00
description: 'Updates an existing user and optionally disconnects it, if connected, to apply the new settings. The current password will be preserved if the password field is omitted in the request body. Recovery codes and TOTP configuration cannot be set/updated using this API : each user must use the specific APIs'
2019-08-01 20:42:46 +00:00
operationId : update_user
2019-11-13 10:36:21 +00:00
parameters :
2020-11-01 09:39:10 +00:00
- in : query
name : disconnect
schema :
type : integer
enum :
- 0
- 1
2021-03-06 16:08:24 +00:00
description : |
2020-11-01 09:39:10 +00:00
Disconnect :
* `0` The user will not be disconnected and it will continue to use the old configuration until connected. This is the default
* `1` The user will be disconnected after a successful update. It must login again and so it will be forced to use the new configuration
2019-07-20 10:26:52 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/User'
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-07-20 10:26:52 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2021-03-06 16:08:24 +00:00
message : User updated
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
delete :
tags :
2020-11-01 09:39:10 +00:00
- users
2021-03-06 16:08:24 +00:00
summary : Delete user
2021-03-07 17:41:56 +00:00
description : Deletes an existing user
2019-08-01 20:42:46 +00:00
operationId : delete_user
2019-07-20 10:26:52 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-07-20 10:26:52 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-07-20 10:26:52 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2021-03-06 16:08:24 +00:00
message : User deleted
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'404' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/NotFound'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-04 10:11:04 +00:00
'/users/{username}/2fa/disable' :
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
put :
tags :
- users
summary : Disable second factor authentication
description : 'Disables second factor authentication for the given user. This API must be used if the user loses access to their second factor auth device and has no recovery codes'
operationId : disable_user_2fa
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : 2FA disabled
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-11-13 12:25:43 +00:00
'/users/{username}/forgot-password' :
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
post :
security : [ ]
tags :
- users
summary : Send a password reset code by email
description : 'You must configure an SMTP server, the account must have a valid email address and must not have the "reset-password-disabled" restriction, in which case SFTPGo will send a code via email to reset the password. If the specified user does not exist, the request will be silently ignored (a success response will be returned) to avoid disclosing existing users'
operationId : user_forgot_password
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-13 12:25:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/users/{username}/reset-password' :
parameters :
- name : username
in : path
description : the username
required : true
schema :
type : string
post :
security : [ ]
tags :
- users
summary : Reset the password
description : 'Set a new password using the code received via email'
operationId : user_reset_password
requestBody :
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-13 12:25:43 +00:00
schema :
type : object
properties :
code :
type : string
password :
type : string
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-13 12:25:43 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2020-12-08 10:18:34 +00:00
/status :
get :
tags :
- maintenance
2021-03-06 16:08:24 +00:00
summary : Get status
2021-03-07 17:41:56 +00:00
description : Retrieves the status of the active services
2020-12-08 10:18:34 +00:00
operationId : get_status
responses :
2021-03-06 16:08:24 +00:00
'200' :
2020-12-08 10:18:34 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-12-08 10:18:34 +00:00
schema :
$ref : '#/components/schemas/ServicesStatus'
2021-03-06 16:08:24 +00:00
'400' :
2020-12-08 10:18:34 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-12-08 10:18:34 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-12-08 10:18:34 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-12-08 10:18:34 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-12-27 22:12:44 +00:00
/dumpdata :
get :
tags :
2020-11-01 09:39:10 +00:00
- maintenance
2021-03-07 17:41:56 +00:00
summary : Dump data
description : 'Backups data as data provider independent JSON. The backup can be saved in a local file on the server, to avoid exposing sensitive data over the network, or returned as response body. The output of dumpdata can be used as input for loaddata'
2019-12-27 22:12:44 +00:00
operationId : dumpdata
parameters :
- in : query
2021-01-22 18:42:18 +00:00
name : output-file
2019-12-27 22:12:44 +00:00
schema :
type : string
2021-01-22 18:42:18 +00:00
description : Path for the file to write the JSON serialized data to. This path is relative to the configured "backups_path". If this file already exists it will be overwritten. To return the backup as response body set `output_data` to true instead.
- in : query
name : output-data
schema :
type : integer
enum :
- 0
- 1
2021-03-06 16:08:24 +00:00
description : |
2021-03-21 18:15:47 +00:00
output data :
2021-01-22 18:42:18 +00:00
* `0` or any other value != 1, the backup will be saved to a file on the server, `output_file` is required
* `1` the backup will be returned as response body
2020-02-02 21:20:39 +00:00
- in : query
name : indent
schema :
type : integer
enum :
- 0
- 1
2021-03-06 16:08:24 +00:00
description : |
2020-02-02 21:20:39 +00:00
indent :
* `0` no indentation. This is the default
* `1` format the output JSON
2023-04-18 16:11:23 +00:00
- in : query
name : scopes
schema :
type : array
items :
$ref : '#/components/schemas/DumpDataScopes'
description : 'You can limit the dump contents to the specified scopes. Empty or missing means any supported scope. Scopes must be specified comma separated'
explode : false
required : false
2019-12-27 22:12:44 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-12-27 22:12:44 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-12-27 22:12:44 +00:00
schema :
2021-01-22 18:42:18 +00:00
oneOf :
- $ref : '#/components/schemas/ApiResponse'
- $ref : '#/components/schemas/BackupData'
2021-03-06 16:08:24 +00:00
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-12-27 22:12:44 +00:00
/loaddata :
2021-01-22 18:42:18 +00:00
parameters :
- in : query
name : scan-quota
schema :
type : integer
enum :
- 0
- 1
- 2
2021-03-06 16:08:24 +00:00
description : |
2021-01-22 18:42:18 +00:00
Quota scan :
* `0` no quota scan is done, the imported users/folders will have used_quota_size and used_quota_files = 0 or the existing values if they already exists. This is the default
* `1` scan quota
* `2` scan quota if the user has quota restrictions
required : false
- in : query
name : mode
schema :
type : integer
enum :
- 0
- 1
- 2
2021-03-06 16:08:24 +00:00
description : |
2021-01-22 18:42:18 +00:00
Mode :
2021-11-27 10:12:51 +00:00
* `0` New objects are added, existing ones are updated. This is the default
* `1` New objects are added, existing ones are not modified
* `2` New objects are added, existing ones are updated and connected users are disconnected and so forced to use the new configuration
2019-12-27 22:12:44 +00:00
get :
tags :
2020-11-01 09:39:10 +00:00
- maintenance
2021-03-07 17:41:56 +00:00
summary : Load data from path
2021-11-27 10:12:51 +00:00
description : 'Restores SFTPGo data from a JSON backup file on the server. Objects will be restored one by one and the restore is stopped if a object cannot be added or updated, so it could happen a partial restore'
2021-01-22 18:42:18 +00:00
operationId : loaddata_from_file
2019-12-27 22:12:44 +00:00
parameters :
- in : query
2021-01-22 18:42:18 +00:00
name : input-file
2019-12-27 22:12:44 +00:00
schema :
type : string
required : true
description : Path for the file to read the JSON serialized data from. This can be an absolute path or a path relative to the configured "backups_path". The max allowed file size is 10MB
2021-01-22 18:42:18 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2021-01-22 18:42:18 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-22 18:42:18 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-01-22 18:42:18 +00:00
example :
2021-03-06 16:08:24 +00:00
message : Data restored
'400' :
2021-01-22 18:42:18 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2021-01-22 18:42:18 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2021-01-22 18:42:18 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2021-01-22 18:42:18 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- maintenance
2021-03-07 17:41:56 +00:00
summary : Load data
2021-11-27 10:12:51 +00:00
description : 'Restores SFTPGo data from a JSON backup. Objects will be restored one by one and the restore is stopped if a object cannot be added or updated, so it could happen a partial restore'
2021-01-22 18:42:18 +00:00
operationId : loaddata_from_request_body
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-01-22 18:42:18 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/BackupData'
2019-12-27 22:12:44 +00:00
responses :
2021-03-06 16:08:24 +00:00
'200' :
2019-12-27 22:12:44 +00:00
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2019-12-27 22:12:44 +00:00
schema :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/ApiResponse'
2019-12-27 22:12:44 +00:00
example :
2021-03-06 16:08:24 +00:00
message : Data restored
'400' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/BadRequest'
2021-03-06 16:08:24 +00:00
'401' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Unauthorized'
2021-03-06 16:08:24 +00:00
'403' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/Forbidden'
2021-03-06 16:08:24 +00:00
'500' :
2020-09-08 07:45:21 +00:00
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-05 14:07:09 +00:00
/user/changepwd :
put :
2021-08-17 16:08:32 +00:00
security :
- BearerAuth : [ ]
2021-06-05 14:07:09 +00:00
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-06-05 14:07:09 +00:00
summary : Change user password
description : Changes the password for the logged in user
operationId : change_user_password
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-05 14:07:09 +00:00
schema :
$ref : '#/components/schemas/PwdChange'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-05 14:07:09 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-29 16:46:15 +00:00
/user/profile :
2021-09-06 16:46:35 +00:00
get :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-29 16:46:15 +00:00
summary : Get user profile
description : 'Returns the profile for the logged in user'
operationId : get_user_profile
2021-09-06 16:46:35 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-06 16:46:35 +00:00
schema :
2021-09-29 16:46:15 +00:00
$ref : '#/components/schemas/UserProfile'
2021-09-06 16:46:35 +00:00
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-30 08:23:25 +00:00
summary : Update user profile
2021-09-29 16:46:15 +00:00
description : 'Allows to update the profile for the logged in user'
operationId : update_user_profile
2021-09-06 16:46:35 +00:00
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-06 16:46:35 +00:00
schema :
2021-09-29 16:46:15 +00:00
$ref : '#/components/schemas/UserProfile'
2021-09-06 16:46:35 +00:00
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-06 16:46:35 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-09-04 10:11:04 +00:00
/user/2fa/recoverycodes :
get :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-04 10:11:04 +00:00
summary : Get recovery codes
description : 'Returns the recovery codes for the logged in user. Recovery codes can be used if the user loses access to their second factor auth device. Recovery codes are returned unencrypted'
operationId : get_user_recovery_codes
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/RecoveryCode'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-04 10:11:04 +00:00
summary : Generate recovery codes
description : 'Generates new recovery codes for the logged in user. Generating new recovery codes you automatically invalidate old ones'
operationId : generate_user_recovery_codes
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : array
items :
type : string
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/totp/configs :
get :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-04 10:11:04 +00:00
summary : Get available TOTP configuration
description : Returns the available TOTP configurations for the logged in user
operationId : get_user_totp_configs
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/TOTPConfig'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/totp/generate :
post :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-04 10:11:04 +00:00
summary : Generate a new TOTP secret
description : 'Generates a new TOTP secret, including the QR code as png, using the specified configuration for the logged in user'
operationId : generate_user_totp_secret
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : object
properties :
config_name :
type : string
description : 'name of the configuration to use to generate the secret'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : object
properties :
config_name :
type : string
issuer :
type : string
secret :
type : string
qr_code :
type : string
format : byte
description : 'QR code png encoded as BASE64'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/totp/validate :
post :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-04 10:11:04 +00:00
summary : Validate a one time authentication code
description : 'Checks if the given authentication code can be validated using the specified secret and config name'
operationId : validate_user_totp_secret
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
type : object
properties :
config_name :
type : string
description : 'name of the configuration to use to validate the passcode'
passcode :
type : string
description : 'passcode to validate'
secret :
type : string
description : 'secret to use to validate the passcode'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Passcode successfully validated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/totp/save :
post :
security :
- BearerAuth : [ ]
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-09-04 10:11:04 +00:00
summary : Save a TOTP config
description : 'Saves the specified TOTP config for the logged in user'
operationId : save_user_totp_config
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/UserTOTPConfig'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-09-04 10:11:04 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : TOTP configuration saved
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-11-06 13:13:20 +00:00
/user/shares :
get :
tags :
- user APIs
summary : List user shares
description : Returns the share for the logged in user
operationId : get_user_shares
parameters :
- in : query
name : offset
schema :
type : integer
minimum : 0
default : 0
required : false
- in : query
name : limit
schema :
type : integer
minimum : 1
maximum : 500
default : 100
required : false
description : 'The maximum number of items to return. Max value is 500, default is 100'
- in : query
name : order
required : false
description : Ordering shares by ID. Default ASC
schema :
type : string
enum :
- ASC
- DESC
example : ASC
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/Share'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
post :
tags :
- user APIs
summary : Add a share
operationId : add_share
description : 'Adds a new share. The share id will be auto-generated'
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
$ref : '#/components/schemas/Share'
responses :
'201' :
description : successful operation
headers :
X-Object-ID :
schema :
type : string
description : ID for the new created share
Location :
schema :
type : string
2022-12-23 12:08:04 +00:00
description : URI to retrieve the details for the new created share
2021-11-06 13:13:20 +00:00
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
'/user/shares/{id}' :
parameters :
- name : id
in : path
description : the share id
required : true
schema :
type : string
get :
tags :
- user APIs
summary : Get share by id
description : Returns a share by id for the logged in user
operationId : get_user_share_by_id
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
$ref : '#/components/schemas/Share'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
put :
tags :
- user APIs
summary : Update share
description : 'Updates an existing share belonging to the logged in user'
operationId : update_user_share
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
$ref : '#/components/schemas/Share'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Share updated
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
- user APIs
summary : Delete share
description : 'Deletes an existing share belonging to the logged in user'
operationId : delete_user_share
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-06 13:13:20 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
example :
message : Share deleted
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2022-12-30 18:30:16 +00:00
/user/file-actions/copy :
parameters :
- in : query
name : path
description : Path to the file/folder to copy. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
- in : query
name : target
description : New name. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
post :
tags :
- user APIs
summary : 'Copy a file or a directory'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-12-30 18:30:16 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/file-actions/move :
parameters :
- in : query
name : path
description : Path to the file/folder to rename. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
- in : query
name : target
description : New name. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
post :
tags :
- user APIs
summary : 'Move (rename) a file or a directory'
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2022-12-30 18:30:16 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-07-26 18:55:49 +00:00
/user/dirs :
get :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-07-26 18:55:49 +00:00
summary : Read directory contents
description : Returns the contents of the specified directory for the logged in user
operationId : get_user_dir_contents
2021-06-05 14:07:09 +00:00
parameters :
- in : query
name : path
2022-03-03 11:44:56 +00:00
description : Path to the folder to read. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir". If empty or missing the user's start directory is assumed. If relative, the user's start directory is used as the base
2021-06-05 14:07:09 +00:00
schema :
type : string
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-05 14:07:09 +00:00
schema :
type : array
items :
$ref : '#/components/schemas/DirEntry'
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-07-23 08:19:27 +00:00
post :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-07-23 08:19:27 +00:00
summary : Create a directory
description : Create a directory for the logged in user
2021-07-26 18:55:49 +00:00
operationId : create_user_dir
2021-07-23 08:19:27 +00:00
parameters :
- in : query
name : path
description : Path to the folder to create. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
2021-12-19 11:14:53 +00:00
- in : query
name : mkdir_parents
description : Create parent directories if they do not exist?
schema :
type : boolean
required : false
2021-07-23 08:19:27 +00:00
responses :
'201' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-07-23 08:19:27 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-07-23 08:19:27 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
patch :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2022-12-30 18:30:16 +00:00
deprecated : true
summary : 'Rename a directory. Deprecated, use "file-actions/move"'
2021-11-14 15:23:33 +00:00
description : Rename a directory for the logged in user. The rename is allowed for empty directory or for non empty local directories, with no virtual folders inside
2021-07-26 18:55:49 +00:00
operationId : rename_user_dir
2021-07-23 08:19:27 +00:00
parameters :
- in : query
name : path
description : Path to the folder to rename. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
- in : query
name : target
description : New name. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-07-23 08:19:27 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-07-23 08:19:27 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-07-23 08:19:27 +00:00
summary : Delete a directory
2022-12-30 18:30:16 +00:00
description : Delete a directory and any children it contains for the logged in user
2021-07-26 18:55:49 +00:00
operationId : delete_user_dir
2021-07-23 08:19:27 +00:00
parameters :
- in : query
name : path
description : Path to the folder to delete. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema :
type : string
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-07-23 08:19:27 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-07-23 08:19:27 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-07-26 18:55:49 +00:00
/user/files :
get :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-07-26 18:55:49 +00:00
summary : Download a single file
description : Returns the file contents as response body
operationId : download_user_file
2021-06-05 14:07:09 +00:00
parameters :
- in : query
name : path
required : true
description : Path to the file to download. It must be URL encoded, for example the path "my dir/àdir/file.txt" must be sent as "my%20dir%2F%C3%A0dir%2Ffile.txt"
schema :
type : string
2021-11-25 18:24:32 +00:00
- in : query
name : inline
required : false
description : 'If set, the response will not have the Content-Disposition header set to `attachment`'
schema :
type : string
2021-06-05 14:07:09 +00:00
responses :
'200' :
description : successful operation
content :
'*/*' :
schema :
type : string
format : binary
'206' :
description : successful operation
content :
'*/*' :
schema :
type : string
format : binary
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-07-23 08:19:27 +00:00
post :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-07-23 08:19:27 +00:00
summary : Upload files
description : Upload one or more files for the logged in user
operationId : create_user_files
parameters :
- in : query
name : path
description : Parent directory for the uploaded files. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir". If empty or missing the root path is assumed. If a file with the same name already exists, it will be overwritten
schema :
type : string
2021-12-19 11:14:53 +00:00
- in : query
name : mkdir_parents
description : Create parent directories if they do not exist?
schema :
type : boolean
required : false
2021-07-23 08:19:27 +00:00
requestBody :
content :
multipart/form-data :
schema :
type : object
properties :
2021-11-06 13:13:20 +00:00
filenames :
2021-07-23 08:19:27 +00:00
type : array
items :
type : string
format : binary
minItems : 1
uniqueItems : true
required : true
responses :
'201' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-07-23 08:19:27 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-07-23 08:19:27 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
2021-11-22 11:25:36 +00:00
'413' :
$ref : '#/components/responses/RequestEntityTooLarge'
2021-07-23 08:19:27 +00:00
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
patch :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2022-12-30 18:30:16 +00:00
deprecated : true
2021-07-27 16:43:00 +00:00
summary : Rename a file
2022-12-30 18:30:16 +00:00
description : 'Rename a file for the logged in user. Deprecated, use "file-actions/move"'
2021-07-23 08:19:27 +00:00
operationId : rename_user_file
parameters :
- in : query
name : path
description : Path to the file to rename. It must be URL encoded
schema :
type : string
required : true
- in : query
name : target
description : New name. It must be URL encoded
schema :
type : string
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-07-23 08:19:27 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-07-23 08:19:27 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
delete :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-07-23 08:19:27 +00:00
summary : Delete a file
description : Delete a file for the logged in user.
operationId : delete_user_file
parameters :
- in : query
name : path
description : Path to the file to delete. It must be URL encoded
schema :
type : string
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-07-23 08:19:27 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-07-23 08:19:27 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-12-08 18:25:22 +00:00
/user/files/upload :
post :
tags :
- user APIs
summary : Upload a single file
description : 'Upload a single file for the logged in user to an existing directory. This API does not use multipart/form-data and so no temporary files are created server side but only a single file can be uploaded as POST body'
operationId : create_user_file
parameters :
- in : query
name : path
description : Full file path. It must be path encoded, for example the path "my dir/àdir/file.txt" must be sent as "my%20dir%2F%C3%A0dir%2Ffile.txt". The parent directory must exist. If a file with the same name already exists, it will be overwritten
schema :
type : string
required : true
2021-12-19 11:14:53 +00:00
- in : query
name : mkdir_parents
description : Create parent directories if they do not exist?
schema :
type : boolean
required : false
2021-12-08 18:25:22 +00:00
- in : header
name : X-SFTPGO-MTIME
schema :
type : integer
description : File modification time as unix timestamp in milliseconds
requestBody :
content :
application/* :
schema :
type : string
format : binary
text/* :
schema :
type : string
format : binary
image/* :
schema :
type : string
format : binary
audio/* :
schema :
type : string
format : binary
video/* :
schema :
type : string
format : binary
required : true
responses :
'201' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-12-08 18:25:22 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-12-08 18:25:22 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'413' :
$ref : '#/components/responses/RequestEntityTooLarge'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
/user/files/metadata :
patch :
tags :
- user APIs
summary : Set metadata for a file/directory
description : 'Set supported metadata attributes for the specified file or directory'
operationId : setprops_user_file
parameters :
- in : query
name : path
description : Full file/directory path. It must be URL encoded, for example the path "my dir/àdir/file.txt" must be sent as "my%20dir%2F%C3%A0dir%2Ffile.txt"
schema :
type : string
required : true
requestBody :
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-12-08 18:25:22 +00:00
schema :
type : object
properties :
modification_time :
type : integer
description : File modification time as unix timestamp in milliseconds
required : true
responses :
'200' :
description : successful operation
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-12-08 18:25:22 +00:00
schema :
2022-12-30 18:30:16 +00:00
$ref : '#/components/schemas/ApiResponse'
2021-12-08 18:25:22 +00:00
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'413' :
$ref : '#/components/responses/RequestEntityTooLarge'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2021-06-05 14:07:09 +00:00
/user/streamzip :
post :
tags :
2021-11-06 13:13:20 +00:00
- user APIs
2021-06-05 14:07:09 +00:00
summary : Download multiple files and folders as a single zip file
description : A zip file, containing the specified files and folders, will be generated on the fly and returned as response body. Only folders and regular files will be included in the zip
operationId : streamzip
requestBody :
required : true
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-06-05 14:07:09 +00:00
schema :
type : array
items :
type : string
description : Absolute file or folder path
responses :
'200' :
description : successful operation
content :
'application/zip' :
schema :
type : string
format : binary
'400' :
$ref : '#/components/responses/BadRequest'
'401' :
$ref : '#/components/responses/Unauthorized'
'403' :
$ref : '#/components/responses/Forbidden'
'500' :
$ref : '#/components/responses/InternalServerError'
default :
$ref : '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
components :
2020-09-08 07:45:21 +00:00
responses :
BadRequest :
description : Bad Request
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
Unauthorized :
description : Unauthorized
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
Forbidden :
description : Forbidden
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
NotFound :
description : Not Found
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
Conflict :
description : Conflict
content :
2023-07-15 10:35:30 +00:00
application/json :
2021-11-22 11:25:36 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
RequestEntityTooLarge :
description : Request Entity Too Large, max allowed size exceeded
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
InternalServerError :
description : Internal Server Error
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
DefaultResponse :
description : Unexpected Error
content :
2023-07-15 10:35:30 +00:00
application/json :
2020-09-08 07:45:21 +00:00
schema :
$ref : '#/components/schemas/ApiResponse'
2019-07-20 10:26:52 +00:00
schemas :
Permission :
type : string
enum :
- '*'
- list
- download
- upload
2019-09-17 06:53:45 +00:00
- overwrite
2019-07-20 10:26:52 +00:00
- delete
2021-11-14 15:23:33 +00:00
- delete_files
- delete_dirs
2019-07-20 10:26:52 +00:00
- rename
2021-11-14 15:23:33 +00:00
- rename_files
- rename_dirs
2019-07-20 10:26:52 +00:00
- create_dirs
- create_symlinks
2019-11-15 11:15:07 +00:00
- chmod
- chown
2019-11-16 09:23:41 +00:00
- chtimes
2024-02-20 17:19:09 +00:00
- copy
2021-03-06 16:08:24 +00:00
description : |
2019-07-20 10:26:52 +00:00
Permissions :
2019-09-18 20:19:34 +00:00
* `*` - all permissions are granted
2019-07-20 10:26:52 +00:00
* `list` - list items is allowed
* `download` - download files is allowed
* `upload` - upload files is allowed
2019-09-17 06:53:45 +00:00
* `overwrite` - overwrite an existing file, while uploading, is allowed. upload permission is required to allow file overwrite
2019-07-20 10:26:52 +00:00
* `delete` - delete files or directories is allowed
2021-11-14 15:23:33 +00:00
* `delete_files` - delete files is allowed
* `delete_dirs` - delete directories is allowed
2019-07-20 10:26:52 +00:00
* `rename` - rename files or directories is allowed
2021-11-14 15:23:33 +00:00
* `rename_files` - rename files is allowed
* `rename_dirs` - rename directories is allowed
2019-07-20 10:26:52 +00:00
* `create_dirs` - create directories is allowed
* `create_symlinks` - create links is allowed
2019-11-15 11:15:07 +00:00
* `chmod` changing file or directory permissions is allowed
* `chown` changing file or directory owner and group is allowed
2019-11-16 09:23:41 +00:00
* `chtimes` changing file or directory access and modification time is allowed
2024-02-20 17:19:09 +00:00
* `copy`, copying files or directories is allowed
2021-01-17 21:29:08 +00:00
AdminPermissions :
type : string
enum :
- '*'
2021-03-06 16:08:24 +00:00
- add_users
- edit_users
- del_users
- view_users
- view_conns
- close_conns
- view_status
2023-07-23 16:48:49 +00:00
- manage_folders
2022-11-16 18:04:50 +00:00
- manage_groups
2021-03-06 16:08:24 +00:00
- quota_scans
- manage_defender
- view_defender
2021-10-23 13:47:21 +00:00
- view_events
2024-02-23 17:24:07 +00:00
- disable_mfa
2021-03-21 18:15:47 +00:00
description : |
Admin permissions :
2024-11-10 09:35:23 +00:00
* `*` - super admin permissions are granted
2021-03-21 18:15:47 +00:00
* `add_users` - add new users is allowed
* `edit_users` - change existing users is allowed
* `del_users` - remove users is allowed
* `view_users` - list users is allowed
* `view_conns` - list active connections is allowed
* `close_conns` - close active connections is allowed
* `view_status` - view the server status is allowed
2023-07-23 16:48:49 +00:00
* `manage_folders` - manage folders is allowed
2022-11-16 18:04:50 +00:00
* `manage_groups` - manage groups is allowed
2021-09-25 10:20:31 +00:00
* `quota_scans` - view and start quota scans is allowed
2021-03-21 18:15:47 +00:00
* `manage_defender` - remove ip from the dynamic blocklist is allowed
* `view_defender` - list the dynamic blocklist is allowed
2021-10-23 13:47:21 +00:00
* `view_events` - view and search filesystem and provider events is allowed
2024-02-23 17:24:07 +00:00
* `disable_mfa` - allow to disable two-factor authentication for users and admins
2022-01-03 16:02:52 +00:00
FsProviders :
type : integer
enum :
- 0
- 1
- 2
- 3
- 4
- 5
2022-06-11 08:41:34 +00:00
- 6
2022-01-03 16:02:52 +00:00
description : |
Filesystem providers :
* `0` - Local filesystem
* `1` - S3 Compatible Object Storage
* `2` - Google Cloud Storage
* `3` - Azure Blob Storage
* `4` - Local filesystem encrypted
* `5` - SFTP
2022-06-11 08:41:34 +00:00
* `6` - HTTP filesystem
2022-07-11 06:17:36 +00:00
EventActionTypes :
type : integer
enum :
- 1
- 2
- 3
- 4
- 5
- 6
- 7
2022-08-12 15:37:29 +00:00
- 8
- 9
2023-02-25 12:06:09 +00:00
- 11
- 12
2023-03-22 18:02:54 +00:00
- 13
2024-03-04 18:48:10 +00:00
- 14
2024-06-04 17:51:52 +00:00
- 15
2022-07-11 06:17:36 +00:00
description : |
Supported event action types :
* `1` - HTTP
* `2` - Command
* `3` - Email
* `4` - Backup
* `5` - User quota reset
* `6` - Folder quota reset
* `7` - Transfer quota reset
2022-08-12 15:37:29 +00:00
* `8` - Data retention check
* `9` - Filesystem
2023-02-25 12:06:09 +00:00
* `11` - Password expiration check
* `12` - User expiration check
2023-03-22 18:02:54 +00:00
* `13` - Identity Provider account check
2024-03-04 18:48:10 +00:00
* `14` - User inactivity check
2024-06-04 17:51:52 +00:00
* `15` - Rotate log file
2022-08-20 12:13:43 +00:00
FilesystemActionTypes :
type : integer
enum :
- 1
- 2
- 3
- 4
2023-04-23 12:46:09 +00:00
- 5
- 6
2022-08-20 12:13:43 +00:00
description : |
Supported filesystem action types :
* `1` - Rename
* `2` - Delete
* `3` - Mkdis
* `4` - Exist
2023-04-23 12:46:09 +00:00
* `5` - Compress
* `6` - Copy
2022-07-11 06:17:36 +00:00
EventTriggerTypes :
type : integer
enum :
- 1
- 2
- 3
2022-08-12 15:37:29 +00:00
- 4
- 5
2023-01-21 14:41:24 +00:00
- 6
2023-03-22 18:02:54 +00:00
- 7
2022-07-11 06:17:36 +00:00
description : |
Supported event trigger types :
* `1` - Filesystem event
* `2` - Provider event
* `3` - Schedule
2022-08-12 15:37:29 +00:00
* `4` - IP blocked
* `5` - Certificate renewal
2023-01-21 14:41:24 +00:00
* `6` - On demand, like schedule but executed on demand
2023-03-22 18:02:54 +00:00
* `7` - Identity provider login
2020-02-19 21:39:30 +00:00
LoginMethods :
type : string
enum :
2021-03-06 16:08:24 +00:00
- publickey
- password
2022-03-06 15:57:13 +00:00
- password-over-SSH
2021-03-06 16:08:24 +00:00
- keyboard-interactive
- publickey+password
- publickey+keyboard-interactive
- TLSCertificate
- TLSCertificate+password
description : |
2021-03-21 18:15:47 +00:00
Available login methods. To enable multi-step authentication you have to allow only multi-step login methods
* `publickey`
2022-03-06 15:57:13 +00:00
* `password`, password for all the supported protocols
* `password-over-SSH`, password over SSH protocol (SSH/SFTP/SCP)
2021-03-21 18:15:47 +00:00
* `keyboard-interactive`
* `publickey+password` - multi-step auth : public key and password
* `publickey+keyboard-interactive` - multi-step auth : public key and keyboard interactive
* `TLSCertificate`
* `TLSCertificate+password` - multi-step auth : TLS client certificate and password
2020-08-17 10:49:20 +00:00
SupportedProtocols :
type : string
enum :
2021-03-06 16:08:24 +00:00
- SSH
- FTP
- DAV
2021-05-06 19:35:43 +00:00
- HTTP
2021-03-21 18:15:47 +00:00
description : |
Protocols :
* `SSH` - includes both SFTP and SSH commands
* `FTP` - plain FTP and FTPES/FTPS
* `DAV` - WebDAV over HTTP/HTTPS
2021-09-04 10:11:04 +00:00
* `HTTP` - WebClient/REST API
MFAProtocols :
type : string
enum :
- SSH
- FTP
- HTTP
description : |
Protocols :
* `SSH` - includes both SFTP and SSH commands
* `FTP` - plain FTP and FTPES/FTPS
* `HTTP` - WebClient/REST API
2021-10-20 17:39:49 +00:00
EventProtocols :
type : string
enum :
- SSH
- SFTP
- SCP
- FTP
- DAV
- HTTP
2022-02-19 12:31:58 +00:00
- HTTPShare
2021-10-20 17:39:49 +00:00
- DataRetention
2022-12-07 17:47:38 +00:00
- EventAction
2022-02-19 09:53:35 +00:00
- OIDC
2021-10-20 17:39:49 +00:00
description : |
Protocols :
* `SSH` - SSH commands
* `SFTP` - SFTP protocol
2022-12-07 17:47:38 +00:00
* `SCP` - SCP protocol
2021-10-20 17:39:49 +00:00
* `FTP` - plain FTP and FTPES/FTPS
* `DAV` - WebDAV
* `HTTP` - WebClient/REST API
2022-02-19 12:31:58 +00:00
* `HTTPShare` - the event is generated in a public share
2021-10-20 17:39:49 +00:00
* `DataRetention` - the event is generated by a data retention check
2022-12-07 17:47:38 +00:00
* `EventAction` - the event is generated by an EventManager action
2022-02-19 09:53:35 +00:00
* `OIDC` - OpenID Connect
2021-05-06 19:35:43 +00:00
WebClientOptions :
type : string
enum :
- publickey-change-disabled
2024-05-03 16:30:03 +00:00
- tls-cert-change-disabled
2021-07-23 19:41:02 +00:00
- write-disabled
2021-09-04 10:11:04 +00:00
- mfa-disabled
2021-09-05 16:49:13 +00:00
- password-change-disabled
2021-09-06 16:46:35 +00:00
- api-key-auth-change-disabled
2021-09-29 16:46:15 +00:00
- info-change-disabled
2021-11-06 13:13:20 +00:00
- shares-disabled
2021-11-13 12:25:43 +00:00
- password-reset-disabled
2022-02-19 12:31:58 +00:00
- shares-without-password-disabled
2021-05-06 19:35:43 +00:00
description : |
Options :
* `publickey-change-disabled` - changing SSH public keys is not allowed
2024-05-03 16:30:03 +00:00
* `tls-cert-change-disabled` - changing TLS certificates is not allowed
2021-07-23 19:41:02 +00:00
* `write-disabled` - upload, rename, delete are not allowed even if the user has permissions for these actions
2021-09-05 16:49:13 +00:00
* `mfa-disabled` - enabling multi-factor authentication is not allowed. This option cannot be set if the user has MFA already enabled
* `password-change-disabled` - changing password is not allowed
2021-09-06 16:46:35 +00:00
* `api-key-auth-change-disabled` - enabling/disabling API key authentication is not allowed
2021-09-29 16:46:15 +00:00
* `info-change-disabled` - changing info such as email and description is not allowed
2022-02-19 12:31:58 +00:00
* `shares-disabled` - sharing files and directories with external users is not allowed
* `password-reset-disabled` - resetting the password is not allowed
* `shares-without-password-disabled` - creating shares without password protection is not allowed
2021-10-02 20:25:41 +00:00
RetentionCheckNotification :
type : string
enum :
2021-10-03 13:17:49 +00:00
- Hook
2021-10-02 20:25:41 +00:00
- Email
description : |
Options :
2021-10-03 13:17:49 +00:00
* `Hook` - notify result using the defined hook. A "data_retention_hook" must be defined in your configuration file for this to work
2021-10-02 20:25:41 +00:00
* `Email` - notify results by email. The admin starting the retention check must have an associated email address and the SMTP server must be configured for this to work
2021-08-17 16:08:32 +00:00
APIKeyScope :
type : integer
enum :
- 1
- 2
description : |
Options :
* `1` - admin scope. The API key will be used to impersonate an SFTPGo admin
* `2` - user scope. The API key will be used to impersonate an SFTPGo user
2021-11-06 13:13:20 +00:00
ShareScope :
type : integer
enum :
- 1
- 2
description : |
Options :
* `1` - read scope
* `2` - write scope
2021-09-04 10:11:04 +00:00
TOTPHMacAlgo :
type : string
enum :
- sha1
- sha256
- sha512
description : 'Supported HMAC algorithms for Time-based one time passwords'
UserType :
type : string
enum :
- ''
- LDAPUser
- OSUser
description : This is an hint for authentication plugins. It is ignored when using SFTPGo internal authentication
2023-04-18 16:11:23 +00:00
DumpDataScopes :
type : string
enum :
- users
- folders
- groups
- admins
- api_keys
- shares
- actions
- rules
- roles
- ip_lists
- configs
2023-05-12 16:34:59 +00:00
LogEventType :
type : integer
enum :
- 1
- 2
- 3
- 4
2024-04-10 16:39:08 +00:00
- 5
2023-05-12 16:34:59 +00:00
description : >
Event status :
* `1` - Login failed
* `2` - Login failed non-existent user
* `3` - No login tried
* `4` - Algorithm negotiation failed
2024-04-10 16:39:08 +00:00
* `5` - Login succeeded
2021-10-20 17:39:49 +00:00
FsEventStatus :
type : integer
enum :
- 1
- 2
- 3
description : >
Event status :
* `1` - no error
* `2` - generic error
* `3` - quota exceeded error
FsEventAction :
type : string
enum :
- download
- upload
2022-12-08 09:02:12 +00:00
- first-upload
- first-download
2021-10-20 17:39:49 +00:00
- delete
- rename
- mkdir
- rmdir
- ssh_cmd
ProviderEventAction :
type : string
enum :
- add
- update
- delete
ProviderEventObjectType :
type : string
enum :
- user
2022-07-24 06:10:23 +00:00
- folder
- group
2021-10-20 17:39:49 +00:00
- admin
- api_key
2021-11-06 13:13:20 +00:00
- share
2022-07-24 06:10:23 +00:00
- event_action
- event_rule
2022-11-16 18:04:50 +00:00
- role
2022-02-26 15:43:29 +00:00
SSHAuthentications :
type : string
enum :
- publickey
- password
- keyboard-interactive
- publickey+password
- publickey+keyboard-interactive
TLSVersions :
type : integer
enum :
- 12
- 13
description : >
TLS version :
* `12` - TLS 1.2
* `13` - TLS 1.3
2023-02-09 08:33:33 +00:00
IPListType :
type : integer
enum :
- 1
- 2
- 3
description : >
IP List types :
2023-02-13 11:58:21 +00:00
* `1` - allow list
2023-02-09 08:33:33 +00:00
* `2` - defender
* `3` - rate limiter safe list
IPListMode :
type : integer
enum :
- 1
- 2
description : >
IP list modes
* `1` - allow
* `2` - deny, supported for defender list type only
2021-09-04 10:11:04 +00:00
TOTPConfig :
type : object
properties :
name :
type : string
issuer :
type : string
algo :
$ref : '#/components/schemas/TOTPHMacAlgo'
RecoveryCode :
type : object
properties :
secret :
$ref : '#/components/schemas/Secret'
used :
type : boolean
description : 'Recovery codes to use if the user loses access to their second factor auth device. Each code can only be used once, you should use these codes to login and disable or reset 2FA for your account'
BaseTOTPConfig :
type : object
properties :
enabled :
type : boolean
config_name :
type : string
description : 'This name must be defined within the "totp" section of the SFTPGo configuration file. You will be unable to save a user/admin referencing a missing config_name'
secret :
$ref : '#/components/schemas/Secret'
AdminTOTPConfig :
allOf :
- $ref : '#/components/schemas/BaseTOTPConfig'
UserTOTPConfig :
allOf :
- $ref : '#/components/schemas/BaseTOTPConfig'
- type : object
properties :
protocols :
type : array
items :
$ref : '#/components/schemas/MFAProtocols'
description : 'TOTP will be required for the specified protocols. SSH protocol (SFTP/SCP/SSH commands) will ask for the TOTP passcode if the client uses keyboard interactive authentication. FTP has no standard way to support two factor authentication, if you enable the FTP support, you have to add the TOTP passcode after the password. For example if your password is "password" and your one time passcode is "123456" you have to use "password123456" as password. WebDAV is not supported since each single request must be authenticated and a passcode cannot be reused.'
2020-11-15 21:04:48 +00:00
PatternsFilter :
type : object
properties :
path :
type : string
2023-02-09 08:33:33 +00:00
description : 'virtual path as seen by users, if no other specific filter is defined, the filter applies for sub directories too. For example if filters are defined for the paths "/" and "/sub" then the filters for "/" are applied for any file outside the "/sub" directory'
2020-11-15 21:04:48 +00:00
allowed_patterns :
type : array
items :
type : string
2023-05-24 17:56:53 +00:00
description : 'list of, case insensitive, allowed shell like patterns. Allowed patterns are evaluated before the denied ones'
2021-03-06 16:08:24 +00:00
example :
- '*.jpg'
- a*b?.png
2020-11-15 21:04:48 +00:00
denied_patterns :
type : array
items :
type : string
2023-05-24 17:56:53 +00:00
description : 'list of, case insensitive, denied shell like patterns'
2021-03-06 16:08:24 +00:00
example :
- '*.zip'
2022-01-15 16:16:49 +00:00
deny_policy :
type : integer
enum :
- 0
- 1
description : |
2023-06-14 17:00:52 +00:00
Policies for denied patterns
2022-01-15 16:16:49 +00:00
* `0` - default policy. Denied files/directories matching the filters are visible in directory listing but cannot be uploaded/downloaded/overwritten/renamed
* `1` - deny policy hide. This policy applies the same restrictions as the default one and denied files/directories matching the filters will also be hidden in directory listing. This mode may cause performance issues for large directories
2021-04-04 20:32:25 +00:00
HooksFilter :
type : object
properties :
external_auth_disabled :
type : boolean
example : false
description : If true, the external auth hook, if defined, will not be executed
pre_login_disabled :
type : boolean
example : false
description : If true, the pre-login hook, if defined, will not be executed
check_password_disabled :
type : boolean
example : false
description : If true, the check password hook, if defined, will not be executed
description : User specific hook overrides
2021-12-10 17:43:26 +00:00
BandwidthLimit :
type : object
properties :
sources :
type : array
items :
type : string
description : 'Source networks in CIDR notation as defined in RFC 4632 and RFC 4291 for example `192.0.2.0/24` or `2001:db8::/32`. The limit applies if the defined networks contain the client IP'
upload_bandwidth :
type : integer
format : int32
description : 'Maximum upload bandwidth as KB/s, 0 means unlimited'
download_bandwidth :
type : integer
format : int32
description : 'Maximum download bandwidth as KB/s, 0 means unlimited'
2024-03-18 18:32:01 +00:00
TimePeriod :
type : object
properties :
day_of_week :
type : integer
enum :
- 0
- 1
- 2
- 3
- 4
- 5
- 6
description : Day of week, 0 Sunday, 6 Saturday
from :
type : string
description : Start time in HH:MM format
to :
type : string
description : End time in HH:MM format
2022-04-25 13:49:11 +00:00
BaseUserFilters :
2019-12-30 17:37:50 +00:00
type : object
properties :
allowed_ip :
type : array
items :
type : string
2021-03-06 16:08:24 +00:00
description : 'only clients connecting from these IP/Mask are allowed. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32"'
example :
- 192.0 .2 .0 /24
- '2001:db8::/32'
2019-12-30 17:37:50 +00:00
denied_ip :
type : array
items :
type : string
description : clients connecting from these IP/Mask are not allowed. Denied rules are evaluated before allowed ones
2021-03-06 16:08:24 +00:00
example :
- 172.16 .0 .0 /16
2020-02-19 21:39:30 +00:00
denied_login_methods :
type : array
items :
$ref : '#/components/schemas/LoginMethods'
description : if null or empty any available login method is allowed
2020-08-17 10:49:20 +00:00
denied_protocols :
type : array
items :
$ref : '#/components/schemas/SupportedProtocols'
description : if null or empty any available protocol is allowed
2020-11-15 21:04:48 +00:00
file_patterns :
type : array
items :
$ref : '#/components/schemas/PatternsFilter'
2021-03-06 16:08:24 +00:00
description : 'filters based on shell like file patterns. These restrictions do not apply to files listing for performance reasons, so a denied file cannot be downloaded/overwritten/renamed but it will still be in the list of files. Please note that these restrictions can be easily bypassed'
2020-08-16 18:17:02 +00:00
max_upload_file_size :
type : integer
format : int64
2021-03-06 16:08:24 +00:00
description : 'maximum allowed size, as bytes, for a single file upload. The upload will be aborted if/when the size of the file being sent exceeds this limit. 0 means unlimited. This restriction does not apply for SSH system commands such as `git` and `rsync`'
2021-02-28 11:10:40 +00:00
tls_username :
type : string
2023-05-25 16:24:51 +00:00
description : 'defines the TLS certificate field to use as username. For FTP clients it must match the name provided using the "USER" command. For WebDAV, if no username is provided, the CN will be used as username. For WebDAV clients it must match the implicit or provided username. Ignored if mutual TLS is disabled. Currently the only supported value is `CommonName`'
2021-04-04 20:32:25 +00:00
hooks :
$ref : '#/components/schemas/HooksFilter'
2021-04-05 15:57:30 +00:00
disable_fs_checks :
type : boolean
example : false
description : Disable checks for existence and automatic creation of home directory and virtual folders. SFTPGo requires that the user's home directory, virtual folder root, and intermediate paths to virtual folders exist to work properly. If you already know that the required directories exist, disabling these checks will speed up login. You could, for example, disable these checks after the first login
2021-05-06 19:35:43 +00:00
web_client :
type : array
items :
$ref : '#/components/schemas/WebClientOptions'
2021-07-23 19:41:02 +00:00
description : WebClient/user REST API related configuration options
2021-08-17 16:08:32 +00:00
allow_api_key_auth :
type : boolean
description : 'API key authentication allows to impersonate this user with an API key'
2021-09-04 10:11:04 +00:00
user_type :
$ref : '#/components/schemas/UserType'
2021-12-10 17:43:26 +00:00
bandwidth_limits :
type : array
items :
$ref : '#/components/schemas/BandwidthLimit'
2022-02-25 10:51:10 +00:00
external_auth_cache_time :
type : integer
description : 'Defines the cache time, in seconds, for users authenticated using an external auth hook. 0 means no cache'
2022-03-03 11:44:56 +00:00
start_directory :
type : string
description : 'Specifies an alternate starting directory. If not set, the default is "/". This option is supported for SFTP/SCP, FTP and HTTP (WebClient/REST API) protocols. Relative paths will use this directory as base.'
2023-03-26 13:57:53 +00:00
two_factor_protocols :
2022-03-06 15:57:13 +00:00
type : array
items :
$ref : '#/components/schemas/MFAProtocols'
description : 'Defines protocols that require two factor authentication'
2022-07-26 16:51:39 +00:00
ftp_security :
type : integer
enum :
- 0
- 1
description : 'Set to `1` to require TLS for both data and control connection. his setting is useful if you want to allow both encrypted and plain text FTP sessions globally and then you want to require encrypted sessions on a per-user basis. It has no effect if TLS is already required for all users in the configuration file.'
2022-07-27 16:54:25 +00:00
is_anonymous :
type : boolean
description : 'If enabled the user can login with any password or no password at all. Anonymous users are supported for FTP and WebDAV protocols and permissions will be automatically set to "list" and "download" (read only)'
2022-08-28 12:41:42 +00:00
default_shares_expiration :
type : integer
description : 'Defines the default expiration for newly created shares as number of days. 0 means no expiration'
2023-08-07 17:07:20 +00:00
max_shares_expiration :
type : integer
description : 'Defines the maximum allowed expiration, as a number of days, when a user creates or updates a share. 0 means no expiration'
2022-12-11 16:53:41 +00:00
password_expiration :
type : integer
description : 'The password expires after the defined number of days. 0 means no expiration'
2024-10-26 19:19:28 +00:00
password_strength :
type : integer
description : 'Defines the minimum password strength. 0 means disabled, any password will be accepted. Values in the 50-70 range are suggested for common use cases'
2024-03-18 18:32:01 +00:00
access_time :
type : array
items :
$ref : '#/components/schemas/TimePeriod'
2021-05-06 19:35:43 +00:00
description : Additional user options
2022-04-25 13:49:11 +00:00
UserFilters :
allOf :
- $ref : '#/components/schemas/BaseUserFilters'
- type : object
properties :
2022-12-11 16:53:41 +00:00
require_password_change :
type : boolean
description : 'User must change password from WebClient/REST API at next login'
2022-04-25 13:49:11 +00:00
totp_config :
$ref : '#/components/schemas/UserTOTPConfig'
recovery_codes :
type : array
items :
$ref : '#/components/schemas/RecoveryCode'
2024-10-16 18:51:51 +00:00
tls_certs :
type : array
items :
type : string
additional_emails :
type : array
items :
type : string
2020-11-22 20:53:04 +00:00
Secret :
type : object
properties :
status :
type : string
enum :
- Plain
- AES-256-GCM
2020-11-30 20:46:34 +00:00
- Secretbox
- GCP
- AWS
- VaultTransit
2021-09-25 10:20:31 +00:00
- AzureKeyVault
2020-11-22 20:53:04 +00:00
- Redacted
2021-03-06 16:08:24 +00:00
description : 'Set to "Plain" to add or update an existing secret, set to "Redacted" to preserve the existing value'
2020-11-22 20:53:04 +00:00
payload :
type : string
key :
type : string
additional_data :
type : string
2020-12-01 21:18:16 +00:00
mode :
type : integer
description : 1 means encrypted using a master key
2022-05-05 16:26:22 +00:00
description : The secret is encrypted before saving, so to set a new secret you must provide a payload and set the status to "Plain". The encryption key and additional data will be generated automatically. If you set the status to "Redacted" the existing secret will be preserved
2020-01-19 06:41:05 +00:00
S3Config :
type : object
properties :
bucket :
type : string
minLength : 1
region :
type : string
minLength : 1
access_key :
type : string
access_secret :
2020-11-22 20:53:04 +00:00
$ref : '#/components/schemas/Secret'
2024-08-15 08:09:06 +00:00
sse_customer_key :
$ref : '#/components/schemas/Secret'
2022-02-28 19:19:13 +00:00
role_arn :
type : string
2022-03-27 14:32:21 +00:00
description : 'Optional IAM Role ARN to assume'
2024-05-02 18:01:30 +00:00
session_token :
type : string
description : 'Optional Session token that is a part of temporary security credentials provisioned by AWS STS'
2020-01-19 06:41:05 +00:00
endpoint :
type : string
description : optional endpoint
storage_class :
type : string
2021-11-13 15:05:40 +00:00
acl :
type : string
description: 'The canned ACL to apply to uploaded objects. Leave empty to use the default ACL. For more information and available ACLs, see here : https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl'
2020-03-13 16:28:55 +00:00
upload_part_size :
type : integer
2021-03-06 16:08:24 +00:00
description : 'the buffer size (in MB) to use for multipart uploads. The minimum allowed part size is 5MB, and if this value is set to zero, the default value (5MB) for the AWS SDK will be used. The minimum allowed value is 5.'
2020-03-13 16:28:55 +00:00
upload_concurrency :
type : integer
2021-07-23 14:56:48 +00:00
description : 'the number of parts to upload in parallel. If this value is set to zero, the default value (5) will be used'
2022-02-01 11:15:56 +00:00
upload_part_max_time :
type : integer
description : 'the maximum time allowed, in seconds, to upload a single chunk (the chunk size is defined via "upload_part_size"). 0 means no timeout'
2021-07-23 14:56:48 +00:00
download_part_size :
type : integer
description : 'the buffer size (in MB) to use for multipart downloads. The minimum allowed part size is 5MB, and if this value is set to zero, the default value (5MB) for the AWS SDK will be used. The minimum allowed value is 5. Ignored for partial downloads'
download_concurrency :
type : integer
description : 'the number of parts to download in parallel. If this value is set to zero, the default value (5) will be used. Ignored for partial downloads'
2021-07-11 16:39:45 +00:00
download_part_max_time :
type : integer
2022-02-01 11:15:56 +00:00
description : 'the maximum time allowed, in seconds, to download a single chunk (the chunk size is defined via "download_part_size"). 0 means no timeout. Ignored for partial downloads.'
2021-07-23 14:56:48 +00:00
force_path_style :
type : boolean
description : 'Set this to "true" to force the request to use path-style addressing, i.e., "http://s3.amazonaws.com/BUCKET/KEY". By default, the S3 client will use virtual hosted bucket addressing when possible ("http://BUCKET.s3.amazonaws.com/KEY")'
2020-01-19 22:23:09 +00:00
key_prefix :
type : string
2021-03-06 16:08:24 +00:00
description : 'key_prefix is similar to a chroot directory for a local filesystem. If specified the user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole bucket contents will be available'
2020-01-19 22:23:09 +00:00
example : folder/subfolder/
2020-01-19 06:41:05 +00:00
description : S3 Compatible Object Storage configuration details
2020-01-31 18:04:00 +00:00
GCSConfig :
type : object
properties :
bucket :
type : string
minLength : 1
credentials :
2020-11-22 20:53:04 +00:00
$ref : '#/components/schemas/Secret'
2020-02-19 08:41:15 +00:00
automatic_credentials :
type : integer
enum :
- 0
- 1
2021-03-06 16:08:24 +00:00
description : |
2020-02-19 08:41:15 +00:00
Automatic credentials :
* `0` - disabled, explicit credentials, using a JSON credentials file, must be provided. This is the default value if the field is null
* `1` - enabled, we try to use the Application Default Credentials (ADC) strategy to find your application's credentials
2020-01-31 18:04:00 +00:00
storage_class :
type : string
2021-11-15 20:57:41 +00:00
acl :
type : string
description: 'The ACL to apply to uploaded objects. Leave empty to use the default ACL. For more information and available ACLs, refer to the JSON API here : https://cloud.google.com/storage/docs/access-control/lists#predefined-acl'
2020-01-31 18:04:00 +00:00
key_prefix :
type : string
2021-03-06 16:08:24 +00:00
description : 'key_prefix is similar to a chroot directory for a local filesystem. If specified the user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole bucket contents will be available'
2020-01-31 18:04:00 +00:00
example : folder/subfolder/
2022-12-18 10:51:46 +00:00
upload_part_size :
type : integer
description : 'The buffer size (in MB) to use for multipart uploads. The default value is 16MB. 0 means use the default'
upload_part_max_time :
type : integer
description : 'The maximum time allowed, in seconds, to upload a single chunk. The default value is 32. 0 means use the default'
2021-03-06 16:08:24 +00:00
description : 'Google Cloud Storage configuration details. The "credentials" field must be populated only when adding/updating a user. It will be always omitted, since there are sensitive data, when you search/get users'
2020-10-25 07:18:48 +00:00
AzureBlobFsConfig :
type : object
properties :
container :
type : string
account_name :
type : string
2021-03-06 16:08:24 +00:00
description : 'Storage Account Name, leave blank to use SAS URL'
2020-10-25 07:18:48 +00:00
account_key :
2020-11-22 20:53:04 +00:00
$ref : '#/components/schemas/Secret'
2020-10-25 07:18:48 +00:00
sas_url :
2021-06-11 20:27:36 +00:00
$ref : '#/components/schemas/Secret'
2020-10-25 07:18:48 +00:00
endpoint :
type : string
2021-03-06 16:08:24 +00:00
description : 'optional endpoint. Default is "blob.core.windows.net". If you use the emulator the endpoint must include the protocol, for example "http://127.0.0.1:10000"'
2020-10-25 07:18:48 +00:00
upload_part_size :
type : integer
2022-02-21 18:01:31 +00:00
description : 'the buffer size (in MB) to use for multipart uploads. If this value is set to zero, the default value (5MB) will be used.'
2020-10-25 07:18:48 +00:00
upload_concurrency :
type : integer
2022-02-21 18:01:31 +00:00
description : 'the number of parts to upload in parallel. If this value is set to zero, the default value (5) will be used'
download_part_size :
type : integer
description : 'the buffer size (in MB) to use for multipart downloads. If this value is set to zero, the default value (5MB) will be used.'
download_concurrency :
type : integer
description : 'the number of parts to download in parallel. If this value is set to zero, the default value (5) will be used'
2020-10-30 21:17:17 +00:00
access_tier :
type : string
enum :
2021-03-06 16:08:24 +00:00
- ''
- Archive
- Hot
- Cool
2020-10-25 07:18:48 +00:00
key_prefix :
type : string
2021-03-06 16:08:24 +00:00
description : 'key_prefix is similar to a chroot directory for a local filesystem. If specified the user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole container contents will be available'
2020-10-25 07:18:48 +00:00
example : folder/subfolder/
use_emulator :
type : boolean
description : Azure Blob Storage configuration details
2023-05-16 16:08:14 +00:00
OSFsConfig :
type : object
properties :
read_buffer_size :
type : integer
minimum : 0
maximum : 10
2023-05-17 16:24:33 +00:00
description : "The read buffer size, as MB, to use for downloads. 0 means no buffering, that's fine in most use cases."
2023-05-16 16:08:14 +00:00
write_buffer_size :
type : integer
minimum : 0
maximum : 10
2023-05-17 16:24:33 +00:00
description : "The write buffer size, as MB, to use for uploads. 0 means no buffering, that's fine in most use cases."
2020-12-05 12:48:13 +00:00
CryptFsConfig :
type : object
properties :
passphrase :
$ref : '#/components/schemas/Secret'
2023-05-16 16:08:14 +00:00
read_buffer_size :
type : integer
minimum : 0
maximum : 10
2023-05-17 16:24:33 +00:00
description : "The read buffer size, as MB, to use for downloads. 0 means no buffering, that's fine in most use cases."
2023-05-16 16:08:14 +00:00
write_buffer_size :
type : integer
minimum : 0
maximum : 10
2023-05-17 16:24:33 +00:00
description : "The write buffer size, as MB, to use for uploads. 0 means no buffering, that's fine in most use cases."
2020-12-05 12:48:13 +00:00
description : Crypt filesystem configuration details
2020-12-12 09:31:09 +00:00
SFTPFsConfig :
type : object
properties :
endpoint :
type : string
2021-03-06 16:08:24 +00:00
description : 'remote SFTP endpoint as host:port'
2020-12-12 09:31:09 +00:00
username :
type : string
description : you can specify a password or private key or both. In the latter case the private key will be tried first.
password :
$ref : '#/components/schemas/Secret'
private_key :
$ref : '#/components/schemas/Secret'
2022-05-30 17:01:12 +00:00
key_passphrase :
$ref : '#/components/schemas/Secret'
2020-12-12 09:31:09 +00:00
fingerprints :
type : array
items :
type : string
2021-03-06 16:08:24 +00:00
description : 'SHA256 fingerprints to use for host key verification. If you don' 't provide any fingerprint the remote host key will not be verified, this is a security risk'
2020-12-12 09:31:09 +00:00
prefix :
type : string
description : Specifying a prefix you can restrict all operations to a given path within the remote SFTP server.
2021-03-06 14:41:40 +00:00
disable_concurrent_reads :
type : boolean
description : Concurrent reads are safe to use and disabling them will degrade performance. Some servers automatically delete files once they are downloaded. Using concurrent reads is problematic with such servers.
2021-04-03 14:00:55 +00:00
buffer_size :
2021-04-03 15:09:08 +00:00
type : integer
2021-04-04 20:32:25 +00:00
minimum : 0
maximum : 16
example : 2
2021-04-03 14:00:55 +00:00
description : The size of the buffer (in MB) to use for transfers. By enabling buffering, the reads and writes, from/to the remote SFTP server, are split in multiple concurrent requests and this allows data to be transferred at a faster rate, over high latency networks, by overlapping round-trip times. With buffering enabled, resuming uploads is not supported and a file cannot be opened for both reading and writing at the same time. 0 means disabled.
2022-08-15 19:39:04 +00:00
equality_check_mode :
type : integer
enum :
- 0
- 1
description : |
Defines how to check if this config points to the same server as another config. If different configs point to the same server the renaming between the fs configs is allowed :
* `0` username and endpoint must match. This is the default
2022-08-22 17:04:17 +00:00
* `1` only the endpoint must match
2022-06-11 08:41:34 +00:00
HTTPFsConfig :
type : object
properties :
endpoint :
type : string
description : 'HTTP/S endpoint URL. SFTPGo will use this URL as base, for example for the `stat` API, SFTPGo will add `/stat/{name}`'
username :
type : string
password :
$ref : '#/components/schemas/Secret'
api_key :
$ref : '#/components/schemas/Secret'
skip_tls_verify :
type : boolean
2022-08-15 19:39:04 +00:00
equality_check_mode :
type : integer
enum :
- 0
- 1
description : |
Defines how to check if this config points to the same server as another config. If different configs point to the same server the renaming between the fs configs is allowed :
* `0` username and endpoint must match. This is the default
* `1` only the endpoint must match
2020-01-19 06:41:05 +00:00
FilesystemConfig :
type : object
properties :
provider :
2022-01-03 16:02:52 +00:00
$ref : '#/components/schemas/FsProviders'
2023-05-16 16:08:14 +00:00
osconfig :
$ref : '#/components/schemas/OSFsConfig'
2020-01-19 06:41:05 +00:00
s3config :
$ref : '#/components/schemas/S3Config'
2020-01-31 18:04:00 +00:00
gcsconfig :
$ref : '#/components/schemas/GCSConfig'
2020-10-25 07:18:48 +00:00
azblobconfig :
$ref : '#/components/schemas/AzureBlobFsConfig'
2020-12-05 12:48:13 +00:00
cryptconfig :
$ref : '#/components/schemas/CryptFsConfig'
2020-12-12 09:31:09 +00:00
sftpconfig :
$ref : '#/components/schemas/SFTPFsConfig'
2022-06-11 08:41:34 +00:00
httpconfig :
$ref : '#/components/schemas/HTTPFsConfig'
2020-01-19 06:41:05 +00:00
description : Storage filesystem details
2020-06-07 21:30:18 +00:00
BaseVirtualFolder :
2020-02-23 10:30:26 +00:00
type : object
properties :
2020-06-07 21:30:18 +00:00
id :
type : integer
format : int32
minimum : 1
2021-02-01 18:04:15 +00:00
name :
type : string
description : unique name for this virtual folder
2020-02-23 10:30:26 +00:00
mapped_path :
type : string
2021-02-01 18:04:15 +00:00
description : absolute filesystem path to use as virtual folder
2021-02-24 18:40:29 +00:00
description :
type : string
description : optional description
2020-06-07 21:30:18 +00:00
used_quota_size :
type : integer
format : int64
used_quota_files :
type : integer
format : int32
last_quota_update :
type : integer
format : int64
description : Last quota update as unix timestamp in milliseconds
users :
type : array
items :
type : string
description : list of usernames associated with this virtual folder
2021-03-21 18:15:47 +00:00
filesystem :
$ref : '#/components/schemas/FilesystemConfig'
2021-09-25 10:20:31 +00:00
description : 'Defines the filesystem for the virtual folder and the used quota limits. The same folder can be shared among multiple users and each user can have different quota limits or a different virtual path.'
2020-06-07 21:30:18 +00:00
VirtualFolder :
allOf :
- $ref : '#/components/schemas/BaseVirtualFolder'
- type : object
properties :
virtual_path :
type : string
quota_size :
type : integer
format : int64
2022-05-05 16:26:22 +00:00
description : 'Quota as size in bytes. 0 means unlimited, -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed'
2020-06-07 21:30:18 +00:00
quota_files :
type : integer
format : int32
2022-05-05 16:26:22 +00:00
description : 'Quota as number of files. 0 means unlimited, , -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed'
2020-06-07 21:30:18 +00:00
required :
- virtual_path
2021-03-06 16:08:24 +00:00
description : 'A virtual folder is a mapping between a SFTPGo virtual path and a filesystem path outside the user home directory. The specified paths must be absolute and the virtual path cannot be "/", it must be a sub directory. The parent directory for the specified virtual path must exist. SFTPGo will try to automatically create any missing parent directory for the configured virtual folders at user login.'
2019-07-20 10:26:52 +00:00
User :
type : object
properties :
id :
type : integer
format : int32
minimum : 1
2019-11-13 10:36:21 +00:00
status :
type : integer
enum :
- 0
- 1
2021-03-06 16:08:24 +00:00
description : |
2019-11-13 10:36:21 +00:00
status :
* `0` user is disabled, login is not allowed
* `1` user is enabled
2019-07-20 10:26:52 +00:00
username :
type : string
2020-06-07 21:30:18 +00:00
description : username is unique
2021-09-25 17:06:13 +00:00
email :
type : string
format : email
2021-02-24 18:40:29 +00:00
description :
type : string
2021-03-06 16:08:24 +00:00
description : 'optional description, for example the user full name'
2019-11-13 10:36:21 +00:00
expiration_date :
type : integer
format : int64
description : expiration date as unix timestamp in milliseconds. An expired account cannot login. 0 means no expiration
2019-07-20 10:26:52 +00:00
password :
type : string
2021-01-17 21:29:08 +00:00
format : password
2023-04-06 16:22:09 +00:00
description : If the password has no known hashing algo prefix it will be stored, by default, using bcrypt, argon2id is supported too. You can send a password hashed as bcrypt ($2a$ prefix), argon2id, pbkdf2 or unix crypt and it will be stored as is. For security reasons this field is omitted when you search/get users
2019-08-07 21:41:10 +00:00
public_keys :
2019-08-01 20:42:46 +00:00
type : array
items :
type : string
2021-06-05 14:07:09 +00:00
example : ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEUWwDwEWhTbF0MqAsp/oXK1HR2cElhM8oo1uVmL3ZeDKDiTm4ljMr92wfTgIGDqIoxmVqgYIkAOAhuykAVWBzc= user@host
2023-04-06 16:22:09 +00:00
description : Public keys in OpenSSH format.
has_password :
type : boolean
description : Indicates whether the password is set
2019-07-20 10:26:52 +00:00
home_dir :
type : string
description : path to the user home directory. The user cannot upload or download files outside this directory. SFTPGo tries to automatically create this folder if missing. Must be an absolute path
2020-02-23 10:30:26 +00:00
virtual_folders :
type : array
items :
$ref : '#/components/schemas/VirtualFolder'
2023-07-23 16:48:49 +00:00
description : mapping between virtual SFTPGo paths and virtual folders
2019-07-20 10:26:52 +00:00
uid :
type : integer
format : int32
minimum : 0
2021-03-25 16:11:42 +00:00
maximum : 2147483647
2021-03-06 16:08:24 +00:00
description : 'if you run SFTPGo as root user, the created files and directories will be assigned to this uid. 0 means no change, the owner will be the user that runs SFTPGo. Ignored on windows'
2019-07-20 10:26:52 +00:00
gid :
type : integer
format : int32
minimum : 0
2021-03-25 16:11:42 +00:00
maximum : 2147483647
2021-03-06 16:08:24 +00:00
description : 'if you run SFTPGo as root user, the created files and directories will be assigned to this gid. 0 means no change, the group will be the one of the user that runs SFTPGo. Ignored on windows'
2019-07-20 10:26:52 +00:00
max_sessions :
type : integer
format : int32
2020-03-27 22:26:22 +00:00
description : Limit the sessions that a user can open. 0 means unlimited
2019-07-20 10:26:52 +00:00
quota_size :
type : integer
format : int64
2022-05-05 16:26:22 +00:00
description : Quota as size in bytes. 0 means unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed
2019-07-20 10:26:52 +00:00
quota_files :
type : integer
format : int32
2022-05-05 16:26:22 +00:00
description : Quota as number of files. 0 means unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed
2019-07-20 10:26:52 +00:00
permissions :
2019-12-25 17:20:19 +00:00
type : object
2022-06-11 17:07:05 +00:00
additionalProperties :
type : array
items :
$ref : '#/components/schemas/Permission'
minItems : 1
minProperties : 1
description : 'hash map with directory as key and an array of permissions as value. Directories must be absolute paths, permissions for root directory ("/") are required'
2021-03-06 16:08:24 +00:00
example :
/ :
- '*'
/somedir :
- list
- download
2019-07-20 10:26:52 +00:00
used_quota_size :
type : integer
format : int64
2020-06-07 21:30:18 +00:00
used_quota_files :
2019-07-20 10:26:52 +00:00
type : integer
format : int32
2019-07-28 17:29:32 +00:00
last_quota_update :
2019-07-20 10:26:52 +00:00
type : integer
format : int64
2019-12-30 17:37:50 +00:00
description : Last quota update as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
upload_bandwidth :
type : integer
2021-03-06 16:08:24 +00:00
description : 'Maximum upload bandwidth as KB/s, 0 means unlimited'
2019-07-20 10:26:52 +00:00
download_bandwidth :
type : integer
2021-03-06 16:08:24 +00:00
description : 'Maximum download bandwidth as KB/s, 0 means unlimited'
2022-01-30 10:42:36 +00:00
upload_data_transfer :
type : integer
description : 'Maximum data transfer allowed for uploads as MB. 0 means no limit'
download_data_transfer :
type : integer
description : 'Maximum data transfer allowed for downloads as MB. 0 means no limit'
total_data_transfer :
type : integer
description : 'Maximum total data transfer as MB. 0 means unlimited. You can set a total data transfer instead of the individual values for uploads and downloads'
used_upload_data_transfer :
type : integer
description : 'Uploaded size, as bytes, since the last reset'
used_download_data_transfer :
type : integer
description : 'Downloaded size, as bytes, since the last reset'
2021-08-19 13:51:43 +00:00
created_at :
type : integer
format : int64
description : 'creation time as unix timestamp in milliseconds. It will be 0 for users created before v2.2.0'
updated_at :
type : integer
format : int64
description : last update time as unix timestamp in milliseconds
2019-11-13 10:36:21 +00:00
last_login :
type : integer
format : int64
2020-11-30 20:46:34 +00:00
description : Last user login as unix timestamp in milliseconds. It is saved at most once every 10 minutes
2022-08-21 17:01:08 +00:00
first_download :
type : integer
format : int64
description : first download time as unix timestamp in milliseconds
first_upload :
type : integer
format : int64
description : first upload time as unix timestamp in milliseconds
2022-12-11 16:53:41 +00:00
last_password_change :
type : integer
format : int64
description : last password change time as unix timestamp in milliseconds
2019-12-30 17:37:50 +00:00
filters :
$ref : '#/components/schemas/UserFilters'
2020-01-19 06:41:05 +00:00
filesystem :
$ref : '#/components/schemas/FilesystemConfig'
2020-11-25 21:26:34 +00:00
additional_info :
type : string
description : Free form text field for external systems
2022-04-25 13:49:11 +00:00
groups :
type : array
items :
$ref : '#/components/schemas/GroupMapping'
2022-04-12 17:31:25 +00:00
oidc_custom_fields :
type : object
additionalProperties : true
description : 'This field is passed to the pre-login hook if custom OIDC token fields have been configured. Field values can be of any type (this is a free form object) and depend on the type of the configured OIDC token fields'
2022-11-16 18:04:50 +00:00
role :
type : string
2022-09-21 17:36:08 +00:00
AdminPreferences :
type : object
properties :
hide_user_page_sections :
type : integer
description : 'Allow to hide some sections from the user page. These are not security settings and are not enforced server side in any way. They are only intended to simplify the user page in the WebAdmin UI. 1 means hide groups section, 2 means hide filesystem section, "users_base_dir" must be set in the config file otherwise this setting is ignored, 4 means hide virtual folders section, 8 means hide profile section, 16 means hide ACLs section, 32 means hide disk and bandwidth quota limits section, 64 means hide advanced settings section. The settings can be combined'
2022-11-05 17:01:24 +00:00
default_users_expiration :
type : integer
description : 'Defines the default expiration for newly created users as number of days. 0 means no expiration'
2021-01-17 21:29:08 +00:00
AdminFilters :
type : object
properties :
allow_list :
type : array
items :
type : string
2021-03-06 16:08:24 +00:00
description : 'only clients connecting from these IP/Mask are allowed. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32"'
example :
- 192.0 .2 .0 /24
- '2001:db8::/32'
2021-08-17 16:08:32 +00:00
allow_api_key_auth :
type : boolean
description : 'API key auth allows to impersonate this administrator with an API key'
2024-02-21 19:45:10 +00:00
require_two_factor :
type : boolean
require_password_change :
type : boolean
2021-09-04 10:11:04 +00:00
totp_config :
$ref : '#/components/schemas/AdminTOTPConfig'
recovery_codes :
type : array
items :
$ref : '#/components/schemas/RecoveryCode'
2022-09-21 17:36:08 +00:00
preferences :
$ref : '#/components/schemas/AdminPreferences'
2021-01-17 21:29:08 +00:00
Admin :
type : object
properties :
id :
type : integer
format : int32
minimum : 1
status :
type : integer
enum :
- 0
- 1
2021-03-06 16:08:24 +00:00
description : |
2021-01-17 21:29:08 +00:00
status :
* `0` user is disabled, login is not allowed
* `1` user is enabled
username :
type : string
description : username is unique
2021-02-24 18:40:29 +00:00
description :
type : string
2021-03-06 16:08:24 +00:00
description : 'optional description, for example the admin full name'
2021-01-17 21:29:08 +00:00
password :
type : string
format : password
description : Admin password. For security reasons this field is omitted when you search/get admins
email :
type : string
format : email
permissions :
type : array
items :
$ref : '#/components/schemas/AdminPermissions'
filters :
$ref : '#/components/schemas/AdminFilters'
additional_info :
type : string
description : Free form text field
2022-09-13 16:04:27 +00:00
groups :
type : array
items :
$ref : '#/components/schemas/AdminGroupMapping'
description : 'Groups automatically selected for new users created by this admin. The admin will still be able to choose different groups. These settings are only used for this admin UI and they will be ignored in REST API/hooks.'
2021-08-19 13:51:43 +00:00
created_at :
type : integer
format : int64
description : 'creation time as unix timestamp in milliseconds. It will be 0 for admins created before v2.2.0'
updated_at :
type : integer
format : int64
description : last update time as unix timestamp in milliseconds
last_login :
type : integer
format : int64
description : Last user login as unix timestamp in milliseconds. It is saved at most once every 10 minutes
2022-11-16 18:04:50 +00:00
role :
type : string
2024-11-10 09:35:23 +00:00
description : 'If set the admin can only administer users with the same role. Role admins cannot have the "*" permission'
2021-09-29 16:46:15 +00:00
AdminProfile :
type : object
properties :
email :
type : string
format : email
description :
type : string
allow_api_key_auth :
type : boolean
description : 'If enabled, you can impersonate this admin, in REST API, using an API key. If disabled admin credentials are required for impersonation'
UserProfile :
type : object
properties :
email :
type : string
format : email
description :
type : string
allow_api_key_auth :
type : boolean
description : 'If enabled, you can impersonate this user, in REST API, using an API key. If disabled user credentials are required for impersonation'
public_keys :
type : array
items :
type : string
example : ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEUWwDwEWhTbF0MqAsp/oXK1HR2cElhM8oo1uVmL3ZeDKDiTm4ljMr92wfTgIGDqIoxmVqgYIkAOAhuykAVWBzc= user@host
description : Public keys in OpenSSH format
2021-08-17 16:08:32 +00:00
APIKey :
type : object
properties :
id :
type : string
description : unique key identifier
name :
type : string
description : User friendly key name
key :
type : string
format : password
description : We store the hash of the key. This is just like a password. For security reasons this field is omitted when you search/get API keys
scope :
$ref : '#/components/schemas/APIKeyScope'
created_at :
type : integer
format : int64
description : creation time as unix timestamp in milliseconds
updated_at :
type : integer
format : int64
description : last update time as unix timestamp in milliseconds
last_use_at :
type : integer
format : int64
description : last use time as unix timestamp in milliseconds. It is saved at most once every 10 minutes
expires_at :
type : integer
format : int64
description : expiration time as unix timestamp in milliseconds
description :
type : string
description : optional description
user :
type : string
description : username associated with this API key. If empty and the scope is "user scope" the key can impersonate any user
admin :
type : string
description : admin associated with this API key. If empty and the scope is "admin scope" the key can impersonate any admin
2021-06-07 19:52:43 +00:00
QuotaUsage :
type : object
properties :
used_quota_size :
type : integer
format : int64
used_quota_files :
type : integer
format : int32
2022-01-30 10:42:36 +00:00
TransferQuotaUsage :
type : object
properties :
used_upload_data_transfer :
type : integer
format : int64
description : 'The value must be specified as bytes'
used_download_data_transfer :
type : integer
format : int64
description : 'The value must be specified as bytes'
2019-08-24 12:41:15 +00:00
Transfer :
2019-07-20 10:26:52 +00:00
type : object
properties :
operation_type :
type : string
2019-11-13 10:36:21 +00:00
enum :
2019-07-20 10:26:52 +00:00
- upload
- download
2021-03-21 18:15:47 +00:00
description : |
Operations :
* `upload`
* `download`
2019-08-08 17:33:16 +00:00
path :
type : string
2019-11-18 22:30:37 +00:00
description : file path for the upload/download
2019-07-20 10:26:52 +00:00
start_time :
type : integer
format : int64
2019-07-28 17:29:32 +00:00
description : start time as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
size :
type : integer
format : int64
description : bytes transferred
ConnectionStatus :
type : object
properties :
username :
type : string
description : connected username
connection_id :
type : string
2019-08-24 12:41:15 +00:00
description : unique connection identifier
2019-07-20 10:26:52 +00:00
client_version :
type : string
2019-11-18 22:30:37 +00:00
description : client version
2019-07-20 10:26:52 +00:00
remote_address :
type : string
2019-11-18 22:30:37 +00:00
description : Remote address for the connected client
2019-07-20 10:26:52 +00:00
connection_time :
type : integer
format : int64
2019-07-28 17:29:32 +00:00
description : connection time as unix timestamp in milliseconds
2020-08-11 21:56:10 +00:00
command :
2019-11-18 22:30:37 +00:00
type : string
2021-01-18 12:24:38 +00:00
description : Last SSH/FTP command or WebDAV method
2019-07-20 10:26:52 +00:00
last_activity :
type : integer
format : int64
2019-07-28 17:29:32 +00:00
description : last client activity as unix timestamp in milliseconds
2019-08-24 12:41:15 +00:00
protocol :
type : string
enum :
- SFTP
- SCP
2019-11-18 22:30:37 +00:00
- SSH
2020-08-11 21:56:10 +00:00
- FTP
- DAV
2019-07-20 10:26:52 +00:00
active_transfers :
type : array
items :
2021-03-06 16:08:24 +00:00
$ref : '#/components/schemas/Transfer'
2022-09-25 17:48:55 +00:00
node :
type : string
description : 'Node identifier, omitted for single node installations'
2021-09-25 10:20:31 +00:00
FolderRetention :
type : object
properties :
path :
type : string
2023-02-09 08:33:33 +00:00
description : 'virtual directory path as seen by users, if no other specific retention is defined, the retention applies for sub directories too. For example if retention is defined for the paths "/" and "/sub" then the retention for "/" is applied for any file outside the "/sub" directory'
2021-09-25 10:20:31 +00:00
example : '/'
retention :
type : integer
description : retention time in hours. All the files with a modification time older than the defined value will be deleted. 0 means exclude this path
example : 24
delete_empty_dirs :
type : boolean
description : if enabled, empty directories will be deleted
ignore_user_permissions :
type : boolean
description : 'if enabled, files will be deleted even if the user does not have the delete permission. The default is "false" which means that files will be skipped if the user does not have permission to delete them. File patterns filters will always be silently ignored'
RetentionCheck :
type : object
properties :
username :
type : string
description : username to which the retention check refers
folders :
type : array
items :
$ref : '#/components/schemas/FolderRetention'
start_time :
type : integer
format : int64
description : check start time as unix timestamp in milliseconds
2021-10-03 13:17:49 +00:00
notifications :
type : array
items :
$ref : '#/components/schemas/RetentionCheckNotification'
2021-10-02 20:25:41 +00:00
email :
type : string
format : email
description : 'if the notification method is set to "Email", this is the e-mail address that receives the retention check report. This field is automatically set to the email address associated with the administrator starting the check'
2019-07-20 10:26:52 +00:00
QuotaScan :
type : object
properties :
username :
type : string
2021-09-25 10:20:31 +00:00
description : username to which the quota scan refers
2019-07-20 10:26:52 +00:00
start_time :
type : integer
format : int64
2019-07-28 17:29:32 +00:00
description : scan start time as unix timestamp in milliseconds
2020-06-07 21:30:18 +00:00
FolderQuotaScan :
type : object
properties :
2021-03-21 18:15:47 +00:00
name :
2020-06-07 21:30:18 +00:00
type : string
2021-09-25 10:20:31 +00:00
description : folder name to which the quota scan refers
2020-06-07 21:30:18 +00:00
start_time :
type : integer
format : int64
description : scan start time as unix timestamp in milliseconds
2021-06-07 19:52:43 +00:00
DefenderEntry :
type : object
properties :
id :
type : string
ip :
type : string
score :
type : integer
description : the score increases whenever a violation is detected, such as an attempt to log in using an incorrect password or invalid username. If the score exceeds the configured threshold, the IP is banned. Omitted for banned IPs
ban_time :
type : string
format : date-time
description : date time until the IP is banned. For already banned hosts, the ban time is increased each time a new violation is detected. Omitted if the IP is not banned
2020-12-08 10:18:34 +00:00
SSHHostKey :
type : object
properties :
path :
type : string
fingerprint :
type : string
2023-10-07 14:07:19 +00:00
algorithms :
type : array
items :
type : string
2020-12-23 15:12:30 +00:00
SSHBinding :
2020-12-08 10:18:34 +00:00
type : object
properties :
2020-12-23 15:12:30 +00:00
address :
type : string
description : TCP address the server listen on
port :
type : integer
description : the port used for serving requests
apply_proxy_config :
type : boolean
2021-03-06 16:08:24 +00:00
description : 'apply the proxy configuration, if any'
2020-12-23 15:12:30 +00:00
WebDAVBinding :
type : object
properties :
address :
type : string
description : TCP address the server listen on
port :
type : integer
description : the port used for serving requests
enable_https :
2020-12-08 10:18:34 +00:00
type : boolean
2022-02-26 15:43:29 +00:00
min_tls_version :
$ref : '#/components/schemas/TLSVersions'
2020-12-29 18:33:04 +00:00
client_auth_type :
type : integer
description : 1 means that client certificate authentication is required in addition to HTTP basic authentication
2022-02-26 15:43:29 +00:00
tls_cipher_suites :
type : array
items :
type : string
description : 'List of supported cipher suites for TLS version 1.2. If empty a default list of secure cipher suites is used, with a preference order based on hardware performance'
prefix :
type : string
description : 'Prefix for WebDAV resources, if empty WebDAV resources will be available at the `/` URI'
proxy_allowed :
type : array
items :
type : string
description : 'List of IP addresses and IP ranges allowed to set proxy headers'
PassiveIPOverride :
type : object
properties :
networks :
type : array
items :
type : string
ip :
type : string
2020-12-23 15:12:30 +00:00
FTPDBinding :
type : object
properties :
2020-12-08 10:18:34 +00:00
address :
type : string
2020-12-23 15:12:30 +00:00
description : TCP address the server listen on
port :
type : integer
description : the port used for serving requests
apply_proxy_config :
type : boolean
2021-03-06 16:08:24 +00:00
description : 'apply the proxy configuration, if any'
2020-12-23 15:12:30 +00:00
tls_mode :
type : integer
enum :
- 0
- 1
- 2
2021-03-06 16:08:24 +00:00
description : |
2021-12-04 14:14:44 +00:00
TLS mode :
* `0` - clear or explicit TLS
* `1` - explicit TLS required
* `2` - implicit TLS
2022-02-26 15:43:29 +00:00
min_tls_version :
$ref : '#/components/schemas/TLSVersions'
2020-12-23 15:12:30 +00:00
force_passive_ip :
type : string
2023-02-09 08:33:33 +00:00
description : External IP address for passive connections
2022-02-26 15:43:29 +00:00
passive_ip_overrides :
type : array
items :
$ref : '#/components/schemas/PassiveIPOverride'
2020-12-29 18:33:04 +00:00
client_auth_type :
type : integer
description : 1 means that client certificate authentication is required in addition to FTP authentication
2022-02-26 15:43:29 +00:00
tls_cipher_suites :
type : array
items :
type : string
description : 'List of supported cipher suites for TLS version 1.2. If empty a default list of secure cipher suites is used, with a preference order based on hardware performance'
passive_connections_security :
type : integer
enum :
- 0
- 1
description : |
Active connections security :
* `0` - require matching peer IP addresses of control and data connection
* `1` - disable any checks
active_connections_security :
type : integer
enum :
- 0
- 1
description : |
Active connections security :
* `0` - require matching peer IP addresses of control and data connection
* `1` - disable any checks
2024-05-02 17:00:29 +00:00
ignore_ascii_transfer_type :
type : integer
enum :
- 0
- 1
description : |
Ignore client requests to perform ASCII translations :
* `0` - ASCII translations are enabled
* `1` - ASCII translations are silently ignored
2022-02-26 15:43:29 +00:00
debug :
type : boolean
description : 'If enabled any FTP command will be logged'
2020-12-08 10:18:34 +00:00
SSHServiceStatus :
2020-12-23 15:12:30 +00:00
type : object
properties :
is_active :
type : boolean
bindings :
type : array
items :
$ref : '#/components/schemas/SSHBinding'
2021-01-18 12:24:38 +00:00
nullable : true
2020-12-23 15:12:30 +00:00
host_keys :
type : array
items :
$ref : '#/components/schemas/SSHHostKey'
2021-01-18 12:24:38 +00:00
nullable : true
2020-12-23 15:12:30 +00:00
ssh_commands :
2021-01-18 12:24:38 +00:00
type : array
items :
type : string
2022-02-26 15:43:29 +00:00
authentications :
type : array
items :
$ref : '#/components/schemas/SSHAuthentications'
2023-11-09 19:03:04 +00:00
public_key_algorithms :
type : array
items :
type : string
2023-02-19 18:03:45 +00:00
macs :
type : array
items :
type : string
kex_algorithms :
type : array
items :
type : string
ciphers :
type : array
items :
type : string
2020-12-08 10:18:34 +00:00
FTPPassivePortRange :
type : object
properties :
start :
type : integer
end :
type : integer
FTPServiceStatus :
2020-12-23 15:12:30 +00:00
type : object
properties :
is_active :
type : boolean
bindings :
type : array
items :
$ref : '#/components/schemas/FTPDBinding'
2021-01-18 12:24:38 +00:00
nullable : true
2020-12-23 15:12:30 +00:00
passive_port_range :
$ref : '#/components/schemas/FTPPassivePortRange'
2020-12-08 10:18:34 +00:00
WebDAVServiceStatus :
2020-12-23 15:12:30 +00:00
type : object
properties :
is_active :
type : boolean
bindings :
type : array
items :
$ref : '#/components/schemas/WebDAVBinding'
2021-01-18 12:24:38 +00:00
nullable : true
2020-12-08 10:18:34 +00:00
DataProviderStatus :
type : object
properties :
is_active :
type : boolean
driver :
type : string
error :
type : string
2021-09-04 10:11:04 +00:00
MFAStatus :
type : object
properties :
is_active :
type : boolean
totp_configs :
type : array
items :
$ref : '#/components/schemas/TOTPConfig'
2020-12-08 10:18:34 +00:00
ServicesStatus :
type : object
properties :
ssh :
$ref : '#/components/schemas/SSHServiceStatus'
ftp :
$ref : '#/components/schemas/FTPServiceStatus'
webdav :
$ref : '#/components/schemas/WebDAVServiceStatus'
data_provider :
$ref : '#/components/schemas/DataProviderStatus'
2021-01-02 18:33:24 +00:00
defender :
type : object
properties :
is_active :
type : boolean
2021-09-04 10:11:04 +00:00
mfa :
$ref : '#/components/schemas/MFAStatus'
2023-02-09 08:33:33 +00:00
allow_list :
type : object
properties :
is_active :
type : boolean
rate_limiters :
type : object
properties :
is_active :
type : boolean
protocols :
type : array
items :
type : string
example : SSH
2021-11-06 13:13:20 +00:00
Share :
type : object
properties :
id :
type : string
description : auto-generated unique share identifier
name :
type : string
description :
type : string
description : optional description
scope :
$ref : '#/components/schemas/ShareScope'
paths :
type : array
items :
type : string
description : 'paths to files or directories, for share scope write this array must contain exactly one directory. Paths will not be validated on save so you can also create them after creating the share'
example :
- '/dir1'
- '/dir2/file.txt'
- '/dir3/subdir'
username :
type : string
created_at :
type : integer
format : int64
description : 'creation time as unix timestamp in milliseconds'
updated_at :
type : integer
format : int64
description : 'last update time as unix timestamp in milliseconds'
last_use_at :
type : integer
format : int64
description : last use time as unix timestamp in milliseconds
expires_at :
type : integer
format : int64
description : 'optional share expiration, as unix timestamp in milliseconds. 0 means no expiration'
password :
type : string
description : 'optional password to protect the share. The special value "[**redacted**]" means that a password has been set, you can use this value if you want to preserve the current password when you update a share'
max_tokens :
type : integer
description : 'maximum allowed access tokens. 0 means no limit'
used_tokens :
type : integer
allow_from :
type : array
items :
type : string
description : 'Limit the share availability to these IP/Mask. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32". An empty list means no restrictions'
example :
- 192.0 .2 .0 /24
- '2001:db8::/32'
2022-04-25 13:49:11 +00:00
GroupUserSettings :
type : object
properties :
home_dir :
type : string
max_sessions :
type : integer
format : int32
quota_size :
type : integer
format : int64
quota_files :
type : integer
format : int32
permissions :
type : object
2022-06-11 17:07:05 +00:00
additionalProperties :
type : array
items :
$ref : '#/components/schemas/Permission'
minItems : 1
minProperties : 1
description : 'hash map with directory as key and an array of permissions as value. Directories must be absolute paths, permissions for root directory ("/") are required'
2022-04-25 13:49:11 +00:00
example :
/ :
- '*'
/somedir :
- list
- download
upload_bandwidth :
type : integer
description : 'Maximum upload bandwidth as KB/s'
download_bandwidth :
type : integer
description : 'Maximum download bandwidth as KB/s'
upload_data_transfer :
type : integer
description : 'Maximum data transfer allowed for uploads as MB'
download_data_transfer :
type : integer
description : 'Maximum data transfer allowed for downloads as MB'
total_data_transfer :
type : integer
description : 'Maximum total data transfer as MB'
2023-02-13 18:32:36 +00:00
expires_in :
type : integer
description : 'Account expiration in number of days from creation. 0 means no expiration'
2022-04-25 13:49:11 +00:00
filters :
$ref : '#/components/schemas/BaseUserFilters'
2023-01-15 14:05:01 +00:00
filesystem :
$ref : '#/components/schemas/FilesystemConfig'
2022-11-16 18:04:50 +00:00
Role :
type : object
properties :
id :
type : integer
format : int32
minimum : 1
name :
type : string
description : name is unique
description :
type : string
description : 'optional description'
created_at :
type : integer
format : int64
description : creation time as unix timestamp in milliseconds
updated_at :
type : integer
format : int64
description : last update time as unix timestamp in milliseconds
users :
type : array
items :
type : string
description : list of usernames associated with this group
admins :
type : array
items :
type : string
description : list of admins usernames associated with this group
2022-04-25 13:49:11 +00:00
Group :
type : object
properties :
id :
type : integer
format : int32
minimum : 1
name :
type : string
description : name is unique
description :
type : string
description : 'optional description'
created_at :
type : integer
format : int64
description : creation time as unix timestamp in milliseconds
updated_at :
type : integer
format : int64
description : last update time as unix timestamp in milliseconds
user_settings :
$ref : '#/components/schemas/GroupUserSettings'
virtual_folders :
type : array
items :
$ref : '#/components/schemas/VirtualFolder'
description : mapping between virtual SFTPGo paths and folders
users :
type : array
items :
type : string
description : list of usernames associated with this group
2022-09-13 16:04:27 +00:00
admins :
type : array
items :
type : string
description : list of admins usernames associated with this group
2022-04-25 13:49:11 +00:00
GroupMapping :
type : object
properties :
name :
type : string
description : group name
type :
enum :
- 1
- 2
2022-09-13 16:04:27 +00:00
- 3
2022-04-25 13:49:11 +00:00
description : |
Group type :
* `1` - Primary group
2022-09-13 16:04:27 +00:00
* `2` - Secondary group
* `3` - Membership only, no settings are inherited from this group type
AdminGroupMappingOptions :
type : object
properties :
add_to_users_as :
enum :
- 0
- 1
- 2
description : |
Add to new users as :
* `0` - the admin's group will be added as membership group for new users
* `1` - the admin's group will be added as primary group for new users
* `2` - the admin's group will be added as secondary group for new users
AdminGroupMapping :
type : object
properties :
name :
type : string
description : group name
options :
$ref : '#/components/schemas/AdminGroupMappingOptions'
2021-01-22 18:42:18 +00:00
BackupData :
type : object
properties :
users :
type : array
items :
$ref : '#/components/schemas/User'
folders :
type : array
items :
$ref : '#/components/schemas/BaseVirtualFolder'
2022-04-25 13:49:11 +00:00
groups :
type : array
items :
$ref : '#/components/schemas/Group'
2021-01-22 18:42:18 +00:00
admins :
type : array
items :
$ref : '#/components/schemas/Admin'
2021-08-17 16:08:32 +00:00
api_keys :
2021-11-06 13:13:20 +00:00
type : array
items :
$ref : '#/components/schemas/APIKey'
shares :
type : array
items :
$ref : '#/components/schemas/Share'
2022-11-16 18:04:50 +00:00
event_actions :
type : array
items :
$ref : '#/components/schemas/EventAction'
event_rules :
type : array
items :
$ref : '#/components/schemas/EventRule'
roles :
type : array
items :
$ref : '#/components/schemas/Role'
2021-01-22 18:42:18 +00:00
version :
type : integer
2021-01-17 21:29:08 +00:00
PwdChange :
type : object
properties :
current_password :
type : string
new_password :
type : string
2021-06-05 14:07:09 +00:00
DirEntry :
type : object
properties :
name :
type : string
description : name of the file (or subdirectory) described by the entry. This name is the final element of the path (the base name), not the entire path
size :
type : integer
format : int64
description : file size, omitted for folders and non regular files
mode :
type : integer
description : |
File mode and permission bits. More details here : https://golang.org/pkg/io/fs/#FileMode.
Let's see some examples :
- for a directory mode&2147483648 != 0
- for a symlink mode&134217728 != 0
- for a regular file mode&2401763328 == 0
last_modified :
type : string
format : date-time
2021-10-20 17:39:49 +00:00
FsEvent :
type : object
properties :
id :
type : string
timestamp :
type : integer
format : int64
description : 'unix timestamp in nanoseconds'
action :
$ref : '#/components/schemas/FsEventAction'
username :
type : string
fs_path :
type : string
fs_target_path :
type : string
virtual_path :
type : string
virtual_target_path :
type : string
ssh_cmd :
type : string
file_size :
type : integer
format : int64
2023-02-13 11:58:21 +00:00
elapsed :
type : integer
format : int64
description : elapsed time as milliseconds
2021-10-20 17:39:49 +00:00
status :
$ref : '#/components/schemas/FsEventStatus'
protocol :
$ref : '#/components/schemas/EventProtocols'
ip :
type : string
2021-12-04 16:57:48 +00:00
session_id :
type : string
2022-01-03 16:02:52 +00:00
fs_provider :
$ref : '#/components/schemas/FsProviders'
bucket :
type : string
endpoint :
type : string
open_flags :
type : string
2023-05-12 16:34:59 +00:00
role :
type : string
2021-10-20 17:39:49 +00:00
instance_id :
type : string
ProviderEvent :
type : object
properties :
id :
type : string
timestamp :
type : integer
format : int64
description : 'unix timestamp in nanoseconds'
action :
$ref : '#/components/schemas/ProviderEventAction'
username :
type : string
ip :
type : string
object_type :
$ref : '#/components/schemas/ProviderEventObjectType'
object_name :
type : string
2022-12-08 09:02:12 +00:00
object_data :
2022-12-11 16:53:41 +00:00
type : string
format : byte
2022-12-08 09:02:12 +00:00
description : 'base64 of the JSON serialized object with sensitive fields removed'
2023-05-12 16:34:59 +00:00
role :
type : string
instance_id :
type : string
LogEvent :
type : object
properties :
id :
type : string
timestamp :
type : integer
format : int64
description : 'unix timestamp in nanoseconds'
event :
$ref : '#/components/schemas/LogEventType'
protocol :
$ref : '#/components/schemas/EventProtocols'
username :
type : string
ip :
type : string
message :
type : string
role :
type : string
2021-10-20 17:39:49 +00:00
instance_id :
type : string
2022-07-11 06:17:36 +00:00
KeyValue :
type : object
properties :
key :
type : string
value :
type : string
2024-08-09 18:18:33 +00:00
RenameConfig :
allOf :
- $ref : '#/components/schemas/KeyValue'
- type : object
properties :
update_modtime :
type : boolean
description : 'Update modification time. This setting is not recursive and only applies to storage providers that support changing modification times'
2022-09-03 14:29:07 +00:00
HTTPPart :
type : object
properties :
name :
type : string
headers :
type : array
items :
$ref : '#/components/schemas/KeyValue'
description : 'Additional headers. Content-Disposition header is automatically set. Content-Type header is automatically detect for files to attach'
filepath :
type : string
description : 'path to the file to be sent as an attachment'
body :
type : string
2022-07-11 06:17:36 +00:00
EventActionHTTPConfig :
type : object
properties :
endpoint :
type : string
description : HTTP endpoint
example : https://example.com
username :
type : string
password :
$ref : '#/components/schemas/Secret'
headers :
type : array
items :
$ref : '#/components/schemas/KeyValue'
description : headers to add
timeout :
type : integer
minimum : 1
2022-09-06 17:09:23 +00:00
maximum : 180
2022-09-03 14:29:07 +00:00
description : 'Ignored for multipart requests with files as attachments'
2022-07-11 06:17:36 +00:00
skip_tls_verify :
type : boolean
description : 'if enabled the HTTP client accepts any TLS certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing.'
method :
type : string
enum :
- GET
- POST
- PUT
2023-08-10 17:02:55 +00:00
- DELETE
2022-07-11 06:17:36 +00:00
query_parameters :
type : array
items :
$ref : '#/components/schemas/KeyValue'
body :
type : string
description : HTTP POST/PUT body
2022-09-03 14:29:07 +00:00
parts :
type : array
items :
$ref : '#/components/schemas/HTTPPart'
description : 'Multipart requests allow to combine one or more sets of data into a single body. For each part, you can set a file path or a body as text. Placeholders are supported in file path, body, header values.'
2022-07-11 06:17:36 +00:00
EventActionCommandConfig :
type : object
properties :
cmd :
type : string
description : absolute path to the command to execute
2022-08-30 10:37:18 +00:00
args :
type : array
items :
type : string
description : 'command line arguments'
2022-07-11 06:17:36 +00:00
timeout :
type : integer
minimum : 1
maximum : 120
env_vars :
type : array
items :
$ref : '#/components/schemas/KeyValue'
EventActionEmailConfig :
type : object
properties :
recipients :
type : array
items :
type : string
2023-05-25 17:55:27 +00:00
bcc :
type : array
items :
type : string
2022-07-11 06:17:36 +00:00
subject :
type : string
body :
type : string
2023-05-17 17:28:13 +00:00
content_type :
type : integer
enum :
- 0
- 1
description : |
Content type :
* `0` text/plain
* `1` text/html
2022-08-22 17:04:17 +00:00
attachments :
type : array
items :
type : string
description : 'list of file paths to attach. The total size is limited to 10 MB'
2022-08-04 19:50:38 +00:00
EventActionDataRetentionConfig :
type : object
properties :
folders :
type : array
items :
$ref : '#/components/schemas/FolderRetention'
2022-10-10 16:53:58 +00:00
EventActionFsCompress :
type : object
properties :
name :
type : string
description : 'Full path to the (zip) archive to create. The parent dir must exist'
paths :
type : array
items :
type : string
description : 'paths to add the archive'
2022-08-20 12:13:43 +00:00
EventActionFilesystemConfig :
type : object
properties :
type :
$ref : '#/components/schemas/FilesystemActionTypes'
renames :
type : array
items :
2024-08-09 18:18:33 +00:00
$ref : '#/components/schemas/RenameConfig'
2022-08-20 12:13:43 +00:00
mkdirs :
type : array
items :
type : string
deletes :
type : array
items :
type : string
exist :
type : array
items :
type : string
2022-12-27 17:51:53 +00:00
copy :
type : array
items :
$ref : '#/components/schemas/KeyValue'
2022-10-10 16:53:58 +00:00
compress :
$ref : '#/components/schemas/EventActionFsCompress'
2022-12-16 17:51:29 +00:00
EventActionPasswordExpiration :
type : object
properties :
threshold :
type : integer
description : 'An email notification will be generated for users whose password expires in a number of days less than or equal to this threshold'
2024-03-04 18:48:10 +00:00
EventActionUserInactivity :
type : object
properties :
disable_threshold :
type : integer
description : 'Inactivity threshold, in days, before disabling the account'
delete_threshold :
type : integer
description : 'Inactivity threshold, in days, before deleting the account'
2023-03-22 18:02:54 +00:00
EventActionIDPAccountCheck :
type : object
properties :
mode :
type : integer
enum :
- 0
- 1
description : |
Account check mode :
* `0` Create or update the account
* `1` Create the account if it doesn't exist
template_user :
type : string
description : 'SFTPGo user template in JSON format'
template_admin :
type : string
description : 'SFTPGo admin template in JSON format'
2022-07-11 06:17:36 +00:00
BaseEventActionOptions :
type : object
properties :
http_config :
$ref : '#/components/schemas/EventActionHTTPConfig'
cmd_config :
$ref : '#/components/schemas/EventActionCommandConfig'
email_config :
$ref : '#/components/schemas/EventActionEmailConfig'
2022-08-04 19:50:38 +00:00
retention_config :
$ref : '#/components/schemas/EventActionDataRetentionConfig'
2022-08-20 12:13:43 +00:00
fs_config :
$ref : '#/components/schemas/EventActionFilesystemConfig'
2022-12-16 17:51:29 +00:00
pwd_expiration_config :
$ref : '#/components/schemas/EventActionPasswordExpiration'
2024-03-04 18:48:10 +00:00
user_inactivity_config :
$ref : '#/components/schemas/EventActionUserInactivity'
2023-03-22 18:02:54 +00:00
idp_config :
$ref : '#/components/schemas/EventActionIDPAccountCheck'
2022-07-11 06:17:36 +00:00
BaseEventAction :
type : object
properties :
id :
type : integer
format : int32
minimum : 1
name :
type : string
description : unique name
description :
type : string
description : optional description
type :
$ref : '#/components/schemas/EventActionTypes'
options :
$ref : '#/components/schemas/BaseEventActionOptions'
rules :
type : array
items :
type : string
description : list of event rules names associated with this action
EventActionOptions :
type : object
properties :
is_failure_action :
type : boolean
stop_on_failure :
type : boolean
execute_sync :
type : boolean
EventAction :
allOf :
- $ref : '#/components/schemas/BaseEventAction'
- type : object
properties :
order :
type : integer
description : execution order
relation_options :
$ref : '#/components/schemas/EventActionOptions'
EventActionMinimal :
type : object
properties :
name :
type : string
order :
type : integer
description : execution order
relation_options :
$ref : '#/components/schemas/EventActionOptions'
ConditionPattern :
type : object
properties :
pattern :
type : string
inverse_match :
type : boolean
ConditionOptions :
type : object
properties :
names :
type : array
items :
$ref : '#/components/schemas/ConditionPattern'
2022-09-04 15:48:09 +00:00
group_names :
type : array
items :
$ref : '#/components/schemas/ConditionPattern'
2022-12-03 16:47:43 +00:00
role_names :
type : array
items :
$ref : '#/components/schemas/ConditionPattern'
2022-07-11 06:17:36 +00:00
fs_paths :
type : array
items :
$ref : '#/components/schemas/ConditionPattern'
protocols :
type : array
items :
type : string
enum :
- SFTP
- SCP
- SSH
- FTP
- DAV
- HTTP
- HTTPShare
- OIDC
provider_objects :
type : array
items :
type : string
enum :
- user
- group
- admin
- api_key
- share
- event_action
- event_rule
min_size :
type : integer
format : int64
max_size :
type : integer
format : int64
concurrent_execution :
type : boolean
description : allow concurrent execution from multiple nodes
Schedule :
type : object
properties :
hour :
type : string
day_of_week :
type : string
day_of_month :
type : string
month :
type : string
EventConditions :
type : object
properties :
fs_events :
type : array
items :
type : string
enum :
- upload
- download
- delete
- rename
- mkdir
- rmdir
2022-12-27 17:51:53 +00:00
- copy
2022-07-11 06:17:36 +00:00
- ssh_cmd
2023-01-03 09:18:30 +00:00
- pre-upload
- pre-download
- pre-delete
2023-03-22 18:02:54 +00:00
- first-upload
- first-download
2022-07-11 06:17:36 +00:00
provider_events :
type : array
items :
type : string
enum :
- add
- update
- delete
schedules :
type : array
items :
$ref : '#/components/schemas/Schedule'
2023-03-22 18:02:54 +00:00
idp_login_event :
type : integer
enum :
- 0
- 1
- 2
description : |
IDP login events :
- `0` any login event
- `1` user login event
- `2` admin login event
2022-07-11 06:17:36 +00:00
options :
$ref : '#/components/schemas/ConditionOptions'
BaseEventRule :
type : object
properties :
id :
type : integer
format : int32
minimum : 1
name :
type : string
description : unique name
2023-01-19 17:33:04 +00:00
status :
type : integer
enum :
- 0
- 1
description : |
status :
* `0` disabled
* `1` enabled
2022-07-11 06:17:36 +00:00
description :
type : string
description : optional description
created_at :
type : integer
format : int64
description : creation time as unix timestamp in milliseconds
updated_at :
type : integer
format : int64
description : last update time as unix timestamp in millisecond
trigger :
$ref : '#/components/schemas/EventTriggerTypes'
conditions :
$ref : '#/components/schemas/EventConditions'
EventRule :
allOf :
- $ref : '#/components/schemas/BaseEventRule'
- type : object
properties :
actions :
type : array
items :
$ref : '#/components/schemas/EventAction'
EventRuleMinimal :
allOf :
- $ref : '#/components/schemas/BaseEventRule'
- type : object
properties :
actions :
type : array
items :
$ref : '#/components/schemas/EventActionMinimal'
2023-02-09 08:33:33 +00:00
IPListEntry :
type : object
properties :
ipornet :
type : string
description : IP address or network in CIDR format, for example `192.168.1.2/32`, `192.168.0.0/24`, `2001:db8::/32`
description :
type : string
description : optional description
type :
$ref : '#/components/schemas/IPListType'
mode :
$ref : '#/components/schemas/IPListMode'
protocols :
type : integer
description : Defines the protocol the entry applies to. `0` means all the supported protocols, 1 SSH, 2 FTP, 4 WebDAV, 8 HTTP. Protocols can be combined, for example 3 means SSH and FTP
created_at :
type : integer
format : int64
description : creation time as unix timestamp in milliseconds
updated_at :
type : integer
format : int64
2023-02-13 11:58:21 +00:00
description : last update time as unix timestamp in millisecond
2019-07-20 10:26:52 +00:00
ApiResponse :
type : object
properties :
message :
type : string
2021-03-06 16:08:24 +00:00
description : 'message, can be empty'
2019-07-20 10:26:52 +00:00
error :
type : string
description : error description if any
2019-08-08 08:01:33 +00:00
VersionInfo :
type : object
properties :
version :
type : string
build_date :
type : string
commit_hash :
type : string
2020-05-23 09:58:05 +00:00
features :
type : array
items :
type : string
2023-03-26 08:33:30 +00:00
description : 'Features for the current build. Available features are `portable`, `bolt`, `mysql`, `sqlite`, `pgsql`, `s3`, `gcs`, `azblob`, `metrics`, `unixcrypt`. If a feature is available it has a `+` prefix, otherwise a `-` prefix'
2021-01-17 21:29:08 +00:00
Token :
type : object
properties :
access_token :
type : string
expires_at :
type : string
format : date-time
2020-02-03 23:08:00 +00:00
securitySchemes :
BasicAuth :
type : http
scheme : basic
2021-01-17 21:29:08 +00:00
BearerAuth :
type : http
scheme : bearer
bearerFormat : JWT
2021-08-17 16:08:32 +00:00
APIKeyAuth :
type : apiKey
in : header
name : X-SFTPGO-API-KEY
description : 'API key to use for authentication. API key authentication is intrinsically less secure than using a short lived JWT token. You should prefer API key authentication only for machine-to-machine communications in trusted environments. If no admin/user is associated to the provided key you need to add ".username" at the end of the key. For example if your API key is "6ajKLwswLccVBGpZGv596G.ySAXc8vtp9hMiwAuaLtzof" and you want to impersonate the admin with username "myadmin" you have to use "6ajKLwswLccVBGpZGv596G.ySAXc8vtp9hMiwAuaLtzof.myadmin" as API key. When using API key authentication you cannot manage API keys, update the impersonated admin, change password or public keys for the impersonated user.'
