Zotero Server Read API

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

The Read API, part of the Zotero Web API, provides read-only access to online Zotero libraries.

The base URL for all API requests is

https://api.zotero.org

All requests must use HTTPS rather than HTTP.

Every Atom response includes the current API version. Requests may include the version parameter to specify the API version used to interact with the server. After the introduction of a new API version, older API versions will remain available for a yet-to-be-determined period.

Accessing non-public data via the API requires use of an API key. Third-party developers should use OAuth to establish credentials or instruct their users to create dedicated keys for use with their services. End users can create API keys via their Zotero account settings.

Requests for data in a specific library begin with /users/<userID> or /groups/<groupID>. User IDs are different from usernames and can be found on the API Keys page and in OAuth responses.

All parameters are optional.

itemType and tag parameters support Boolean searches:

Examples:

• “itemType=book”
• “itemType=book || journalArticle” (OR)
• “itemType=-attachment” (NOT)

• “tag=foo”
• “tag=foo bar” (tag with space)
• “tag=foo&tag=bar” (AND)
• “tag=foo bar || bar” (OR)
• “tag=-foo” (NOT)
• “tag=\-foo” (literal first-character hyphen)

The following parameters are valid only when accessing a resource that represents a set of objects. For example, /users/123/items represents a set of items, while /users/123/items/ABCD2345 represents a single item.

* Applies to format=atom and format={export_format} only. format=keys has no default or maximum limit.

Note the difference between format=bib and content=bib. format=bib returns a formatted bibliography as XHTML, sorted according to the rules of the selected style. content=bib (valid only for format=atom, the default format mode) returns an individual formatted reference within the Atom <content> block for each item, with the Atom feed sorted according to the query parameters. format=bib processes the entire feed you are requesting without regard for any limit arguments, so it is generally a good idea to use it only with collections or tags.

The following bibliographic data formats can be used as 'format' and 'content' parameters:

Several examples of Read API request URLs and their responses:

The Read API is accompanied by a Write API, which allows for the creation, modification and deletion of items and collections in online Zotero libraries.

Successful GET requests will return a 200 OK status code.

Conditional GET requests using If-Modified-Since or If-Match may return a 304 Not Modified if the requested resource has not changed since the specified time/version. 304 responses may not yet be implemented for all requests.

For any read or write request, the server may return a 400 Bad Request, 404 Not Found, or 405 Method Not Allowed for an invalid request and 500 Internal Server Error or 503 Service Unavailable for a server-related issue. Authentication errors (e.g., invalid API key or insufficient privileges) will return a 403 Forbidden.

Passing an Expect header, which is unsupported, will result in a 417 Expectation Failed response.