API

client.py

class SlskdClient(host: str, api_key: str = None, url_base: str = '/', username: str = None, password: str = None, token: str = None, verify_ssl: bool = True, timeout: float = None)

The main class that allows access to the different APIs of a slskd instance. An API-Key with appropriate permissions (readwrite for most use cases) must be set in slskd config file. Alternatively, provide your username and password. Requests error status raise corresponding error. Usage:

slskd = slskd_api.SlskdClient(host, api_key, url_base)
app_status = slskd.application.state()

apis/_types.py

class AppVersion

TypedDict describing application version. Returned by check_updates().

full: str

current: str

latest: str

isUpdateAvailable: bool

isCanary: bool

isDevelopment: bool

class AppState

TypedDict describing application state. Returned by state().

version: AppVersion

pendingReconnect: bool

pendingRestart: bool

server: ServerState

connectionWatchdog: dict

relay: dict

user: dict

distributedNetwork: dict

shares: dict

rooms: list[str]

users: list

class Message

TypedDict describing a message. Element of Conversation.

timestamp: str

id: int

username: str

direction: Literal['Out', 'In']

message: str

isAcknowledged: bool

wasReplayed: bool

class Conversation

TypedDict describing a conversation. Returned by get().

username: str

isActive: bool

unAcknowledgedMessageCount: int

hasUnAcknowledgedMessages: bool

messages: NotRequired[list[Message]]

class Event

TypedDict describing an event. Single element of list returned by get().

timestamp: str

type: Literal['DownloadFileComplete', 'DownloadDirectoryComplete', 'UploadFileComplete', 'PrivateMessageReceived', 'RoomMessageReceived', 'Noop']

data: str

id: str

class File

TypedDict describing a file in the downloads or incomplete folder. See FilesApi.

name: str

fullName: str

length: int

attributes: str

createdAt: str

modifiedAt: str

class Directory

TypedDict describing a directory in the downloads or incomplete folder. See FilesApi.

name: str

fullName: str

attributes: str

createdAt: str

modifiedAt: str

files: NotRequired[list[File]]

directories: NotRequired[list[Directory]]

class LogEntry

TypedDict describing a log entry. Single element of list returned by get().

timestamp: str

context: str

level: str

message: str

class RoomMessage

TypedDict describing a message in a room. See Room.

timestamp: str

username: str

message: str

roomName: str

class RoomInfo

TypedDict describing room info.

name: str

userCount: int

isPrivate: bool

isOwned: bool

isModerated: bool

class RoomUser

TypedDict describing a room user.

averageSpeed: int

countryCode: str

directoryCount: int

fileCount: int

slotsFree: int

status: Literal['Offline', 'Away', 'Online']

uploadCount: int

username: str

class Room

TypedDict describing a room. Returned by join() and get_joined().

name: str

isPrivate: bool

users: list[RoomUser]

messages: list[RoomMessage]

class SearchFile

TypedDict describing a single search file result. Element found in SearchResponseItem.

filename: str

size: int

code: int

isLocked: bool

extension: str

bitRate: NotRequired[int]

bitDepth: NotRequired[int]

length: NotRequired[int]

sampleRate: NotRequired[int]

class SearchResponseItem

TypedDict describing a search response item. Single element of list returned by search_responses().

fileCount: int

files: list[SearchFile]

hasFreeUploadSlot: bool

lockedFileCount: int

lockedFiles: list[SearchFile]

queueLength: int

token: int

uploadSpeed: int

username: str

class SearchState

TypedDict describing search state. Returned by state().

endedAt: NotRequired[str]

fileCount: int

id: str

isComplete: bool

lockedFileCount: int

responseCount: int

responses: list[SearchResponseItem]

searchText: str

startedAt: str

state: str

token: int

class ServerState

TypedDict describing server state. Returned by state().

address: str

ipEndPoint: str

state: Literal['Connected, LoggedIn', 'Disconnected']

isConnected: bool

isConnecting: bool

isLoggedIn: bool

isLoggingIn: bool

isTransitioning: bool

class SessionStatus

TypedDict describing session status. Returned by login().

expires: int

issued: int

name: str

notBefore: int

token: str

tokenType: str

class ShareInfo

TypedDict describing a shared directory. Returned by get().

id: str

alias: str

isExcluded: bool

localPath: str

raw: str

remotePath: str

directories: int

files: int

class Shares

