Protocol links
Every obsidian://zotlit/* action, its parameters, and usage for scripting workflows.
Available sinceZotLit 2.0.0
This page documents every obsidian://zotlit/* protocol action. These deep links allow external tools (the ZotLit companion, scripts, launchers) to trigger ZotLit operations in Obsidian.
Common parameters
Every protocol link requires a source-id parameter: an 8-character hex string identifying the Zotero install that generated the link. ZotLit rejects links whose source-id does not match the connected database, showing:
This link was created by a different Zotero install.
If the Zotero database is not yet loaded, ZotLit shows:
Open the Zotero database to handle this link.
Actions
open
Opens the existing literature note for a Zotero item, or creates one if none exists.
obsidian://zotlit/open?item=<id>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
item | Integer | Yes | Zotero item ID |
source-id | 8-char hex | Yes | Zotero install identifier |
update
Re-renders a literature note from the current Zotero data.
obsidian://zotlit/update?item=<id>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
item | Integer | Yes | Zotero item ID |
source-id | 8-char hex | Yes | Zotero install identifier |
scope | full or metadata | No | What to update. Default: full (frontmatter + managed body region). metadata updates frontmatter only. |
update-many
Batch-updates multiple literature notes. Opens an interactive confirm/progress modal.
obsidian://zotlit/update-many?items=<id,id,...>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
items | Comma-separated integers | Yes | Zotero item IDs (deduplicated; trailing comma tolerated) |
source-id | 8-char hex | Yes | Zotero install identifier |
scope | full or metadata | No | Default: full |
For batches too large for a URL, ZotLit also exposes PUT {host} /literature-notes with the same parameters in the request body, gated by a
source-id header.
import-note
Imports a single Zotero note (or child notes from an item) into the vault.
obsidian://zotlit/import-note?item=<id>&mode=<mode>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
item | Integer | Yes | Zotero item ID |
mode | note or child | Yes | note imports a standalone note; child imports child notes of a parent item |
source-id | 8-char hex | Yes | Zotero install identifier |
import-notes
Batch-imports multiple Zotero notes.
obsidian://zotlit/import-notes?items=<id,id,...>&mode=<mode>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
items | Comma-separated integers | Yes | Zotero item IDs (deduplicated; trailing comma tolerated) |
mode | note or child | Yes | Import mode |
source-id | 8-char hex | Yes | Zotero install identifier |
For batches too large for a URL, ZotLit also exposes PUT {host}/zotero-notes
with the same parameters in the request body, gated by a source-id header.
update-all
Creates or updates a literature note for every item in one library, optionally narrowed to one collection. Opens the same batch confirmation modal as update-many.
obsidian://zotlit/update-all?source-id=<hash>&library=<groupID>&collection=<key>| Parameter | Type | Required | Description |
|---|---|---|---|
source-id | 8-char hex | Yes | Zotero install identifier |
library | Integer | No | Zotero group ID of the target library. Absent or 0 targets My Library. |
collection | 8-char key | No | Collection key inside the target library. Covers that collection and its descendants. Absent covers the whole library. |
import-all-notes
Imports every child note of a regular item and every standalone note in one library, optionally narrowed to one collection. Opens the same batch confirmation modal as import-notes. It gathers both note kinds, so it carries no mode.
obsidian://zotlit/import-all-notes?source-id=<hash>&library=<groupID>&collection=<key>| Parameter | Type | Required | Description |
|---|---|---|---|
source-id | 8-char hex | Yes | Zotero install identifier |
library | Integer | No | Zotero group ID of the target library. Absent or 0 targets My Library. |
collection | 8-char key | No | Collection key inside the target library. Covers that collection and its descendants. Absent covers the whole library. |
The exact target
library names an exact target for both actions. ZotLit runs that one library, whatever your library scope covers, so a link keeps working for a library you never selected. The same collection key can exist in two libraries; library decides which one the link means.
A link that omits library targets My Library, as it always has. A permanent link written by an earlier ZotLit keeps its meaning.
Two results end the action before any note is written:
- A
librarythis Zotero database no longer holds reports "That Zotero library is not available." - A
collectionthe target library does not hold reports "Collection not found in Zotero."
The Obsidian command palette runs the same two operations without an exact target. Those commands cover every available library in your library scope. See Commands.
explore
Opens the Template Data Explorer anchored on a specific item.
obsidian://zotlit/explore?item=<id>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
item | Integer | Yes | Zotero item ID |
source-id | 8-char hex | Yes | Zotero install identifier |
annotation | 8-char key | No | Zotero annotation key (charset: 23456789A-NP-Z). When provided, the explorer focuses on this annotation. |
Action summary
| Action | Single item | Batch | Scope param | Mode param | Library param |
|---|---|---|---|---|---|
open | yes | — | — | — | — |
update | yes | — | yes | — | — |
update-many | — | yes | yes | — | — |
import-note | yes | — | — | yes | — |
import-notes | — | yes | — | yes | — |
update-all | — | yes | — | — | yes |
import-all-notes | — | yes | — | — | yes |
explore | yes | — | — | — | — |