SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillszotero

zotero

Writing & research

View repository

Updated 10-16 00:01

About this skill

Zotero API Skill

Zotero's local HTTP server (localhost:23119) and REST API (api.zotero.org) to perform bibliographic management operations.

Prerequisites

Local API (only while Zotero is running)

Zotero is running and the following setting is enabled:

  • Zotero > Preferences > Advanced > check "Allow other applications on this computer to communicate with Zotero"

Connection check:

curl -s http://localhost:23119/connector/ping

REST API (cloud operations)

The following environment variables are set:

Connection check:

curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" "https://api.zotero.org/keys/current"

Command

1. Bulk DOI import (/zotero import)

/zotero import <DOI1> <DOI2> ...
/zotero import --file <doi_list.txt>
/zotero import --collection "コレクション名"

Import script:

bash ~/.claude/skills/zotero/scripts/zotero_import.sh --dois "10.1038/xxx,10.2196/yyy" [--collection "名前"]

Processing flow:

  1. Check Zotero is running (/connector/ping）
  2. Identify target collection (use currently selected if not specified)
  3. For each DOI → doi.org Retrieve BibTeX from (CrossRef fallback on failure)
  4. /connector/import?session=<unique_id> に POST
  5. Display result summary

2. Manual BibTeX import (/zotero bibtex)

For literature without a DOI. Import a BibTeX file directly:

bash ~/.claude/skills/zotero/scripts/zotero_import.sh --bibtex /path/to/file.bib

When DOI is unknown, search with the CrossRef API:

curl -s "https://api.crossref.org/works?query.bibliographic=著者名+キーワード&rows=5"

3. Collection list (/zotero collections)

curl -s http://localhost:23119/api/users/0/collections | python3 -c "
import json, sys
for c in json.load(sys.stdin):
    d = c['data']
    print(f\"{d['key']}  {d['name']}\")"

4. Item list (/zotero list)

/zotero list                          # 現在選択中コレクション
/zotero list --collection "名前"      # 指定コレクション

5. Item search (/zotero search)

/zotero search "AI psychosis"

REST API operations

Create collection

curl -s -X POST \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/collections" \
  -d '[{"name": "コレクション名"}]'

Update collection

curl -s -X PUT \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/collections/COLLECTION_KEY" \
  -d '{"name": "新しい名前"}'

Create items (up to 50 per request)

curl -s -X POST \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items" \
  -d '[{
    "itemType": "journalArticle",
    "title": "タイトル",
    "creators": [{"creatorType": "author", "firstName": "名", "lastName": "姓"}],
    "collections": ["COLLECTION_KEY"],
    "tags": [{"tag": "タグ名"}]
  }]'

Partial item update (PATCH)

curl -s -X PATCH \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY" \
  -d '{"tags": [{"tag": "new-tag"}]}'

Delete item

curl -s -X DELETE \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY"

Bulk tag deletion

curl -s -X DELETE \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/tags?tag=tag1+||+tag2"

Group library

All endpoints are simply replaced with /users/<userID> を /groups/<groupID> .

# 所属グループ一覧
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/groups"

Search (REST API)

# キーワード検索
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items?q=keyword&qmode=titleCreatorYear"

# タグフィルタ（AND: 複数 tag、OR: || 区切り、NOT: - 接頭辞）
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items?tag=AI&tag=review"

API overview

Local API

Endpoint Method Purpose
/connector/ping GET/POST Startup check
/connector/import?session=ID POST BibTeX/RIS import
/connector/getSelectedCollection POST Selected collection
/api/users/0/collections GET Collection list
/api/users/0/collections/:key/items GET Item list
/api/users/0/items GET All items

REST API (api.zotero.org)

Endpoint Method Purpose
/users/<id>/collections GET/POST Collection list/create
/users/<id>/collections/<key> PUT/DELETE Collection update/delete
/users/<id>/items GET/POST Item list/create (up to 50)
/users/<id>/items/<key> PUT/PATCH/DELETE Item update/delete
/users/<id>/tags GET Tag list
/users/<id>/tags?tag=... DELETE Bulk tag deletion
/users/<id>/searches GET/POST Saved searches
/users/<id>/items/<key>/file GET/POST/PATCH Attachments
/users/<id>/groups GET Group list
/groups/<id>/... Miscellaneous Group operations

Details: references/api-endpoints.md

Important notes

Local API

  • Local API (/api/...) is GET only (read-only)
  • Connector API (/connector/...) is readable/writable via POST
  • /connector/import の session Parameters areunique each time(duplicates cause a 409 error)
  • If the BibTeX contains shell special characters, --data-binary @file.bib send via file
  • The import destination is the collection selected in the Zotero UI and is saved there

REST API

  • Authentication: Zotero-API-Key: <key> header (recommended)
  • When updating/deleting, If-Unmodified-Since-Version: <version> is required (if unspecified → 428)
  • Batch limit: up to 50 items per request
  • Rate limit: Backoff / 429 + Retry-After based
  • Duplicate submission prevention: Zotero-Write-Token: <token> header