REST API

Each smallweb installation comes with a built-in REST API. You can map it to a subdomain by creating a smallweb.json manifest:

// ~/smallweb/api/smallweb.jsonc
{
    "entrypoint": "smallweb:api",
    // make sure to protect your API
    "private": true,
    "publicRoutes": [
        // openapi manifest
        "/openapi.json",
        // json schemas for config files
        "/schemas/*"
    ]
}

A swagger UI is available at the root of the api, allowing you to easily test the available endpoints.

Authentication

You'll need to generate a bearer token to access the API. You can create one by running the following command:

smallweb token create --description "api token" --app <api-subdomain>

You'll then be able to use it to authenticate your requests using this token:

curl https://<api-domain>/v0/apps -H "Authorization: Bearer <token>"

Or you can just use the smallweb api command, which automatically authenticates your requests:

smallweb api /v0/apps

Client Library

Since the API is based on OpenAPI, you can easily generate client libraries for your favorite language.

For usage in smallweb apps, I personally recommend using feTS.

Here is an example of how you can use it (no code-gen required):

import { createClient, type NormalizeOAS } from 'npm:fets'
import type openapi from 'jsr:@smallweb/openapi@<smallweb-version>'

const client = createClient<NormalizeOAS<typeof openapi>>({
    endpoint: Deno.env.get("SMALLWEB_API_URL"),
    globalParams: {
        headers: {
            Authorization: `Bearer ${Deno.env.get("SMALLWEB_API_TOKEN")}`
        }
    }
})

const res = await client['/v0/apps'].get()
if (!res.ok) {
    throw new Error(`Failed to fetch apps: ${res.statusText}`)
}

const apps = await res.json() // typed!

Webdav Server

The rest api bundles a webdav server that you can use to manage your files. It is accessible at: https://<api-domain>/webdav.

You can easily connect it to any webdav client:

Windows

Open the File Explorer.
Click on the Computer tab.
Click on Map network drive.
Enter the URL of the webdav server in the Folder field.
Click Finish.
Enter your Smallweb username and password.
Click OK.

MacOS

Open the Finder.
Click on Go in the menu bar.
Click on Connect to Server.
Enter the URL of the webdav server in the Server Address field.
Click Connect.
Enter your Smallweb username and password.
Click Connect.
Click Done.

Linux (Ubuntu)

Open Nautilus / Files.
Click on Other Locations.
Enter the URL of the webdav server, and prefix with davs:// (ex: davs://<api-domain>/webdav).
Click Connect.
Enter your Smallweb username and password.
Click Connect.

Android

Material Files has built-in support for WebDAV.

Javascript

I'm still searching for a good webdav client in javascript. The best I found so far is webdav-client, but I don't really like it.

Still, here is an example of how you can use it:

import * as webdav from 'webdav'

const webdavClient = webdav.createClient(new URL("/webdav", Deno.env.get("SMALLWEB_API_URL")).href, {
    authType: webdav.AuthType.Password,
    username: Deno.env.get("SMALLWEB_API_TOKEN")
})

const apps = await webdavClient.getDirectoryContents("/")

Smallweb