Skip to content

What works

This page is the feature-level status of altero's Zotero v3 compatibility.

Release: 1.0.0-beta.2. Two real Zotero 10.0.5 profiles passed 47 database/scenario combinations and 594 phases on Linux, across SQLite and PostgreSQL 18.4. This verifies the recorded transitions, not every client path or platform. See desktop compatibility coverage and gaps.

One confirmed issue remains in Zotero 10.0.1 itself: when file-conflict sides have equal displayed modification dates, choosing Remote can retain the local bytes. See the reproduced client behavior.

Short version: ordinary Zotero Desktop synchronization is the target; the official mobile apps work through a build of your own, unofficially but supported.

User-facing capabilities

Capability Status Notes
Zotero Desktop synchronization ✅ Items, collections, tags, saved searches and deletions
Notes and annotations ✅ Included in normal item synchronization
Attachment file sync ✅ Files stored once per digest
Full-text upload and search ✅ Uses the database rather than Elasticsearch
Group libraries ✅ Includes group policy and membership
My Publications ✅ Includes browser publishing and profile pages
Citations and bibliographies ✅ CSL-based styles and Zotero-compatible formats
Zotero export formats ✅ API and browser export support
Browser interface ✅ Library browsing, account settings, groups and administration
OIDC and SAML browser sign-in ✅ Sign-in only; never a v3 API credential
OAuth 2.0 and OIDC provider ✅ Scoped tokens for third-party applications, confinable to chosen libraries and collections; requires a stable public URL
Passkeys and optional second factors ✅ Passkeys require a stable public URL
Import a personal library from zotero.org ✅ Preserves object keys and versions
Zotero iOS and Android apps ⚠️ Unofficial: needs a build pointed at altero; Android reported working on a device, iOS untested

Synchronization and API behavior implemented

altero implements the parts of the v3 API needed by the desktop client, including:

  • API-key authentication and per-library permissions;
  • OAuth 2.0 access tokens as a second credential for the same endpoints;
  • personal and group library discovery;
  • item, collection, saved-search and tag reads;
  • json, atom, keys and versions response formats;
  • pagination, sorting, since and version-aware conditional requests;
  • item, collection and saved-search writes with version preconditions;
  • deleted-object synchronization;
  • library settings;
  • attachment full text;
  • the three-step attachment file protocol;
  • the streaming API at /stream;
  • My Publications and publication visibility;
  • citations, bibliographies, CSL JSON and Zotero export formats;
  • group creation, membership and group policy;
  • rate limiting when enabled; and
  • API version negotiation.

The compatibility reference documents behavior that differs from the public API documentation or that had to be learned from the real client or server: Compatibility notes.

Additional altero features

These are not required for basic Zotero compatibility but are available on an altero instance:

  • browser-based account and API-key management;
  • instance administration without library-wide superuser access;
  • OpenID Connect and SAML 2.0 browser sign-in;
  • an OAuth 2.0 and OpenID Connect authorization server, so a third-party application can be given scoped, expiring access instead of an API key, confinable to chosen libraries and collections, with RP-initiated sign-out and a device grant for a machine that has no browser;
  • passkeys, authenticator-app second factors and email codes;
  • per-member group permissions such as read-only, add-without-remove and own-items-only;
  • group activity and opt-in notifications;
  • configurable retention;
  • server-side tag rename;
  • single-collection sharing links;
  • storage reporting; and
  • whole-library export/import and migration from zotero.org.

Not implemented

  • Zotero's Note HTML and Note Markdown translators. These create a note rather than an ordinary bibliography/export response.
  • Zotero-hosted read-aloud speech synthesis and credit services (/tts/...).
  • Legacy password-to-key creation (POST /keys); use desktop browser linking or an API key.
  • Legacy removestoragefiles; synced attachment removal follows item deletion.

Client requests without a reference server implementation

Two client behaviors do not have a corresponding implementation in the public dataserver source:

  • GET /retractions/list; and
  • the streaming WebSocket service.

altero currently answers the retractions request with 404. Zotero logs the failure and continues syncing. The streaming API is implemented from the published protocol and observed client behavior.

Library versions and concurrent writes

Writes to a library are serialized so one request advances the library by one version, even when that request changes several objects. This is important because Zotero synchronization uses the library version as its consistency boundary.

See Database schema for the implementation details.