Zotero Api

Authentication is optional for reading public libraries but required for accessing private libraries and all write operations. Zotero uses API keys for authentication.

1. Log in to your Zotero account at https://www.zotero.org/
2. Navigate to https://www.zotero.org/settings/keys
3. Create a new API key with appropriate permissions (read/write access to personal or group libraries)
4. Include the key in the Zotero-API-Key header

# Authenticated request
curl -H "Zotero-API-Key: YOUR_API_KEY" "https://api.zotero.org/users/USER_ID/items"

# Public group library (no auth needed)
curl "https://api.zotero.org/groups/GROUP_ID/items"

Your user ID can be found at https://www.zotero.org/settings/keys alongside your API key settings.

Core Endpoints

users/{id}/items: User Library Items

Retrieve, search, and manage items in a user's personal Zotero library.

• URL: GET https://api.zotero.org/users/{userID}/items
• Parameters:

• Example:

# Get all journal articles tagged "machine learning"
curl -H "Zotero-API-Key: YOUR_KEY" \
  "https://api.zotero.org/users/12345/items?itemType=journalArticle&tag=machine+learning&format=json"

# Search for items by keyword
curl -H "Zotero-API-Key: YOUR_KEY" \
  "https://api.zotero.org/users/12345/items?q=neural+networks&format=json"

• Response: Returns array of item objects, each containing key, version, data (with itemType, title, creators, abstractNote, date, DOI, url, tags, collections, relations), and links.

groups/{id}/items: Group Library Items

Access items in shared group libraries, which are commonly used for collaborative research projects and reading groups.

• URL: GET https://api.zotero.org/groups/{groupID}/items
• Parameters:

• Example:

# List items in a public group library
curl "https://api.zotero.org/groups/67890/items?format=json&limit=50"

# Get formatted bibliography from a group
curl "https://api.zotero.org/groups/67890/items?format=bib&style=apa"

• Response: Same structure as user library items. Group items may include additional access control metadata depending on the group's privacy settings.

Rate Limits

No strict rate limits are enforced, but Zotero asks users to limit requests to a reasonable rate. The API uses conditional requests via If-Modified-Since-Version headers for efficient synchronization. Responses include a Last-Modified-Version header that should be stored and used in subsequent requests to only retrieve changed items. Batch operations are supported for creating/updating multiple items in a single request (up to 50 items per write request).

Common Patterns

Export a Bibliography in a Specific Citation Style

Generate a formatted bibliography from a Zotero collection:

import requests

headers = {"Zotero-API-Key": "YOUR_KEY"}

# Get items formatted as APA bibliography
resp = requests.get(
    "https://api.zotero.org/users/12345/collections/ABCDEF/items",
    headers=headers,
    params={"format": "bib", "style": "apa", "limit": 100}
)
print(resp.text)

Sync Library Items to a Custom Database

Efficiently synchronize Zotero items using version tracking:

import requests

headers = {"Zotero-API-Key": "YOUR_KEY"}
last_version = 0  # Store this between syncs

resp = requests.get(
    "https://api.zotero.org/users/12345/items",
    headers={**headers, "If-Modified-Since-Version": str(last_version)},
    params={"format": "json", "limit": 100}
)

if resp.status_code == 200:
    items = resp.json()
    last_version = resp.headers["Last-Modified-Version"]
    for item in items:
        print(f"Updated: {item['data'].get('title', 'No title')} (v{item['version']})")
elif resp.status_code == 304:
    print("No changes since last sync")

Analyze Research Library by Tag Distribution

Explore the thematic distribution of a research library:

import requests
from collections import Counter

headers = {"Zotero-API-Key": "YOUR_KEY"}

resp = requests.get(
    "https://api.zotero.org/users/12345/items",
    headers=headers,
    params={"format": "json", "limit": 100, "itemType": "journalArticle"}
)

tag_counts = Counter()
for item in resp.json():
    for tag in item["data"].get("tags", []):
        tag_counts[tag["tag"]] += 1

for tag, count in tag_counts.most_common(20):
    print(f"  {tag}: {count}")

References

• Official Web API documentation: https://www.zotero.org/support/dev/web_api/v3/basics
• API key management: https://www.zotero.org/settings/keys
• Item types and fields: https://api.zotero.org/itemTypes
• Zotero homepage: https://www.zotero.org/
• Citation styles: https://www.zotero.org/styles