TypedDict describing all shares (local or from relays). Returned by get_all().

local: list[ShareInfo]

class TransferedFile

TypedDict describing a transfered file. Element found in TransferedDirectory.

id: str

username: str

direction: Literal['Download', 'Upload']

filename: str

size: int

startOffset: int

state: str

requestedAt: str

enqueuedAt: NotRequired[str]

startedAt: NotRequired[str]

endedAt: NotRequired[str]

bytesTransferred: int

averageSpeed: float

bytesRemaining: int

elapsedTime: NotRequired[str]

percentComplete: float

remainingTime: NotRequired[str]

class TransferedDirectory

TypedDict describing a transfered directory. Element found in Transfer.

directory: str

fileCount: int

files: list[TransferedFile]

class Transfer

TypedDict describing transfer(s) to/from a given user. See TransfersApi.

username: str

directories: NotRequired[list[TransferedDirectory]]

class UserAddress

TypedDict describing a user IP address. Returned by address().

addressFamily: str

address: str

port: int

class BrowsingStatus

TypedDict describing browsing status of a user’s shares. Returned by browsing_status().

bytesTransferred: int

bytesRemaining: int

percentComplete: int

size: int

username: str

class UserInfo

TypedDict describing user info. Returned by info().

description: str

hasFreeUploadSlot: bool

hasPicture: bool

picture: NotRequired[str]

queueLength: int

uploadSlots: int

class UserStatus

TypedDict describing user status. Returned by status().

isPrivileged: bool

presence: Literal['Offline', 'Away', 'Online']

class FileAttribute

TypedDict describing a file attribute. Defined attributes are added as new keys to UserFile.

type: str

value: int

class UserFile

TypedDict describing a user file. Found in UserDirectory.

attributeCount: int

attributes: list[FileAttribute]

code: int

extension: str

filename: str

size: int

class UserDirectory

TypedDict describing a user directory either locked or not. See UserRootDir.

name: str

fileCount: int

files: list[UserFile]

class UserRootDir

TypedDict describing the root of a user’s shares. Returned by browse().

directories: list[UserDirectory]

directoryCount: int

lockedDirectories: list[UserDirectory]

lockedDirectoryCount: int

apis/application.py

class ApplicationApi(api_url: str, session: Session)

This class contains the methods to interact with the Application API.

state()

Gets the current state of the application.

Return type:: AppState

stop()

Stops the application. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Returns:: bool – True if successful.

restart()

Restarts the application. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Returns:: bool – True if successful.

version()

Gets the current application version.

Return type:: str

check_updates(forceCheck: bool = False)

Checks for updates.

Return type:: AppVersion

gc()

Forces garbage collection.

Returns:: bool – True if successful.

apis/conversations.py

class ConversationsApi(api_url: str, session: Session)

This class contains the methods to interact with the Conversations API.

acknowledge(username: str, id: int)

Acknowledges the given message id for the given username.

Returns:: bool – True if successful.

acknowledge_all(username: str)

Acknowledges all messages from the given username.

Returns:: bool – True if successful.

delete(username: str)

Closes the conversation associated with the given username.

Returns:: bool – True if successful.

get(username: str, includeMessages: bool = True)

Gets the conversation associated with the specified username.

Return type:: Conversation

send(username: str, message: str)

Sends a private message to the specified username.

Returns:: bool – True if successful.

get_all(includeInactive: bool = False, unAcknowledgedOnly: bool = False)

Gets all active conversations.

Return type:: list[Conversation]

get_messages(username: str, unAcknowledgedOnly: bool = False)

Gets all messages associated with the specified username.

Return type:: list[Message]

apis/events.py

class EventsApi(api_url: str, session: Session)

This class contains the methods to interact with the Events API.

get(start: int = 0, limit: int = 100)

Retrieves a paginated list of past event records.

Parameters:

start (int) – The offset (number of records) at which to start the requested page.
limit (int) – The page size.

Return type:

list[Event]

create(event_type: Literal['DownloadFileComplete', 'DownloadDirectoryComplete', 'UploadFileComplete', 'PrivateMessageReceived', 'RoomMessageReceived', 'Noop'], data: str = '')

Raises a sample event of the specified type.

Returns:: bool – True if successful.

apis/files.py

class FilesApi(api_url: str, session: Session)

This class contains the methods to interact with the Files API. In order to delete files/directory you need to set remoteFileManagement: true in slskd.yml.

