2019-07-20 10:26:52 +00:00
openapi : 3.0 .1
info :
title : SFTPGo
description : 'SFTPGo REST API'
2019-12-27 22:12:44 +00:00
version : 1.4 .0
2019-11-13 10:36:21 +00:00
2019-07-20 10:26:52 +00:00
servers :
- url : /api/v1
paths :
2019-08-08 08:01:33 +00:00
/version :
get :
tags :
- version
summary : Get version details
operationId : get_version
responses :
200 :
description : successful operation
content :
application/json :
schema :
type : array
items :
$ref : '#/components/schemas/VersionInfo'
2019-11-14 17:48:01 +00:00
/providerstatus :
get :
tags :
- providerstatus
summary : Get data provider status
operationId : get_provider_status
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 200
message : "Alive"
error : ""
500 :
description : Provider Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 500
message : ""
error : "Error description if any"
2019-08-24 12:41:15 +00:00
/connection :
2019-07-20 10:26:52 +00:00
get :
tags :
- connections
2019-08-24 12:41:15 +00:00
summary : Get the active users and info about their uploads/downloads
operationId : get_connections
2019-07-20 10:26:52 +00:00
responses :
200 :
description : successful operation
content :
application/json :
schema :
type : array
items :
$ref : '#/components/schemas/ConnectionStatus'
2019-08-24 12:41:15 +00:00
/connection/{connectionID}:
2019-07-20 10:26:52 +00:00
delete :
tags :
- connections
2019-08-24 12:41:15 +00:00
summary : Terminate an active connection
operationId : close_connection
2019-11-13 10:36:21 +00:00
parameters :
2019-07-20 10:26:52 +00:00
- name : connectionID
in : path
description : ID of the connection to close
required : true
schema :
type : string
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 200
message : "Connection closed"
error : ""
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
404 :
description : Not Found
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 404
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
/quota_scan :
get :
tags :
- quota
summary : Get the active quota scans
2019-08-01 20:42:46 +00:00
operationId : get_quota_scans
2019-07-20 10:26:52 +00:00
responses :
200 :
description : successful operation
content :
application/json :
schema :
type : array
items :
$ref : '#/components/schemas/QuotaScan'
post :
tags :
- quota
summary : start a new quota scan
description : A quota scan update the number of files and their total size for the given user
operationId : start_quota_scan
requestBody :
required : true
content :
application/json :
schema :
$ref : '#/components/schemas/User'
responses :
201 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 201
message : "Scan started"
error : ""
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 403
message : ""
error : "Error description if any"
404 :
description : Not Found
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 404
message : ""
error : "Error description if any"
409 :
description : Another scan is already in progress for this user
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 409
message : "Another scan is already in progress"
2019-11-13 10:36:21 +00:00
error : "Error description if any"
2019-07-20 10:26:52 +00:00
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
/user :
get :
tags :
- users
2019-08-24 12:41:15 +00:00
summary : Returns an array with one or more users
2019-10-07 16:19:01 +00:00
description : For security reasons hashed passwords are omitted in the response
2019-07-20 10:26:52 +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
description : The maximum number of items to return. Max value is 500, default is 100
- in : query
name : order
required : false
description : Ordering users by username
schema :
type : string
enum :
- ASC
- DESC
example : ASC
- in : query
name : username
required : false
description : Filter by username, extact match case sensitive
schema :
type : string
responses :
200 :
description : successful operation
content :
application/json :
schema :
type : array
items :
$ref : '#/components/schemas/User'
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 403
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
post :
tags :
- users
2019-11-18 22:30:37 +00:00
summary : Adds a new user
2019-07-20 10:26:52 +00:00
operationId : add_user
requestBody :
required : true
content :
application/json :
schema :
$ref : '#/components/schemas/User'
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/User'
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 403
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
/user/{userID}:
get :
tags :
- users
summary : Find user by ID
2019-10-07 16:19:01 +00:00
description : For security reasons the hashed password is omitted in the response
2019-08-01 20:42:46 +00:00
operationId : get_user_by_id
2019-11-13 10:36:21 +00:00
parameters :
2019-07-20 10:26:52 +00:00
- name : userID
in : path
description : ID of the user to retrieve
required : true
schema :
type : integer
format : int32
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/User'
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 403
message : ""
error : "Error description if any"
404 :
description : Not Found
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 404
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
put :
tags :
- users
2019-08-01 20:42:46 +00:00
summary : Update an existing user
operationId : update_user
2019-11-13 10:36:21 +00:00
parameters :
2019-07-20 10:26:52 +00:00
- name : userID
in : path
description : ID of the user to update
required : true
schema :
type : integer
format : int32
requestBody :
required : true
content :
application/json :
schema :
$ref : '#/components/schemas/User'
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 200
message : "User updated"
error : ""
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 403
message : ""
error : "Error description if any"
404 :
description : Not Found
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 404
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
delete :
tags :
- users
2019-08-01 20:42:46 +00:00
summary : Delete an existing user
operationId : delete_user
2019-11-13 10:36:21 +00:00
parameters :
2019-07-20 10:26:52 +00:00
- name : userID
in : path
description : ID of the user to delete
required : true
schema :
type : integer
format : int32
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 200
message : "User deleted"
error : ""
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 403
message : ""
error : "Error description if any"
404 :
description : Not Found
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 404
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
2019-11-13 10:36:21 +00:00
example :
2019-07-20 10:26:52 +00:00
status : 500
message : ""
error : "Error description if any"
2019-12-27 22:12:44 +00:00
/dumpdata :
get :
tags :
- maintenance
summary : Backup SFTPGo data serializing them as JSON
description : The backup is saved to a local file to avoid to expose users hashed passwords over the network. The output of dumpdata can be used as input for loaddata
operationId : dumpdata
parameters :
- in : query
name : output_file
schema :
type : string
required : true
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
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 200
message : "Data saved"
error : ""
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 403
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 500
message : ""
error : "Error description if any"
/loaddata :
get :
tags :
- maintenance
summary : Restore SFTPGo data from a JSON backup
description : New users are added, existing users are updated. Users will be restored one by one and the restore is stopped if a user cannot be added/updated, so it could happen a partial restore
operationId : loaddata
parameters :
- in : query
name : input_file
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
- in : query
name : scan_quota
schema :
type : integer
enum :
- 0
- 1
- 2
description : >
Quota scan :
* `0` no quota scan is done, the imported user will have used_quota_size and used_quota_file = 0
* `1` scan quota
* `2` scan quota if the user has quota restrictions
required : false
responses :
200 :
description : successful operation
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 200
message : "Data restored"
error : ""
400 :
description : Bad request
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 400
message : ""
error : "Error description if any"
403 :
description : Forbidden
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 403
message : ""
error : "Error description if any"
500 :
description : Internal Server Error
content :
application/json :
schema :
$ref : '#/components/schemas/ApiResponse'
example :
status : 500
message : ""
error : "Error description if any"
2019-07-20 10:26:52 +00:00
components :
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
- rename
- create_dirs
- create_symlinks
2019-11-15 11:15:07 +00:00
- chmod
- chown
2019-11-16 09:23:41 +00:00
- chtimes
2019-07-20 10:26:52 +00:00
description : >
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
* `rename` - rename files or directories is allowed
* `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
2019-12-25 17:20:19 +00:00
DirPermissions :
type : object
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
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
description : >
status :
* `0` user is disabled, login is not allowed
* `1` user is enabled
2019-07-20 10:26:52 +00:00
username :
type : string
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
nullable : true
2019-08-25 11:51:54 +00:00
description : password or public key are mandatory. If the password has no known hashing algo prefix it will be stored using argon2id. You can send a password hashed as bcrypt or pbkdf2 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
2019-07-20 10:26:52 +00:00
nullable : true
2019-10-03 13:29:54 +00:00
description : a password or at least one public key are mandatory.
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
uid :
type : integer
format : int32
minimum : 0
maximum : 65535
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
gid :
type : integer
format : int32
minimum : 0
maximum : 65535
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
max_sessions :
type : integer
format : int32
2019-08-24 12:41:15 +00:00
description : limit the sessions that an user can open. 0 means unlimited
2019-07-20 10:26:52 +00:00
quota_size :
type : integer
format : int64
2019-10-07 16:19:01 +00:00
description : quota as size in bytes. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
2019-07-20 10:26:52 +00:00
quota_files :
type : integer
format : int32
2019-08-24 12:41:15 +00:00
description : quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
2019-07-20 10:26:52 +00:00
permissions :
2019-12-25 17:20:19 +00:00
type : object
2019-07-20 10:26:52 +00:00
items :
2019-12-25 17:20:19 +00:00
$ref : '#/components/schemas/DirPermissions'
2019-07-20 10:26:52 +00:00
minItems : 1
2019-12-25 17:20:19 +00:00
example : {"/" : [ "*" ] , "/somedir" : [ "list" , "download" ] }
2019-07-20 10:26:52 +00:00
used_quota_size :
type : integer
format : int64
used_quota_file :
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-07-28 17:29:32 +00:00
description : last quota update as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
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
2019-11-13 10:36:21 +00:00
last_login :
type : integer
format : int64
description : last user login as unix timestamp in milliseconds
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
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
last_activity :
type : integer
format : int64
2019-07-28 17:29:32 +00:00
description : last transfer activity as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
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
2019-11-18 22:30:37 +00:00
ssh_command :
type : string
description : SSH command. This is not empty for protocol SSH
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
2019-07-20 10:26:52 +00:00
active_transfers :
type : array
items :
2019-08-24 12:41:15 +00:00
$ref : '#/components/schemas/Transfer'
2019-07-20 10:26:52 +00:00
QuotaScan :
type : object
properties :
username :
type : string
description : username with an active scan
start_time :
type : integer
format : int64
2019-07-28 17:29:32 +00:00
description : scan start time as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
ApiResponse :
type : object
properties :
status :
type : integer
format : int32
minimum : 200
maximum : 500
example : 200
description : HTTP Status code, for example 200 OK, 400 Bad request and so on
message :
type : string
nullable : true
description : additional message if any
error :
type : string
nullable : true
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
