This is not currently the default version of the API. Include the Zotero-API-Version: 3 HTTP header or the v=3 query parameter to access this version.

The page documents read requests available in the Zotero Web API, providing 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.

To use this version of the API, include the Zotero-API-Version: 3 HTTP header or the v=3 query parameter with all requests. The current default version is version 1, which will be discontinued.

At most times, API changes are made in a backwards-compatible manner. On rare occasions, however, backwards-incompatible changes may need to be made. When this occurs, the new API version will first be made available via the Zotero-API-Version HTTP header or v query parameter, while other clients will continue to receive the old version. After a transition period, the new API version will become the default. If an API version is discontinued, clients requesting the discontinued version will receive the oldest available version. Announcements regarding API version transitions will always be made ahead of time on zotero-dev.

The API version of a response will be returned in the Zotero-API-Version response header.

Authentication is not required for read access to public libraries.

Accessing non-public libraries 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.

API keys can be included in requests in one of two ways:

1. As an HTTP header, in the form Authentication: Bearer P9NiFoyLeZu2bZNvvuQPDWsd
   
2. As a URL query parameter, in the form key=P9NiFoyLeZu2bZNvvuQPDWsd

Use of the Authentication header is recommended, as it will allow use of URLs returned from the API (e.g., for pagination) without modification.

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.

The following parameters are valid for all requests:

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)

Be sure to URL-encode search strings if required by your client or library.

The following parameters are valid only for multi-object requests such as /users/123/items, with the exception of format=bib requests, which do not support sorting or pagination.

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

For efficient usage of the API, clients should make conditional GET requests whenever possible. If If-Modified-Since-Version: <libraryVersion> is passed with a multi-object read request (e.g., /users/1/items) and data has not changed in the library since the specified version, the API will return 304 Not Modified. If If-Modified-Since-Version: <objectVersion> is passed with a single-object read request (e.g., /users/1/items/ABCD2345), a 304 Not Modified will be returned if the individual object has not changed.

While a conditional GET request that returns a 304 should be fast, some clients may wish or need to perform additional caching on their own, using stored data for a period of time before making subsequent conditional requests to the Zotero API. This makes particular sense when the underlying Zotero data is known not to change frequently or when the data will be accessed frequently. For example, a website that displayed a bibliography from a Zotero collection might cache the returned bibliography for an hour, after which time it would make another conditional request to the Zotero API. If the API returned a 304, the website would continue to display the cached bibliography for another hour before retrying. This would prevent the website from making a request to the Zotero API every time a user loaded a page.

[Not all rate limits are currently enforced, but clients should be prepared to handle them.]

Clients accessing the Zotero API should be prepared to handle two forms of rate limiting: backoff requests and hard limiting.

If the API servers are overloaded, the API may include a Backoff: <seconds> HTTP header in responses, indicating that the client should perform the minimum number of requests necessary to maintain data consistency and then refrain from making further requests for the number of seconds indicated. Backoff can be included in any response, including successful ones.

If a client has made too many requests within a given time period, the API may return 429 Too Many Requests with a Retry-After: <seconds> header. Clients receiving a 429 should wait the number of seconds indicated in the header before retrying the request.

Retry-After can also be included with 503 Service Unavailable responses when the server is undergoing maintenance.

TODO

The API also supports write requests that allow the creation, modification, and deletion of data in Zotero libraries.

Successful GET requests will return a 200 OK status code.

Conditional GET requests may return 304 Not Modified.

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.

Library/object versioning or Zotero-Write-Token errors will result in 412 Precondition Failed or 428 Precondition Required.

429 Too Many Requests indicates that the client has been rate-limited.