get_downloads_dir(recursive: bool = False)

Lists the contents of the downloads directory.

Parameters:: recursive (bool) – whether to recursively list subdirectories and files.
Return type:: Directory

get_downloaded_directory(dir_name: str, recursive: bool = False)

Lists the contents of the specified subdirectory within the downloads directory.

Parameters:: recursive (bool) – whether to recursively list subdirectories and files.
Return type:: Directory

delete_downloaded_directory(dir_name: str)

Deletes the specified subdirectory within the downloads directory.

Return type:: bool

delete_downloaded_file(file_name: str)

Deletes the specified file within the downloads directory.

Return type:: bool

get_incomplete_dir(recursive: bool = False)

Lists the contents of the incomplete directory.

Parameters:: recursive (bool) – whether to recursively list subdirectories and files.
Return type:: Directory

get_incomplete_directory(dir_name: str, recursive: bool = False)

Lists the contents of the specified subdirectory within the incomplete directory.

Parameters:: recursive (bool) – whether to recursively list subdirectories and files.
Return type:: Directory

delete_incomplete_directory(dir_name: str)

Deletes the specified subdirectory within the incomplete directory.

Return type:: bool

delete_incomplete_file(file_name: str)

Deletes the specified file within the incomplete directory.

Return type:: bool

apis/logs.py

class LogsApi(api_url: str, session: Session)

This class contains the methods to interact with the Logs API.

get()

Gets the last few application logs.

Return type:: list[LogEntry]

apis/options.py

class OptionsApi(api_url: str, session: Session)

This class contains the methods to interact with the Options API.

get()

Gets the current application options.

Return type:: dict

get_startup()

Gets the application options provided at startup.

Return type:: dict

debug()

Gets the debug view of the current application options. debug and remote_configuration must be set to true. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Return type:: str

yaml_location()

Gets the path of the yaml config file. remote_configuration must be set to true. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Return type:: str

download_yaml()

Gets the content of the yaml config file as text. remote_configuration must be set to true. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Return type:: str

upload_yaml(yaml_content: str)

Sets the content of the yaml config file. remote_configuration must be set to true. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Returns:: bool – True if successful.

validate_yaml(yaml_content: str)

Validates the provided yaml string. remote_configuration must be set to true. Only works with token (usr/pwd login). ‘Unauthorized’ with API-Key.

Returns:: str – Empty string if validation successful. Error message otherwise.

apis/relay.py

class RelayApi(api_url: str, session: Session)

[UNTESTED] This class contains the methods to interact with the Relay API.

connect()

Connects to the configured controller.

Returns:: bool – True if successful.

disconnect()

Disconnects from the connected controller.

Returns:: bool – True if successful.

download_file(token: str)

Downloads a file from the connected controller.

Returns:: bool – True if successful.

upload_file(token: str)

Uploads a file from the connected controller.

Returns:: bool – True if successful.

upload_share_info(token: str)

Uploads share information to the connected controller.

Returns:: bool – True if successful.

apis/rooms.py

class RoomsApi(api_url: str, session: Session)

This class contains the methods to interact with the Rooms API.

get_all_joined()

Gets all joined rooms.

Returns:: list[str] – Names of the joined rooms.

join(roomName: str)

Joins a room.

Return type:: Room

get_joined(roomName: str)

Gets the specified room.

Return type:: Room

leave(roomName: str)

Leaves a room.

Returns:: bool – True if successful.

send(roomName: str, message: str)

Sends a message to the specified room.

Returns:: bool – True if successful.

get_messages(roomName: str)

Gets the current list of messages for the specified room.

Return type:: list[RoomMessage]

set_ticker(roomName: str, ticker: str)

Sets a ticker for the specified room.

Returns:: bool – True if successful.

add_member(roomName: str, username: str)

Adds a member to a private room.

Returns:: bool – True if successful.

get_users(roomName: str)

Gets the current list of users for the specified joined room.

Return type:: list[RoomUser]

get_all()

Gets a list of rooms from the server.

Return type:: list[RoomInfo]

apis/searches.py

class SearchesApi(api_url: str, session: Session)

Class that handles operations on searches.

search_text(searchText: str, id: str = None, fileLimit: int = 10000, filterResponses: bool = True, maximumPeerQueueLength: int = 1000000, minimumPeerUploadSpeed: int = 0, minimumResponseFileCount: int = 1, responseLimit: int = 100, searchTimeout: int = 15000)

