API and development

UI password

Off by default: on a trusted home network the web UI is open. Enable it from Settings -> Authentication, or by hashing a password on the command line and pasting the result into the config:

# on the host:
./monloader -hash-password 'your-password'
# or via Docker:
docker exec -it monloader monloader -hash-password 'your-password'

Put the output in auth.password_hash and set auth.enable_password = true. When enabled, the web UI is gated by a session cookie (lifetime auth.session_lifetime_days, default 7); removing the password clears every session.

API tokens and scopes

monloader’s JSON API lives under /api/v1/ and requires a bearer token; the API is disabled until at least one token exists. Create tokens in Settings -> Authentication: each is named, individually revocable, and its secret is shown once at creation, never again.

Each token’s config dialog sets its scopes: read (list the queue, inspect jobs, list sites) and/or write (enqueue URLs, manage jobs). A call whose token lacks the needed scope gets 403 insufficient_scope. Tokens provisioned by pairing have fixed scopes and are removed by removing the pairing.

/health, /api/v1/openapi.json, and /api/v1/docs stay open without a token.

curl -H "Authorization: Bearer <token>" \
     -X POST http://localhost:8081/api/v1/queue \
     -d '{"url":"https://danbooru.donmai.us/posts/xxx"}'

API reference

The API documents itself in-app:

• HTML reference: /api/v1/docs (linked in the footer).
• OpenAPI spec: /api/v1/openapi.json.

Error codes

A failed queue item carries one of these stable codes; scripts and the monsender extension can branch on them:

The job’s summary aggregates its items: { created, duplicate, enriched, skipped, failed, canceled, total }. The outcomes themselves are described in downloading.

Building from source

monloader is pure Go with no CGO, so the binary is static and builds without system libraries:

make build      # go build with the version injected from VERSION.md
# or directly:
go build -o monloader ./cmd/monloader

./monloader -config /path/to/monloader.toml

make build injects the version and repository URL via -ldflags (read from VERSION.md and REPOSITORY.md), which feed the footer and /health; a plain go build reports dev.

CLI flags and subcommands:

• -config - path to the TOML config file (default ./monloader.toml).
• -hash-password '...' - print a bcrypt hash for the UI password and exit.
• -version - print the version and exit.
• healthcheck - probe the local /health endpoint and exit non-zero if it is not healthy (accepts -config and -timeout).

gallery-dl

The container image bundles Python and a pinned gallery-dl. Outside the container you supply it yourself; if it is not on PATH, set gallerydl.binary_path to its location. A missing binary is not fatal at startup - the UI and API still run, the bundled version shows as unavailable, and downloads fail until it is installed.

Adding a site profile

Mappings are data, not code, so tracking gallery-dl’s growing site list is a data change. There are two levels:

• No profile needed. Any gallery-dl site without a curated entry uses the generic fallback (sites), and the [[tag_overrides]] / [[rating_overrides]] tables in monloader.toml (mapping) can correct a generic site with no release.
• A curated profile. To improve a site’s mapping, add one entry to internal/mapping/profiles.json, keyed by the gallery-dl category. Profiles are embedded at build time, so a new one ships with a rebuild.

A profile’s fields: