Protocol links
Every obsidian://zotlit/* action and its parameters, and the Zotero open links ZotLit opens in Obsidian's reader.
This page documents every obsidian://zotlit/* protocol action. These deep links allow ZotLit Companion, the Zotero add-on, and external tools such as scripts and launchers to trigger ZotLit operations in Obsidian.
It also documents which zotero:// links ZotLit opens in Obsidian's reader when you click them in a note. See Zotero open links.
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.
If the Zotero database is not yet loaded, ZotLit shows Open the Zotero database to handle this link..
Where the link opens
Four actions put something in front of you: open, update, explore, and open-attachment. Each takes an optional paneType, spelled as Obsidian's own URI links spell it.
| Value | Result |
|---|---|
tab | Opens a new tab. |
split | Opens a new tab group. |
window | Opens a pop-out window. Desktop only. |
obsidian://zotlit/open?item=<id>&source-id=<hash>&paneType=tabOmit the parameter to keep each action's usual placement: open, update, and open-attachment replace the last active tab, and explore reuses the Template Data Explorer already in the sidebar. A value outside the three shows Invalid ZotLit protocol link. and stops the action.
ZotLit Companion writes the parameter onto the links its own Zotero menus open. Under the Opening in Obsidian section of the ZotLit pane in Zotero's settings, Open notes in picks the pane. Active tab, the default, leaves the parameter off the 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 |
profile | 12-char id | No | The profile that creates or updates the note, named by profile ID. |
paneType | Pane value | No | Where the note opens: tab, split, or window. See Where the link opens. |
profile picks the profile the action resolves the note against. The note is created with that profile when none exists yet. A note that already exists keeps the profile it carries. A link naming a different profile reports the profile the note kept and changes nothing.
The value is 12 letters or digits, the id its profile document declares, never a label. Omit the parameter to resolve the profile the usual way. An unknown ID shows a notice and stops the action.
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. |
profile | 12-char id | No | The profile that creates or updates the note, named by profile ID. |
paneType | Pane value | No | Where the note opens: tab, split, or window. See Where the link opens. |
profile names the profile for the item. The update runs through the profile the note carries. A link naming a different profile reports the profile the note kept and skips the update. When the item has no note yet, the note is created with the named profile.
The value is 12 letters or digits, the id its profile document declares. An unknown ID shows a notice and stops the action.
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 |
profile | 12-char id | No | The profile for the notes the batch creates. |
profile is the companion profile of the batch. Every note the batch creates is created with it. A note that already exists keeps its own profile; the batch reports those notes as kept rather than re-rendering them. The value is 12 letters or digits, the id its profile document declares. An unknown ID shows a notice and stops the batch.
For batches too large for a URL, ZotLit also exposes PUT {host} /literature-notes with the same parameters in the request body, profile
included, 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. |
paneType | Pane value | No | Where the explorer opens: tab, split, or window. See Where the link opens. |
open-attachment
Opens a Zotero PDF attachment in Obsidian's own PDF reader.
obsidian://zotlit/open-attachment?item=<id>&source-id=<hash>| Parameter | Type | Required | Description |
|---|---|---|---|
item | Integer | Yes | Zotero item ID, naming either a PDF attachment or a regular item that has one |
source-id | 8-char hex | Yes | Zotero install identifier |
paneType | Pane value | No | Where the PDF opens: tab, split, or window. See Where the link opens. |
item may name an attachment directly or the regular item it hangs from; ZotLit decides which it found and resolves the PDF from there. One PDF opens straight away. Several open a picker that lists them by file name.
Only PDF attachments are offered; the action passes over EPUBs, web snapshots, and other file types. An item with no PDF shows This item has no PDF attachment. A PDF whose file is no longer on disk shows The PDF file is missing. Neither case falls back to Zotero's own reader.
The PDF opens whether the file sits inside the vault or in Zotero's storage folder.
Action summary
| Action | Single item | Batch | Scope param | Mode param | Library param | profile param | paneType param |
|---|---|---|---|---|---|---|---|
open | yes | — | — | — | — | yes | yes |
update | yes | — | yes | — | — | yes | yes |
update-many | — | yes | yes | — | — | yes | — |
import-note | yes | — | — | yes | — | — | — |
import-notes | — | yes | — | yes | — | — | — |
update-all | — | yes | — | — | yes | — | — |
import-all-notes | — | yes | — | — | yes | — | — |
explore | yes | — | — | — | — | — | yes |
open-attachment | yes | — | — | — | — | — | yes |
profile belongs to the literature-note actions: open, update, and update-many, whose PUT {host}/literature-notes body carries it too. The note-import actions take none. paneType belongs to the actions that put something on screen: open, update, explore, and open-attachment. Every other action ends in a notice or a confirmation modal rather than an opened pane, so it takes none.
Zotero open links
Every annotation ZotLit writes into a note links back with its durable link. That link is Zotero's own open link, naming the attachment and the annotation by their Zotero keys:
zotero://open/library/items/<attachmentKey>?annotation=<annotationKey>&page=<pageLabel>A group library has groups/<groupID> in place of library. page is the annotation's printed page label, and the link omits it when there is none. The template field is zt.backlink.
The link appears wherever ZotLit writes an annotation: Insert into note on an annotation view card, a card dragged from the annotation view, a query block, or the Query View, and the default annotation template. The placeholder for an unavailable excerpt image links back the same way.
Opened in Obsidian
While Settings > ZotLit > Reader > Open PDF file links in Obsidian and Settings > ZotLit > Reader > Open annotation links in ZotLit reader are on, which is the default, ZotLit opens a durable annotation link in Obsidian's reader. The PDF opens with the annotation selected and scrolled into view. This applies to a link clicked in Live Preview, in Reading view, or in a Properties value.
When Zotero no longer has the annotation, the PDF opens on the annotation's page alone. If that annotation's page label differs from the PDF's page number, the page jump can miss.
Passed to Zotero
ZotLit hands the link to Zotero, unchanged, in these cases:
| Case | Result |
|---|---|
| The PDF is not on this computer, or ZotLit does not know the attachment | Zotero opens the annotation. |
| Open PDF file links in Obsidian is off | Zotero opens the annotation. |
| Open annotation links in ZotLit reader is off | Zotero opens the annotation. Hover shows it. |
| You right-click the link and choose Open in default browser | Zotero opens the annotation. |
A zotero://open link with no annotation parameter | Zotero handles it. ZotLit never captures it. |
A zotero://select link | Zotero handles it. ZotLit never captures it. |
Older file links
Notes written by an earlier ZotLit link an annotation to the attachment file instead, in the form file:///…/paper.pdf#page=N&zt-annotation=<key>. These links keep opening in Obsidian's reader on the annotation, as before. They hold the file path of the computer that wrote them, so they open nothing on a computer whose Zotero storage folder sits elsewhere. See Open an item's PDF in Obsidian.
See also
Last updated on