Performs a search for the specified request.

Parameters:

searchText (str) – Search query
id (str) – uuid of the search. One will be generated if None.
fileLimit (int) – Max number of file results
filterResponses (bool) – Filter unreachable users from the results
maximumPeerQueueLength (int) – Max queue length
minimumPeerUploadSpeed (int) – Min upload speed in bit/s
minimumResponseFileCount (int) – Min number of matching files per user
responseLimit (int) – Max number of users results
searchTimeout (int) – Search timeout in ms

Returns:

SearchState – Info about the search (no results!)

get_all()

Gets the list of active and completed searches.

Return type:: list[SearchState]

state(id: str, includeResponses: bool = False)

Gets the state of the search corresponding to the specified id.

Parameters:

id (str) – uuid of the search.
includeResponses (bool) – Include responses (search result list) in the returned dict

Returns:

SearchState – Info about the search

stop(id: str)

Stops the search corresponding to the specified id.

Returns:: bool – True if successful.

delete(id: str)

Deletes the search corresponding to the specified id.

Returns:: bool – True if successful.

search_responses(id: str)

Gets search responses corresponding to the specified id.

Parameters:: id (str) – uuid of the search.
Returns:: list[SearchResponseItem] – Search responses.

apis/server.py

class ServerApi(api_url: str, session: Session)

This class contains the methods to interact with the Server API.

connect()

Connects the client.

Returns:: bool – True if successful.

disconnect()

Disconnects the client.

Returns:: bool – True if successful.

state()

Retrieves the current state of the server.

Return type:: ServerState

apis/session.py

class SessionApi(api_url: str, session: Session)

This class contains the methods to interact with the Session API.

auth_valid()

Checks whether the provided authentication is valid.

Return type:: bool

login(username: str, password: str)

Logs in.

Returns:: SessionStatus – Session info for the given user incl. token.

security_enabled()

Checks whether security is enabled.

Return type:: bool

apis/shares.py

class SharesApi(api_url: str, session: Session)

This class contains the methods to interact with the Shares API.

get_all()

Gets the current list of shares.

Return type:: Shares

start_scan()

Initiates a scan of the configured shares.

Returns:: bool – True if successful.

cancel_scan()

Cancels a share scan, if one is running.

Returns:: bool – True if successful.

get(id: str)

Gets the share associated with the specified id.

Return type:: ShareInfo

all_contents()

Returns a list of all shared directories and files.

Return type:: list[UserDirectory]

contents(id: str)

Gets the contents of the share associated with the specified id.

Return type:: list[UserDirectory]

apis/telemetry.py

class TelemetryApi(api_url: str, session: Session)

This class contains the methods to interact with the Metrics API.

get_metrics()

Gets the Prometheus metrics as text.

Return type:: str

get_kpis()

Gets application KPIs.

Return type:: str

get_transfer_summary(start: str = None, end: str = None, direction: Literal['Download', 'Upload'] = None, username: str = None)

Gets a summary of all transfer activity over the specified timeframe, grouped by direction and final state.

Parameters:

start (str) – The start time of the window (default: 7 days ago). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”

Return type:

dict

get_transfer_histogram(start: str = None, end: str = None, interval: int = 60, direction: Literal['Download', 'Upload'] = None, username: str = None)

Gets a histogram of all transfer activity over the specified timeframe, aggregated into fixed size time intervals and grouped by direction and final state.

Parameters:

start (str) – The start time of the window (default: 7 days ago). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”
interval (int) – The interval, in minutes (default: 60).

Return type:

dict

get_transfer_leaderboard(direction: Literal['Download', 'Upload'], start: str = None, end: str = None, sortBy: Literal['Count', 'TotalBytes', 'AverageSpeed'] = 'Count', sortOrder: Literal['ASC', 'DESC'] = 'DESC', limit: int = 25, offset: int = 0)

Gets the top N user summaries by count, total bytes, or average speed.

Parameters:

start (str) – The start time of the window (default: oldest). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”
sortBy (Literal['Count', 'TotalBytes', 'AverageSpeed']) – The property by which to sort.
sortOrder (Literal['ASC', 'DESC']) – The sort order.
limit (int) – The number of records to return.
offset (int) – The record offset (if paginating).

Returns:

