Maven Central

katbox is a Kotlin multiplatform wrapper written with ktor and coroutines, for
interacting with the permanent file hosting service Catbox, and its temporary file hosting service
equivalent Litterbox. All public endpoints defined by
Catbox and Litterbox are implemented.


repositories { 

dependencies {

katbox does not define any ktor-client engine by itself, therefore you will need to define one yourself. Information
can be found here.


katbox separates any anonymous operations from logged in operations by placing all anonymous operations in the Catbox
companion object. Therefore any functions defined there do not require a userhash.

All functions are documented properly, so only the very basics will be shown here, for further information, read the
documentation on the functions.

Uploading files

All upload functions return a String, which contains the url to the uploaded file.


// upload raw bytes
Catbox.upload(byteArray(4, 2), "foo.bar")
// upload from an url
// if on the JVM, upload via Path

// litterbox only allows anonymous uploads
// upload raw bytes
Litterbox.upload(byteArray(4, 2), "foo.bar")
// if on the JVM, upload via Path

As user

// to upload as a user, a Catbox instance must be created
// no verification on whether the userHash is valid is done, so be careful
val catbox = Catbox(userHash = "####")
// upload raw bytes
catbox.upload(byteArray(4, 2), "foo.bar")
// upload from an url
// if on the JVM, upload via Path

Creating an album with newly uploaded images

This example is a bit contrived, but at least serves as somewhat of a real-world example.

val catbox = Catbox(userHash = "####")
val files = Path("./foo/").listDirectoryEntries(glob = "*.png").map { catbox.upload(it) }
val myCoolAlbum = catbox.createAlbum(
    title = "My Cool Images", 
    description = "A collection of all my cool images.",
    files = files.mapTo(hashSet()) { it.substringAfterLast('/') },


View Github