openapi: 3.0.1 info: title: SFTPGo description: 'SFTPGo REST API' version: 1.2.0 servers: - url: /api/v1 paths: /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' /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" /connection: get: tags: - connections summary: Get the active users and info about their uploads/downloads operationId: get_connections responses: 200: description: successful operation content: application/json: schema: type: array items: $ref : '#/components/schemas/ConnectionStatus' /connection/{connectionID}: delete: tags: - connections summary: Terminate an active connection operationId: close_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 users description: For security reasons hashed passwords are omitted 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/SCP 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 the hashed password is omitted 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 - overwrite - delete - rename - create_dirs - create_symlinks description: > Permissions: * `*` - all permissions are granted * `list` - list items is allowed * `download` - download files is allowed * `upload` - upload files is allowed * `overwrite` - overwrite an existing file, while uploading, is allowed. upload permission is required to allow file overwrite * `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 status: type: integer enum: - 0 - 1 description: > status: * `0` user is disabled, login is not allowed * `1` user is enabled username: type: string expiration_date: type: integer format: int64 description: expiration date as unix timestamp in milliseconds. An expired account cannot login. 0 means no expiration password: type: string nullable: true 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 public_keys: type: array items: type: string nullable: true description: a password or at least one public key are mandatory. 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 user can open. 0 means unlimited quota_size: type: integer format: int64 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 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/SCP 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 last_login: type: integer format: int64 description: last user login as unix timestamp in milliseconds Transfer: type: object properties: operation_type: type: string enum: - upload - download path: type: string description: SFTP/SCP file path for the 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 connection identifier client_version: type: string description: SFTP/SCP client version remote_address: type: string description: Remote address for the connected SFTP/SCP 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 protocol: type: string enum: - SFTP - SCP active_transfers: type: array items: $ref : '#/components/schemas/Transfer' 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 VersionInfo: type: object properties: version: type: string build_date: type: string commit_hash: type: string