zotero-local

name zotero-local description Interact with a local Zotero 8 desktop application through its HTTP API at localhost:23119. Use this skill whenever the user wants to search, fetch, add, edit, or organize bibliographic items in their Zotero library, import citations (BibTeX, RIS, etc.), attach files, manage collections and tags, or retrieve full-text content from Zotero. Triggers on mentions of Zotero, citation management, reference libraries, bibliographic databases, or local library management. Also use when chaining with other catalog skills (Harvard, LOC, HathiTrust, etc.) to save found records into the user's Zotero library. version 1.0.0 Zotero Local API Skill Interact with a running Zotero 8 desktop app via its local HTTP API. Critical: Two API Layers Zotero's local server has two separate API layers with different capabilities: 1. Local API (Read-Only) — /api/... Mirrors the Zotero Web API v3 at http://localhost:23119/api/ . Supports comprehensive read operations but no writes (POST/PUT/PATCH/DELETE all return 400). Uses users/0 for the local user (not the actual user ID) No authentication required All query parameters from the Web API work: q , qmode , sort , direction , limit , start , format , include , itemType , tag , since Supports format=json (default), format=bib , format=citation , format=keys , format=versions , and export formats like format=bibtex 2. Connector API (Write) — /connector/... The connector endpoints handle all write operations: Endpoint What it does POST /connector/saveItems Create items with full metadata, notes, and tags POST /connector/saveSnapshot Save a webpage as a Zotero item POST /connector/import Import BibTeX, RIS, or other bibliographic formats POST /connector/saveAttachment Attach files to existing items POST /connector/saveStandaloneAttachment Save a standalone file attachment POST /connector/saveSingleFile Save SingleFile webpage snapshots POST /connector/updateSession Update tags, target collection for a save session POST /connector/getSelectedCollection Get current library/collection selection POST /connector/installStyle Install citation styles Prerequisites Zotero 8 must be running on the local machine In Zotero preferences: "Allow other applications on this computer to communicate with Zotero" must be enabled The API runs at http://localhost:23119/api/ Common Workflows Search Items GET http://localhost:23119/api/users/0/items?q=keyword&format=json&limit=20 Query parameters: q (search text), qmode (titleCreatorYear or everything), sort (dateAdded, dateModified, title, creator, date), direction (asc/desc), itemType (book, journalArticle, etc.), tag (filter by tag). Get a Specific Item GET http://localhost:23119/api/users/0/items/{itemKey}?format=json Get Item Children (notes, attachments) GET http://localhost:23119/api/users/0/items/{itemKey}/children?format=json Create Items POST http://localhost:23119/connector/saveItems Content-Type: application/json { "items" : [{ "itemType" : "book" , "title" : "The Title" , "creators" : [{ "firstName" : "First" , "lastName" : "Last" , "creatorType" : "author" }], "date" : "2024" , "publisher" : "Publisher Name" , "ISBN" : "978-0-123456-78-9" , "tags" : [{ "tag" : "history" }, { "tag" : "research" }], "notes" : [{ "note" : "<p>My note about this book</p>" }] }], "uri" : "http://example.com" , "sessionID" : "unique-session-id" } The uri and sessionID fields are required by the connector protocol. Use any unique string for sessionID . Import BibTeX/RIS The import endpoint requires a unique session query parameter: POST http://localhost:23119/connector/import?session=unique-id Content-Type: text/plain @book{key2024, author = {Author Name}, title = {Book Title}, year = {2024}, publisher = {Publisher} } Returns the created item(s) as JSON. Without the session parameter, repeated imports return 409 Conflict. Import a PDF into Zotero Upload a PDF as a standalone attachment. Zotero auto-recognizes the document and creates a parent item with extracted metadata (title, authors, DOI, etc.). POST http://localhost:23119/connector/saveStandaloneAttachment Content-Type: application/pdf X-Metadata: { "sessionID" : "unique-id" , "url" : "file:///path/to/file.pdf" , "title" : "file.pdf" } <binary PDF data> Returns {"canRecognize": true} on success (201). Attach a File to an Existing Item Requires the Better BibTeX (BBT) extension for its debug-bridge endpoint. Without BBT, use import_pdf() to import as a standalone item instead. POST http://127.0.0.1:23119/debug-bridge/execute Content-Type: application/javascript var item = await Zotero.Items.getByLibraryAndKeyAsync( Zotero.Libraries.userLibraryID, 'ITEMKEY' ); var att = await Zotero.Attachments.importFromFile({ file: '/path/to/file.pdf' , parentItemID: item.id }); return JSON.stringify({key: att.key}); Download Attached Files Get the local file path for an attachment: GET http://localhost:23119/api/users/0/items/{attachmentKey}/file/view/url Returns a file:// URL pointing to the file in Zotero's storage directory. Or redirect to the file directly (returns 302): GET http://localhost:23119/api/users/0/items/{attachmentKey}/file Get Full-Text Content GET http://localhost:23119/api/users/0/items/{itemKey}/fulltext Returns indexed full-text content for PDFs and other indexed documents. List Collections GET http://localhost:23119/api/users/0/collections?format=json GET http://localhost:23119/api/users/0/collections/top?format=json GET http://localhost:23119/api/users/0/collections/{collectionKey}/items?format=json Create / Delete Collections (requires BBT) These operations use the Better BibTeX debug-bridge. See the "Better BibTeX" section below. z = ZoteroLocal() # Check if BBT is available if not z.check_bbt(): print ( "Install Better BibTeX: https://retorque.re/zotero-better-bibtex/installation/" ) # Create a top-level collection col = z.create_collection( "My Research" ) # Returns: {"key": "ABCD1234", "name": "My Research"} # Create a sub-collection sub = z.create_collection( "Chapter 1" , parent_key=col[ "key" ]) # Returns: {"key": "EFGH5678", "name": "Chapter 1", "parentKey": "ABCD1234"} # Delete a collection (items remain in library) z.delete_collection( "ABCD1234" ) # Delete a collection and trash items only in that collection z.delete_collection( "ABCD1234" , delete_items= True ) List Tags GET http://localhost:23119/api/users/0/tags?format=json Export Citations GET http://localhost:23119/api/users/0/items?format=bibtex GET http://localhost:23119/api/users/0/items/{itemKey}?format=ris GET http://localhost:23119/api/users/0/items?format=bib&style=chicago-author-date Supported export formats: bibtex , ris , csljson , mods , refer , rdf_bibliontology , rdf_dc , rdf_zotero , tei , wikipedia . Execute Saved Searches Unlike the web API, the local API can execute saved searches: GET http://localhost:23119/api/users/0/searches/{searchKey}/items?format=json Item Types Common types: book , bookSection , journalArticle , conferencePaper , thesis , report , webpage , document , manuscript , letter , map , artwork , film , videoRecording , audioRecording , presentation , statute , case , patent , blogPost , forumPost , encyclopediaArticle , dictionaryEntry , newspaperArticle , magazineArticle . Get all types: GET http://localhost:23119/api/itemTypes Get fields for a type: GET http://localhost:23119/api/itemTypeFields?itemType=book Get creator types: GET http://localhost:23119/api/itemTypeCreatorTypes?itemType=book Response Structure Items from the local API return this structure: { "key" : "ABC12345" , "version" : 0 , "library" : { "type" : "user" , "id" : 0 , "name" : "My Library" } , "meta" : { "creatorSummary" : "Author" , "numChildren" : 2 } , "data" : { "key" : "ABC12345" , "itemType" : "book" , "title" : "..." , "creators" : [ ... ] , "date" : "2024" , "publisher" : "..." , "ISBN" : "..." , "tags" : [ { "tag" : "..." } ] , "collections" : [ "COLLKEY1" ] , "dateAdded" : "2024-01-01T00:00:00Z" , "dateModified" : "2024-01-01T00:00:00Z" } } Python Script from scripts.zotero_api import ZoteroLocal z = ZoteroLocal() # connects to localhost:23119 # Search items = z.search( "keyword" , limit= 10 ) # Get item item = z.get_item( "ABC12345" ) # Create book item = z.create_item( "book" , title= "My Book" , creators=[{ "firstName" : "A" , "lastName" : "B" , "creatorType" : "author" }]) # Import BibTeX items = z.import_bibtex( '@book{...}' ) # Import a PDF (auto-recognizes metadata) result = z.import_pdf( "/path/to/paper.pdf" ) # Download an attachment path = z.download_attachment( "ATTKEY12" , "/tmp/" ) # Check if Better BibTeX is available if z.check_bbt(): # Attach file to existing item (requires BBT) z.attach_file( "/path/to/paper.pdf" , "ITEMKEY1" ) # Create/delete collections (requires BBT) col = z.create_collection( "My Collection" ) sub = z.create_collection( "Sub-Collection" , parent_key=col[ "key" ]) z.delete_collection(sub[ "key" ]) # Export bibtex = z.export_items( format = "bibtex" ) Better BibTeX (BBT) Some features require the Better BibTeX extension, which provides a debug-bridge for executing JavaScript inside Zotero. BBT is free and open-source — any user can install it. Features requiring BBT: Creating and deleting collections/sub-collections Attaching files to existing items Check if BBT is installed: z = ZoteroLocal() if z.check_bbt(): print ( "BBT is available" ) else : print ( "Install BBT: https://retorque.re/zotero-better-bibtex/installation/" ) Install BBT: Download the latest .xpi from BBT releases , then in Zotero: Tools → Add-ons → gear icon → Install Add-on From File. Limitations No PATCH/PUT/DELETE : The local API is read-only. Items can only be created through connector endpoints, not updated or deleted programmatically. Connector write format : saveItems requires uri and sessionID wrapper fields around the items array. No item templates : The /api/items/new?itemType= endpoint returns empty on the local API. Use /api/itemTypeFields?itemType= to discover fields instead. Collection management and file attachment : Requires Better BibTeX (BBT) extension. Without BBT, use import_pdf() to import files as standalone items with auto-recognition instead. Resources references/api_reference.md — Complete endpoint reference with all parameters scripts/zotero_api.py — Python client for read and write operations