list – List of users (dict) with transfer related info (count, totalBytes, averageSpeed…)

get_user_transfers(username: str, start: str = None, end: str = None)

Gets detailed transfer activity for the specified user.

Parameters:

start (str) – The start time of the window (default: oldest). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”

Return type:

dict

get_transfer_exceptions(direction: Literal['Download', 'Upload'], start: str = None, end: str = None, username: str = None, sortOrder: Literal['ASC', 'DESC'] = 'DESC', limit: int = 25, offset: int = 0)

Gets a list of transfer exceptions by direction.

Parameters:

start (str) – The start time of the window (default: oldest). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”
username (str) – An optional username by which to filter exceptions.
sortOrder (Literal['ASC', 'DESC']) – The sort order.
limit (int) – The number of records to return.
offset (int) – The record offset (if paginating).

Returns:

list – List of exceptions (dict) with transfer related info (direction, filename, state…)

get_transfer_exceptions_pareto(direction: Literal['Download', 'Upload'], start: str = None, end: str = None, username: str = None, limit: int = 25, offset: int = 0)

Gets the top N exceptions by total count and direction.

Parameters:

start (str) – The start time of the window (default: oldest). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”
username (str) – An optional username by which to filter exceptions.
limit (int) – The number of records to return.
offset (int) – The record offset (if paginating).

Returns:

list – List of exceptions (dict) with following info: exception message, count and distinctUsers.

get_most_dl_directories(start: str = None, end: str = None, username: str = None, limit: int = 25, offset: int = 0)

Gets the top N most frequently downloaded directories by total count and distinct users.

Parameters:

start (str) – The start time of the window (default: oldest). e.g. “2026-01-31”
end (str) – The end time of the window (default: now). e.g. “2026-02-15”
username (str) – An optional username by which to filter exceptions.
limit (int) – The number of records to return.
offset (int) – The record offset (if paginating).

Returns:

list – List of directories (dict) with following info: path, count and distinctUsers.

apis/transfers.py

class TransfersApi(api_url: str, session: Session)

This class contains the methods to interact with the Transfers API.

cancel_download(username: str, id: str, remove: bool = False)

Cancels the specified download.

Returns:: bool – True if successful.

get_download(username: str, id: str)

Gets the specified download.

Return type:: Transfer

remove_completed_downloads()

Removes all completed downloads, regardless of whether they failed or succeeded.

Returns:: bool – True if successful.

cancel_upload(username: str, id: str, remove: bool = False)

Cancels the specified upload.

Returns:: bool – True if successful.

get_upload(username: str, id: str)

Gets the specified upload.

Return type:: Transfer

remove_completed_uploads()

Removes all completed uploads, regardless of whether they failed or succeeded.

Returns:: bool – True if successful.

enqueue(username: str, files: list[SearchFile])

Enqueues the specified download.

Parameters:

username (str) – User to download from.
files (list[SearchFile]) – A list of files that can be obtained by search_responses() (see key files of SearchResponseItem).

Returns:

bool – True if successful.

get_downloads(username: str)

Gets all downloads for the specified username.

Return type:: Transfer

get_all_downloads(includeRemoved: bool = False)

Gets all downloads.

Return type:: list[Transfer]

get_queue_position(username: str, id: str)

Gets the download for the specified username matching the specified filename, and requests the current place in the remote queue of the specified download.

Returns:: Union[int, str] – Queue position or error message

get_all_uploads(includeRemoved: bool = False)

Gets all uploads.

Return type:: list[Transfer]

get_uploads(username: str)

Gets all uploads for the specified username.

Return type:: Transfer

apis/users.py

class UsersApi(api_url: str, session: Session)

This class contains the methods to interact with the Users API.

address(username: str)

Retrieves the address of the specified username.

Return type:: UserAddress

browse(username: str)

Retrieves the files shared by the specified username.

Return type:: UserRootDir

browsing_status(username: str)

Retrieves the status of the current browse operation for the specified username, if any. Will return error 404 if called after the browsing operation has ended. Best called asynchronously while browse() is still running.

Return type:: BrowsingStatus

directory(username: str, directory: str)

Retrieves the specified directory from the specified user. This returns a list (usually with a single element).

Return type:: list[UserDirectory]

info(username: str)

Retrieves information about the specified username.

Return type:: UserInfo

status(username: str)

Retrieves status for the specified username.

Return type:: UserStatus