Upgrade StorageFeature request: Expose API for programmatic PDF annotation creation (highlights, notes)
Hi everyone,
I'm working on an AI-powered research pipeline that automatically extracts key insights from academic PDFs (using deep-reading models). I'd love to write these extracted insights back into Zotero as PDF annotations (highlights + notes) so users can review them directly in Zotero's PDF reader alongside their manual annotations.
However, after extensive experimentation with Zotero 9.0.5, I've found that there is currently no working way to programmatically create PDF annotations that actually appear in the reader. I wanted to share what I've tried and see if anyone has found a workaround, or if this is a feature gap worth addressing.
What I've tried (all unsuccessful)
1. Zotero.Annotations.saveFromJSON() This internal API exists in the source (chrome/content/zotero/xpcom/data/annotations.js), so I tried calling it from the "Run JavaScript" window:
javascript
Zotero.Annotations.saveFromJSON(attachmentID, {
type: 1, // note annotation
sortIndex: "00001|000001|000072",
text: "AI-extracted insight...",
pageLabel: "3",
color: "#ffd400",
position: JSON.stringify({
pageIndex: 2,
rects: [[100, 200, 400, 220]]
})
});
The call succeeds with no error
Data gets written correctly to the SQLite database (verified via sqlite3)
But the annotations never appear in the PDF reader, and Zotero.Items.get(annotationID) returns nothing
2. new Zotero.Item('annotation') + setField()
setField() rejects annotation-specific fields (annotationType, annotationText, annotationColor) with: "'annotationType' is not a valid itemData field"
Annotation fields live in a separate itemAnnotations table, not in itemData
3. Direct database writes (SQLite)
Wrote complete annotation records to items and itemAnnotations tables
The data is structurally correct and mirrors what Zotero creates when you annotate manually
Still invisible — Zotero's runtime cache apparently doesn't load externally-inserted annotation records
4. Zotero Web API & Local Connector API
The annotation itemType exists in the schema but has fields: [] — no field definitions
Neither the Web API nor the local connector (port 23119) exposes annotation creation endpoints
Related discussion
A user asked essentially the same question on the forums back in August 2025: Programatic Highlighting/Annotation Feature — no replies so far.
Why this matters
A documented annotation API would unlock several valuable workflows:
AI-assisted reading: auto-highlight key passages and attach AI-generated summaries as sticky notes
Cross-tool sync: import annotations from external PDF readers (LiquidText, MarginNote, etc.)
Research automation: programmatically mark evidence, tag findings, create structured annotations
Plugin development: third-party plugins could enrich Zotero's annotation capabilities
What I'm hoping for
Ideally, one or more of the following:
Document Zotero.Annotations.saveFromJSON() — the JSON format, sortIndex specification, and supported annotation types
Expose annotation creation via the Web API — at minimum, POST to create annotation items as children of PDF attachments
Define annotation fields in the schema — currently fields: []; fields like annotationType, annotationText, annotationComment, annotationColor, annotationPageLabel, annotationSortIndex, annotationPosition should be formally defined
Environment
Zotero 9.0.5
Windows 11
Using JavaScript (Zotero internal API) + Python (pyzotero)
Thanks for your time! Happy to provide more details or test any workarounds.
I'm working on an AI-powered research pipeline that automatically extracts key insights from academic PDFs (using deep-reading models). I'd love to write these extracted insights back into Zotero as PDF annotations (highlights + notes) so users can review them directly in Zotero's PDF reader alongside their manual annotations.
However, after extensive experimentation with Zotero 9.0.5, I've found that there is currently no working way to programmatically create PDF annotations that actually appear in the reader. I wanted to share what I've tried and see if anyone has found a workaround, or if this is a feature gap worth addressing.
What I've tried (all unsuccessful)
1. Zotero.Annotations.saveFromJSON() This internal API exists in the source (chrome/content/zotero/xpcom/data/annotations.js), so I tried calling it from the "Run JavaScript" window:
javascript
Zotero.Annotations.saveFromJSON(attachmentID, {
type: 1, // note annotation
sortIndex: "00001|000001|000072",
text: "AI-extracted insight...",
pageLabel: "3",
color: "#ffd400",
position: JSON.stringify({
pageIndex: 2,
rects: [[100, 200, 400, 220]]
})
});
The call succeeds with no error
Data gets written correctly to the SQLite database (verified via sqlite3)
But the annotations never appear in the PDF reader, and Zotero.Items.get(annotationID) returns nothing
2. new Zotero.Item('annotation') + setField()
setField() rejects annotation-specific fields (annotationType, annotationText, annotationColor) with: "'annotationType' is not a valid itemData field"
Annotation fields live in a separate itemAnnotations table, not in itemData
3. Direct database writes (SQLite)
Wrote complete annotation records to items and itemAnnotations tables
The data is structurally correct and mirrors what Zotero creates when you annotate manually
Still invisible — Zotero's runtime cache apparently doesn't load externally-inserted annotation records
4. Zotero Web API & Local Connector API
The annotation itemType exists in the schema but has fields: [] — no field definitions
Neither the Web API nor the local connector (port 23119) exposes annotation creation endpoints
Related discussion
A user asked essentially the same question on the forums back in August 2025: Programatic Highlighting/Annotation Feature — no replies so far.
Why this matters
A documented annotation API would unlock several valuable workflows:
AI-assisted reading: auto-highlight key passages and attach AI-generated summaries as sticky notes
Cross-tool sync: import annotations from external PDF readers (LiquidText, MarginNote, etc.)
Research automation: programmatically mark evidence, tag findings, create structured annotations
Plugin development: third-party plugins could enrich Zotero's annotation capabilities
What I'm hoping for
Ideally, one or more of the following:
Document Zotero.Annotations.saveFromJSON() — the JSON format, sortIndex specification, and supported annotation types
Expose annotation creation via the Web API — at minimum, POST to create annotation items as children of PDF attachments
Define annotation fields in the schema — currently fields: []; fields like annotationType, annotationText, annotationComment, annotationColor, annotationPageLabel, annotationSortIndex, annotationPosition should be formally defined
Environment
Zotero 9.0.5
Windows 11
Using JavaScript (Zotero internal API) + Python (pyzotero)
Thanks for your time! Happy to provide more details or test any workarounds.