Attach a file (PDF, snapshot) to an item
zotero_attach_fileAdd a stored file attachment (e.g. a PDF full text) under an existing item. Give parent (the item key) and one of url (Zoteus downloads it, then stores it), path (a file on the machine running Zoteus), or find_oa: true (Zoteus…
Instructions
Add a stored file attachment (e.g. a PDF full text) under an existing item. Give parent (the item key) and one of url (Zoteus downloads it, then stores it), path (a file on the machine running Zoteus), or find_oa: true (Zoteus looks the parent item's DOI up in OpenAlex and attaches the open-access PDF, if there is one). find_oa finds only copies OpenAlex already knows about, which is arXiv, PubMed Central, DOAJ journals and institutional repositories: it is not a way past a paywall, and it says so plainly when there is no free copy. The copy it finds is often the author's accepted or submitted manuscript rather than the published version, so the source, the version and the licence come back in the result and go into the attachment's title. filename and content_type are inferred when omitted. Saves through the Zotero desktop app when one is reachable (Zotero 10+ local API; you may be asked once to allow Zoteus write access, choose "Always Allow"), and otherwise through the cloud Web API, which needs ZOTERO_API_KEY with file access and uses your Zotero file-storage quota. url works on every setup including a remote/hosted Zoteus that cannot see your desktop, so prefer it over path unless the file really is on the server. Returns the new attachment key.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"parent": "<parent>"
},
"name": "zotero_attach_file"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to download the file from; works on remote/hosted servers, where it must be an https link to a public host (no private or loopback addresses, 64 MB at most). | |
| path | No | Filesystem path to the file, on the machine running Zoteus. | |
| title | No | Attachment title, e.g. "Full Text PDF". | |
| parent | Yes | Key of the parent item to attach the file to. | |
| find_oa | No | Find the open-access PDF for the parent item by its DOI (OpenAlex) and attach it. Use instead of `url`/`path`, not alongside them. Refuses, saying why, when the item has no DOI, when OpenAlex reports no open-access copy, when the item already has a PDF, or when what the link serves is not a PDF. | |
| filename | No | File name to store; inferred from path/url if omitted. | |
| library_id | No | Group library to attach the file in (from zotero_groups). Goes to the desktop app when it holds that group (Zotero 10+), otherwise to the cloud. | |
| content_type | No | MIME type; inferred from the extension if omitted (pdf -> application/pdf). | |
| library_type | No | Which library to address: "user" (a personal library) or "group" (a shared group library). Omit to use the library this server is configured for. "group" on its own is refused: pass library_id with it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| oa | No | Where an automatically discovered open-access PDF came from, and what version it is. Present only for find_oa. | |
| bytes | Yes | Size of the stored file. | |
| parent | Yes | The item it hangs off. | |
| target | No | Where the write went: "local" (Zotero desktop local API), "desktop" (connector protocol) or "cloud" (Zotero Web API). | |
| filename | Yes | File name stored. | |
| attachment | Yes | Key of the attachment item created. | |
| contentType | Yes | MIME type stored, e.g. "application/pdf". | |
| alreadyInStorage | No | True when Zotero already held these bytes and only the item was created (cloud path). |