API

Stump exposes an API that allows you to interact with your Stump server programmatically. The API is a fairly standard RESTful API backed by a few different authentication methods. The API is constantly being developed, and while it is generally stable at this point it is still subject to change.

Stump SDK

Stump provides a TypeScript SDK that you can use to create your own applications and integrations with Stump. If the demand is high enough, I will prioritize a proper NPM publish workflow. For the time being, you can load the dependency using something like gitpkg.

yarn add 'https://gitpkg.now.sh/stumpapp/stump/packages/sdk?main'

Then use the SDK in your application like so:

app.ts

import { Api } from '@stump/sdk'
 
const sdk = new Api({
	baseURL: 'http://localhost:10801',
	// You may also use 'session' if you configure it properly
	authMethod: 'token', // or 'session' or 'api-key'
	// If you have an API key, you can immediately set it here too:
	// apiKey: '*****'
})
 
// A token will be managed for you in-memory, but you can store it yourself
// using the returned `LoginResponse` object
await sdk.auth.login({
	username: 'oromei',
	password: 'password',
})
 
// Example query for a book by name
const favoriteBook = (
	await sdk.media.get({
		name: ['The Cybernetic Tea Shop'],
		limit: 1,
	})
).at(0)
 
// Example query for a series by ID
const favoriteSeries = await sdk.series.getByID(favoriteBook.series_id)
 
// Example query for a library by name
const ebooksLibrary = (
	await sdk.library.get({
		name: ['Ebooks'],
		limit: 1,
	})
).at(0)
 
// Example scan of a library
await sdk.library.scan(ebooksLibrary.id)

A full SDK guide will be available in the future to better support these integrations.

🚀

Have you created a custom integration with Stump using the SDK? I’d love to hear about your experience! Please share your creations by opening an issue or giving me a ping on Discord

Authentication

Sessions

Stump uses server-side sessions to authenticate users. These sessions are stored in the database, and are automatically cleaned up within 60 seconds of expiring. You can change the expiry cleanup check interval by setting the SESSION_EXPIRY_CLEANUP_INTERVAL environment variable. See the configuration guide for more information.

Basic Authentication

🔐

This functionality is only available on OPDS endpoints. You cannot authenticate with Basic Authentication on the REST API

Stump supports Basic Authentication in order to properly support OPDS clients. Authenticating using this method will still create a server-side session for you.

JWT Access Tokens

Short-lived JWT access tokens are available for API access, aimed at better enabling third-party applications and extensions to interact with Stump. While you can generate these tokens and use them to authenticate API requests, the API is still in development and subject to change.

API Keys

🔐

This functionality is gated behind the feature:api_keys user permission. To learn more about permissions, see the permissions guide.

You can generated user-scoped API keys to authenticate requests to the REST API. These keys are stored in the database and can be revoked at any time. API keys are not subject to the same expiry as sessions, and are intended for long-term use.

Special API Key Routes

There are instances where you can embed an API key in the URL directly. This will only be available for features/integrations where passing the key in the header is otherwise impossible. At the time of writing, there are two such routes:

/koreader/:api_key/* - Used for the KoReader sync integration. See here for more information
/opds/:api_key/v1.2/* - An optional clone of the OPDS integration API for clients which don’t support auth headers

For more information on API keys, see the API keys guide.

Swagger UI

Stump’s REST API is documented using Swagger. You can access Swagger UI by visiting visiting http(s)://your-server(:10801)/swagger-ui. If you aren’t familiar with Swagger, you can read more about it here. Under the hood, Stump uses utoipa for semi-automated Swagger generation. If you find any issues or inconsistencies with the API options available while using the Swagger UI, please open an issue outlining the problem.

Disabling Swagger UI

If you don’t want to expose Swagger UI, you can disable it by setting the ENABLE_SWAGGER_UI environment variable to false. See the configuration guide for more information.

OPDS CLI