K-Dense-AI/scientific-agent-skills / skills/pyzotero
pyzotero
VerifiedManages Zotero reference libraries using the pyzotero Python client: retrieves, creates, updates, and deletes items, collections, tags, and attachments via the Zotero Web API v3 or local API. Applies when working with Zotero libraries programmatically, managing bibliographic references, exporting citations, searching library contents, uploading PDF attachments, or building research automation workflows that integrate with Zotero.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| references/authentication.md | markdown | 5.1 KB |
| references/cli.md | markdown | 3.7 KB |
| references/collections.md | markdown | 3.8 KB |
| references/error-handling.md | markdown | 3.9 KB |
| references/exports.md | markdown | 3.9 KB |
| references/files-attachments.md | markdown | 4.3 KB |
| references/full-text.md | markdown | 2.4 KB |
| references/mcp.md | markdown | 6.1 KB |
| references/pagination.md | markdown | 2.4 KB |
| references/read-api.md | markdown | 4.3 KB |
| references/saved-searches.md | markdown | 3.6 KB |
| references/search-params.md | markdown | 3.7 KB |
| references/tags.md | markdown | 2.6 KB |
| references/write-api.md | markdown | 5.6 KB |
references/write-api.md
View on GitHub# Write API Methods
## Creating Items
For the remote API, use `item_template()` to get a valid template. The local API lacks `/items/new`; build data from the type/field endpoints instead (see [authentication.md](authentication.md)). All write examples below are illustrative and must use an authorized target library.
```python
# Get a template for a specific item type
template = zot.item_template('journalArticle')
# Fill in fields
template['title'] = 'Example article (illustrative metadata)'
template['date'] = '2024'
# Populate DOI, title, journal, and authors together from a verified source;
# never pair a real DOI with fabricated bibliographic metadata.
template['creators'] = [
{'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'},
{'creatorType': 'author', 'firstName': 'John', 'lastName': 'Smith'},
]
# Validate fields before creating (raises InvalidItemFieldsError if invalid)
zot.check_items([template])
# Create the item
resp = zot.create_items([template])
# Response maps are indexed by each input's string index: '0', '1', ...
if resp.get('failed'):
raise RuntimeError(f"Creation failures: {resp['failed']}")
new_key = resp['successful']['0']['key']
# successful holds saved objects; legacy success maps indices to keys.
# unchanged maps indices to existing keys when no change was needed.
```
### Create Multiple Items at Once
```python
templates = []
for data in paper_data_list:
t = zot.item_template('journalArticle')
t['title'] = data['title']
t['DOI'] = data['doi']
templates.append(t)
for start in range(0, len(templates), 50):
resp = zot.create_items(templates[start:start + 50])
if resp.get('failed'):
raise RuntimeError(f"Batch starting at {start}: {resp['failed']}")
```
### Create Child Items
```python
# Create a note as a child of an existing item
note_template = zot.item_template('note')
note_template['note'] = '<p>My annotation here</p>'
zot.create_items([note_template], parentid='PARENTKEY')
```
## Updating Items
```python
# Retrieve, modify, update
item = zot.item('ITEMKEY')
item['data']['title'] = 'Updated Title'
item['data']['abstractNote'] = 'New abstract text.'
success = zot.update_item(item) # returns True or raises error
# Update many existing items while retaining per-item status
items = zot.items(itemType='journalArticle', limit=10)
for item in items:
item['data']['extra'] = item['data'].get('extra', '') + '\nProcessed'
for start in range(0, len(items), 50):
result = zot.create_items([i['data'] for i in items[start:start + 50]])
if result.get('failed'):
raise RuntimeError(result['failed'])
```
## Deleting Items
```python
# Permanent deletion of one item: use its object version
item = zot.item('ITEMKEY')
zot.delete_item(item)
# Multiple deletion uses a LIBRARY version, not the first item's version.
# Review the exact selected keys first; at most 50 per request.
items = zot.items(tag='to-delete', limit=50)
library_version = int(zot.request.headers['Last-Modified-Version'])
if items:
zot.delete_item(items, last_modified=library_version)
# To trash instead of permanently delete:
item = zot.item('ITEMKEY')
item['data']['deleted'] = 1 # use 0 to restore
zot.update_item(item['data'])
```
## Item Types and Fields
```python
# All available item types
item_types = zot.item_types()
# [{'itemType': 'artwork', 'localized': 'Artwork'}, ...]
# All available fields
fields = zot.item_fields()
# Valid fields for a specific item type
journal_fields = zot.item_type_fields('journalArticle')
# Valid creator types for an item type
creator_types = zot.item_creator_types('journalArticle')
# [{'creatorType': 'author', 'localized': 'Author'}, ...]
# All localised creator field names
creator_fields = zot.creator_fields()
# Attachment link modes (needed for attachment templates)
link_modes = zot.item_attachment_link_modes()
# Template for an attachment
attach_template = zot.item_template('attachment', linkmode='imported_file')
```
## Optimistic Locking
Single-item `last_modified` is the **item version**. The normal read/modify/write example already sends it; an explicit override must come from that same item's read:
```python
# Only update if this item's version still matches
zot.update_item(item, last_modified=item['version'])
# Raises PreConditionFailedError on a stale version.
```
## Notes
- `create_items()` accepts up to 50 items per call; batch if needed.
- `update_items()` auto-chunks at 50 but returns a coarse Boolean without checking each `failed` mapping in 1.15.2. Use `create_items()` with keyed, versioned data in explicit batches when every result must be reconciled.
- If a dict passed to `create_items()` contains a `key` matching an existing item, it will be updated rather than created.
- `check_items()` checks field names against the global field set, not all type-specific values or scientific metadata. Server failures remain possible.
- Item `PATCH` leaves omitted fields unchanged, but supplied arrays replace entire creator/tag/collection lists. Re-fetch after writes before further edits.
- A timeout does not establish whether a write happened. Pyzotero generates a new write token on another `create_items()` call, so blindly repeating an unkeyed create can duplicate records. Reconcile first; retry only verified failures.
- Batch POST preconditions use the library version when supplied; per-object `version` values are usually simpler. HTTP 200 can still contain failed entries.
Sources: [write request/response contracts](https://www.zotero.org/support/dev/web_api/v3/write_requests), [Pyzotero 1.15.2 source](https://github.com/urschrei/pyzotero/blob/v1.15.2/src/pyzotero/_client.py).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |