<!-- Generated by scripts/generate-llms.mjs from docs/connectors/zotero.md. Do not edit. -->

Source: https://qbash.com/docs/connectors/zotero

# Connect Zotero

Tasks call Zotero through `qbash.integrations.zotero` with an API key and user ID you store on the Connectors page. The connector reads items with their child notes and attachment records, collections and subcollections, tags, saved search definitions, groups and group libraries, My Publications and the key's own privileges. Its writes create items, notes, collections and linked attachment records, update items and collections, and set an item's tags and collections.

The key is the only credential, with no OAuth step and no app to register. A free Zotero account can create a key.

No method deletes anything, empties the trash, replaces a whole item with PUT, uploads a file or changes the key.

After you connect Zotero, you can add its tools to a [qbash MCP server](https://qbash.com/docs-markdown/mcp-servers/overview.md#package) for ChatGPT, Claude and other MCP clients, or call it from a Python task.

## Create the key

1. Register at [zotero.org](https://www.zotero.org/user/register), or log in to your existing account.
2. Open [zotero.org/settings/keys/new](https://www.zotero.org/settings/keys/new).
3. Give the key a name such as "qbash".
4. For the personal library, allow library access. Allow write access only if your tasks add or change things, and allow notes access if they read or write notes.
5. Give group access only if your tasks need a group library, and pick the specific groups. Do not grant access to all groups or to everything.
6. Save the key, then copy it.
7. Open [zotero.org/settings/keys](https://www.zotero.org/settings/keys) and copy the number shown as "Your userID for use in API calls". It is a number, not your username.

## Add the key in qbash

1. Open **Connectors**, then **Zotero**, and click **Connect**.
2. Fill in **Credential Name**, such as "Research library", paste the key into **API Key** and enter the number in **User ID**.
3. Save. qbash asks Zotero which account owns the key and saves the credential only if the key works and belongs to that user ID.
4. In the task editor, choose **Add connector** from the Package **+** menu and select the credential. See [Task resources](https://qbash.com/docs-markdown/tasks/task-editor.md#resources).

## Methods

Every method takes an optional `group_id` to work in a group library instead of your personal one, except where noted. Get group IDs from `list_groups`.

| Resource | Method | Read or write |
| --- | --- | --- |
| Key | `check_key` | Read |
| Items | `list_items` | Read |
| Items | `get_item` | Read |
| Items | `list_child_items` (child notes and attachment metadata) | Read |
| Collections | `list_collections` | Read |
| Collections | `get_collection` | Read |
| Collections | `list_subcollections` | Read |
| Tags | `list_tags` | Read |
| Tags | `list_item_tags` | Read |
| Saved searches | `list_saved_searches` (definitions only) | Read |
| Groups | `list_groups` (personal library only) | Read |
| Groups | `list_group_items` (requires `group_id`) | Read |
| Publications | `list_publication_items` (personal library only) | Read |
| Item types | `list_item_types` | Read |
| Item types | `get_item_template` | Read |
| Items | `create_items` | Write |
| Items | `update_item` | Write |
| Items | `batch_update_items` | Write |
| Collections | `create_collection` | Write |
| Collections | `update_collection` | Write |
| Items | `set_item_tags` | Write |
| Items | `set_item_collections` | Write |
| Items | `create_child_note` | Write |
| Items | `create_child_attachment_metadata` | Write |

The [SDK Reference](https://qbash.com/docs-markdown/tasks/sdk-reference.md) lists each method's parameters and return values.

### What is left out

- **Deletes.** No method deletes items, collections, tags or searches, and `update_item` refuses the `deleted` field, which would move an item to the trash.
- **Whole-item replace.** Zotero's PUT on an item removes every field you leave out. All item updates use PATCH, which changes only the fields you send.
- **File upload and download.** `create_child_attachment_metadata` creates a linked-URL record only. No file is uploaded or fetched.
- **Saved search results, full-text content, exports and citations.** The Web API does not run saved searches, and this connector does not read formatted output.

## Versions and write tokens

Zotero numbers every change with a library version. Each item and collection has its own `version`, and `update_item`, `set_item_tags`, `set_item_collections` and `update_collection` send it as `If-Unmodified-Since-Version`. If the object changed after you read it, Zotero refuses the write with a 412 and the task gets a version conflict error. Read the object again and retry with its new version. `batch_update_items` checks each object's own `version` and reports a stale one in `failed` with code 412, while the others still go through.

`create_items`, `create_collection`, `create_child_note` and `create_child_attachment_metadata` send a `Zotero-Write-Token`. Zotero remembers a token for 12 hours and answers a reused token with a 412, so a repeated call cannot create duplicates. The connector generates a token when you omit `write_token` and returns it as `write_token`. To retry safely after a timeout, pass the same `write_token` again. A 412 on that retry means the first call went through.

Item arrays such as `tags` and `collections` replace the whole list. Read the item first, then send the full list you want.

## Rate limits

The connector sends one request per call and never retries on its own. Zotero answers with a 429 and a `Retry-After` header when you go too fast, and may send a `Backoff` header on any response. A 429 reaches your task as a retryable error that states the wait, for example "Wait 30 seconds". A successful read includes `backoff_seconds` when Zotero asked for one, and the connector then refuses further calls for that key until the wait is over, without sending a request. At most 4 requests run at once across all Zotero keys on a server. A fifth waits a few seconds for a free slot, then fails with a retryable error. A create that fails also names the write token it used, so you can retry with the same token and not create a duplicate.

## Read a collection from a task

```python
result = qbash.integrations.zotero.list_items(
    collection_key="QK7V2N8B",
    top_level=True,
    sort="date",
    direction="asc",
    limit=100,
)
for item in result["items"]:
    qbash.output({"key": item["key"], "title": item.get("title"), "date": item.get("date")})
```

Each item has its fields at the top level, next to `key` and `version`, and `meta` with counts such as `numChildren`. List methods return `next_cursor`, `total_results` and `library_version`. Pass `next_cursor` back as `cursor` until it is `None`.

## Add a note and a tag from a task

```python
item = qbash.integrations.zotero.get_item(item_key="X42A7DEE")["item"]
qbash.integrations.zotero.create_child_note(
    parent_item_key=item["key"],
    note="<p>Read in full. Method section is the useful part.</p>",
)
qbash.integrations.zotero.set_item_tags(
    item_key=item["key"],
    version=item["version"],
    tags=[tag["tag"] for tag in item.get("tags", [])] + ["read"],
)
```
