This is version 1 of the Zotero Web API. For new development, use API version 3.

In addition to providing ways to read and write online library data, the Zotero Web API allows you to upload attachment files.

The exact process depends on whether you are adding a new attachment file or modifying an existing one and whether you are performing a full upload or uploading a binary diff.

GET /items/new?itemType=attachment&linkMode={imported_file,imported_url,linked_file,linked_url}

{
  "itemType": "attachment",
  "linkMode": "imported_url",
  "title": "",
  "accessDate": "",
  "url": "",
  "note": "",
  "tags": [],
  "contentType": "",
  "charset": "",
  "filename": "",
  "md5": null,
  "mtime": null
}

POST /users/<userID>/items/<parentItemKey>/children
Content-Type: application/json
X-Zotero-Write-Token: <token>

{
  "items": [
    {
      "itemType": "attachment",
      "linkMode": "imported_url",
      "title": "My Document",
      "accessDate": "2012-03-14 17:45:54",
      "url": "http://example.com/doc.pdf",
      "note": "",
      "tags": [],
      "contentType": "",
      "charset": "",
      "filename": "",
      "md5": null,
      "mtime": null
    }
  ]
}

contentType, charset, filename, md5, and mtime can be edited directly in personal libraries for WebDAV-based file syncing. They cannot be edited directly in group libraries and should not be edited directly in personal libraries using Zotero File Storage, which provides an atomic method (detailed below) for setting the properties along with the corresponding file.

Child attachments can also be created along with new top-level items by including the attachment object in the attachments array of the new item's metadata.

Top-level attachments can be created by POSTing to <userOrGroupPrefix>/items. As in the Zotero client, only file attachments and PDFs—not HTML snapshots or web links—can be added as top-level items.

GET /users/<userID>/items/<itemKey>?content=json

...
{
  "itemType": "attachment",
  "linkMode": "imported_file",
  "title": "My Document",
  "note": "",
  "tags": []
  "contentType": "text/plain",
  "charset": "utf-8",
  "filename": "doc.txt",
  "md5": "4fa38e3f2c360ca181e633d02bab91f5",
  "mtime": "1331171741767"
}
</content>

GET /users/<userID>/items/<itemKey>/file

Check the ETag header of the response to make sure it matches the attachment item's md5 value. If it doesn't, check the attachment item again. If the attachment item still has a different hash, the latest version of the file may be available only via WebDAV, not via Zotero File Storage, and it is up to the client how to proceed.

Save the file as filename and set the modification time to the mtime provided in the attachment item.

Note that to perform a faster partial upload using a binary diff, you must save a copy of the file before changes are made.

POST /users/<userID>/items/<itemKey>/file
Content-Type: application/x-www-form-urlencoded
If-None-Match: *

md5=<hash>&filename=<filename>&filesize=<bytes>&mtime=<milliseconds>[&contentType=<type>&charset=<charset>]

For existing attachments, use If-Match: <hash> in place of If-None-Match: *, where <hash> is the previous MD5 hash of the file (as provided in the ETag header when downloading it).

Note that mtime must be provided in milliseconds, not seconds.

A successful 200 response returns one of two possible JSON objects:

{
  "url": ...,
  "contentType": ...,
  "prefix": ...,
  "suffix": ...,
  "uploadKey": ...
}

or

{ "exists": 1 }

In the latter case, the file already exists on the server and was successfully associated with the specified item. No further action is necessary.

Concatenate prefix, the file contents, and suffix and POST to url with the Content-Type header set to contentType.

'prefix' and 'suffix' are strings containing multipart/form-data. In some environments, it may be easier to work directly with the form parameters. Add params=1 to the upload authorization request above to retrieve the individual parameters in a params array, which will replace contentType, prefix, and suffix.

POST /users/<userID>/items/<itemKey>/file
Content-Type: application/x-www-form-urlencoded
If-None-Match: *

upload=<uploadKey>

For existing attachments, use If-Match: <hash>, where <hash> is the previous MD5 hash of the file, provided as the md5 property in the attachment item.

After the upload has been registered, the attachment item will reflect the new metadata.

PATCH /users/<userID>/items/<itemKey>/file?algorithm={xdelta,vcdiff,bsdiff}&upload=<uploadKey>
If-Match: <previous-value-of-md5-property>

<Binary diff of old and new versions>

For best results, we recommend using Xdelta version 3 with the “-9 -S djw” flags. bsdiff takes significantly longer to generate diffs. 'vcdiff' is an alias for 'xdelta', as Xdelta3 can process diffs in VCDIFF format.

Clients may wish to automatically fall back to a full upload—possibly with some form of warning—if HTTP PATCH is not supported by a user's proxy server (indicated, in theory, by a 405 Method Not Allowed).

After the upload has finished, the attachment item will reflect the new metadata.