Upgrade Storagezotkit — headless Zotero library management via the Web API, incl. WebDAV attachment upload/download
Hi all,
I manage my Zotero library from a headless Linux server (no GUI, so no desktop app), and ended up building a small Python package + CLI for it that I've now open-sourced in case it's useful to others:
GitHub: https://github.com/oldantique/zotkit
PyPI: pipx install zotkit
What it does, entirely through the Web API:
- search / create items (with DOI+title dedup, dry-run by default), tags, collections, reading status, full-library JSON backups
- optionally enforce a namespaced tag taxonomy (conventions.toml) in code — handy when scripts or LLM agents write to your library
The part that may be of most interest here: for libraries that sync files to a personal WebDAV server, zotkit can UPLOAD and download the attachment files themselves by writing Zotero's WebDAV storage layout directly (K.zip + K.prop with md5/mtime, and setting md5/mtime on the attachment item via the API). As far as I could find, existing headless tools only support Zotero File Storage uploads or WebDAV downloads. I documented the format here: https://github.com/oldantique/zotkit/blob/main/docs/webdav-format.md
Caveats: the WebDAV layout is undocumented, so this was determined by interoperability inspection of my own library — it round-trips cleanly with desktop clients in my testing, but please keep backups and treat it as beta.
Corrections from anyone who knows the sync internals better are very welcome (e.g. whether ignoring lastsync.txt is safe in all cases).
MIT-licensed; feedback and issues welcome. Not affiliated with Zotero.
I manage my Zotero library from a headless Linux server (no GUI, so no desktop app), and ended up building a small Python package + CLI for it that I've now open-sourced in case it's useful to others:
GitHub: https://github.com/oldantique/zotkit
PyPI: pipx install zotkit
What it does, entirely through the Web API:
- search / create items (with DOI+title dedup, dry-run by default), tags, collections, reading status, full-library JSON backups
- optionally enforce a namespaced tag taxonomy (conventions.toml) in code — handy when scripts or LLM agents write to your library
The part that may be of most interest here: for libraries that sync files to a personal WebDAV server, zotkit can UPLOAD and download the attachment files themselves by writing Zotero's WebDAV storage layout directly (K.zip + K.prop with md5/mtime, and setting md5/mtime on the attachment item via the API). As far as I could find, existing headless tools only support Zotero File Storage uploads or WebDAV downloads. I documented the format here: https://github.com/oldantique/zotkit/blob/main/docs/webdav-format.md
Caveats: the WebDAV layout is undocumented, so this was determined by interoperability inspection of my own library — it round-trips cleanly with desktop clients in my testing, but please keep backups and treat it as beta.
Corrections from anyone who knows the sync internals better are very welcome (e.g. whether ignoring lastsync.txt is safe in all cases).
MIT-licensed; feedback and issues welcome. Not affiliated with Zotero.