8d4964c16d
Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
656 lines
20 KiB
YAML
656 lines
20 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: SFTPGo
|
|
description: 'SFTPGo REST API'
|
|
version: 1.0.0
|
|
|
|
servers:
|
|
- url: /api/v1
|
|
paths:
|
|
/sftp_connection:
|
|
get:
|
|
tags:
|
|
- connections
|
|
summary: Get the active sftp users and info about their uploads/downloads
|
|
operationId: get_sftp_connections
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref : '#/components/schemas/ConnectionStatus'
|
|
/sftp_connection/{connectionID}:
|
|
delete:
|
|
tags:
|
|
- connections
|
|
summary: Terminate an active SFTP connection
|
|
operationId: close_sftp_connection
|
|
parameters:
|
|
- 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'
|
|
example:
|
|
status: 200
|
|
message: "Connection closed"
|
|
error: ""
|
|
400:
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
example:
|
|
status: 400
|
|
message: ""
|
|
error: "Error description if any"
|
|
404:
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
example:
|
|
status: 404
|
|
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"
|
|
/quota_scan:
|
|
get:
|
|
tags:
|
|
- quota
|
|
summary: Get the active quota scans
|
|
operationId: get_quota_scans
|
|
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'
|
|
example:
|
|
status: 201
|
|
message: "Scan started"
|
|
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"
|
|
404:
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
example:
|
|
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'
|
|
example:
|
|
status: 409
|
|
message: "Another scan is already in progress"
|
|
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"
|
|
/user:
|
|
get:
|
|
tags:
|
|
- users
|
|
summary: Returns an array with one or more SFTP users
|
|
description: For security reasons password and public key are empty in the response
|
|
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'
|
|
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"
|
|
post:
|
|
tags:
|
|
- users
|
|
summary: Adds a new SFTP user
|
|
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'
|
|
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"
|
|
/user/{userID}:
|
|
get:
|
|
tags:
|
|
- users
|
|
summary: Find user by ID
|
|
description: For security reasons password and public key are empty in the response
|
|
operationId: get_user_by_id
|
|
parameters:
|
|
- 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'
|
|
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"
|
|
404:
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
example:
|
|
status: 404
|
|
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"
|
|
put:
|
|
tags:
|
|
- users
|
|
summary: Update an existing user
|
|
operationId: update_user
|
|
parameters:
|
|
- 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'
|
|
example:
|
|
status: 200
|
|
message: "User updated"
|
|
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"
|
|
404:
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
example:
|
|
status: 404
|
|
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"
|
|
delete:
|
|
tags:
|
|
- users
|
|
summary: Delete an existing user
|
|
operationId: delete_user
|
|
parameters:
|
|
- 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'
|
|
example:
|
|
status: 200
|
|
message: "User deleted"
|
|
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"
|
|
404:
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
example:
|
|
status: 404
|
|
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"
|
|
components:
|
|
schemas:
|
|
Permission:
|
|
type: string
|
|
enum:
|
|
- '*'
|
|
- list
|
|
- download
|
|
- upload
|
|
- delete
|
|
- rename
|
|
- create_dirs
|
|
- create_symlinks
|
|
description: >
|
|
Permissions:
|
|
* `*` - all permission are granted
|
|
* `list` - list items is allowed
|
|
* `download` - download files is allowed
|
|
* `upload` - upload files is allowed
|
|
* `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
|
|
User:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int32
|
|
minimum: 1
|
|
username:
|
|
type: string
|
|
password:
|
|
type: string
|
|
nullable: true
|
|
description: password or public key are mandatory. For security reasons this field is omitted when you search/get users
|
|
public_key:
|
|
type: array
|
|
items:
|
|
type: string
|
|
nullable: true
|
|
description: a password or at least one public key are mandatory. For security reasons this field is omitted when you search/get users.
|
|
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
|
|
description: limit the sessions that an sftp user can open. 0 means unlimited
|
|
quota_size:
|
|
type: integer
|
|
format: int64
|
|
description: quota as size. 0 menas unlimited. Please note that quota is updated if files are added/removed via sftp otherwise a quota scan is needed
|
|
quota_files:
|
|
type: integer
|
|
format: int32
|
|
description: quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via sftp otherwise a quota scan is needed
|
|
permissions:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Permission'
|
|
minItems: 1
|
|
used_quota_size:
|
|
type: integer
|
|
format: int64
|
|
used_quota_file:
|
|
type: integer
|
|
format: int32
|
|
last_quota_update:
|
|
type: integer
|
|
format: int64
|
|
description: last quota update as unix timestamp in milliseconds
|
|
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
|
|
SFTPTransfer:
|
|
type: object
|
|
properties:
|
|
operation_type:
|
|
type: string
|
|
enum:
|
|
- upload
|
|
- download
|
|
start_time:
|
|
type: integer
|
|
format: int64
|
|
description: start time as unix timestamp in milliseconds
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
description: bytes transferred
|
|
last_activity:
|
|
type: integer
|
|
format: int64
|
|
description: last transfer activity as unix timestamp in milliseconds
|
|
ConnectionStatus:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: connected username
|
|
connection_id:
|
|
type: string
|
|
description: unique sftp connection identifier
|
|
client_version:
|
|
type: string
|
|
description: SFTP client version
|
|
remote_address:
|
|
type: string
|
|
description: Remote address for the connected SFTP client
|
|
connection_time:
|
|
type: integer
|
|
format: int64
|
|
description: connection time as unix timestamp in milliseconds
|
|
last_activity:
|
|
type: integer
|
|
format: int64
|
|
description: last client activity as unix timestamp in milliseconds
|
|
active_transfers:
|
|
type: array
|
|
items:
|
|
$ref : '#/components/schemas/SFTPTransfer'
|
|
QuotaScan:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: username with an active scan
|
|
start_time:
|
|
type: integer
|
|
format: int64
|
|
description: scan start time as unix timestamp in milliseconds
|
|
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
|