Syncthing API

Fully typed SDK for the Syncthing REST API

Generated from the Syncthing OpenAPI spec · Works with Vanilla Fetch · React Query · SWR

npm install syncthing

Vanilla

import createSyncthingClient from 'syncthing'

const syncthing = createSyncthingClient({
    baseUrl: 'http://localhost:8384',
    headers: { 'X-API-Key': process.env.SYNCTHING_API_KEY }
})

// Get version info
const { data: version } = await syncthing.GET('/rest/system/version')
console.log(`Syncthing ${version?.version} on ${version?.os}/${version?.arch}`)

// List all configured folders
const { data: folders } = await syncthing.GET('/rest/config/folders')
console.log(folders?.map(f => `${f.label} (${f.id})`))

// Check device connections
const { data: connections } = await syncthing.GET('/rest/system/connections')
console.log(connections?.connections)

// Get sync completion for a folder
const { data: completion } = await syncthing.GET('/rest/db/completion', {
    params: { query: { folder: 'default' } }
})
console.log(`${completion?.completion}% complete`)

Tanstack/React Query

import createSyncthingQueryClient from 'syncthing/query'

const rq = createSyncthingQueryClient({
    baseUrl: 'http://localhost:8384',
    headers: { 'X-API-Key': process.env.SYNCTHING_API_KEY }
})

function FolderList() {
    const { data, isLoading, error } = rq.useQuery('get', '/rest/config/folders')

    if (isLoading) return <div>Loading...</div>
    if (error) return <div>Error loading folders</div>

    return (
        <ul>
            {data?.map(folder => (
                <li key={folder.id}>
                    {folder.label || folder.id} — {folder.path}
                </li>
            ))}
        </ul>
    )
}

function DeviceList() {
    const { data } = rq.useQuery('get', '/rest/config/devices')

    return (
        <ul>
            {data?.map(device => (
                <li key={device.deviceID}>
                    {device.name || device.deviceID}
                </li>
            ))}
        </ul>
    )
}

SWR

import createSyncthingSWR from 'syncthing/swr'

const swr = createSyncthingSWR({
    baseUrl: 'http://localhost:8384',
    headers: { 'X-API-Key': process.env.SYNCTHING_API_KEY }
})

function SystemStatus() {
    const { data, error, isLoading } = swr.useQuery('/rest/system/status')

    if (isLoading) return <div>Loading...</div>
    if (error) return <div>Error loading status</div>

    return (
        <div>
            <p>Uptime: {Math.floor((data?.uptime ?? 0) / 3600)}h</p>
            <p>My ID: {data?.myID}</p>
        </div>
    )
}

function FolderStats() {
    const { data } = swr.useQuery('/rest/stats/folder')

    return (
        <ul>
            {Object.entries(data ?? {}).map(([id, stats]) => (
                <li key={id}>
                    {id} — last synced: {stats.lastScan}
                </li>
            ))}
        </ul>
    )
}

Tips

Syncthing requires authentication. Pass your API key when creating the client:

import createSyncthingClient from 'syncthing'

const syncthing = createSyncthingClient({
    baseUrl: 'http://localhost:8384',
    headers: { 'X-API-Key': process.env.SYNCTHING_API_KEY }
})

Contributing

Contributions = welcome. If you need to change the API surface, update the spec in syncthing-openapi, regenerate types, and keep the README examples aligned with the generated clients.