This is not currently the default version of the Zotero API. Include the HTTP header
Zotero-API-Version: 2 to access this version.
The page documents read requests available in the Zotero Server API, providing read-only access to online Zotero libraries.
The base URL for all API requests is
All requests must use HTTPS rather than HTTP.
To use this version of the API, include the HTTP header
Zotero-API-Version: 2 with all requests. The current default version is version 1, which will be discontinued in the near future.
At most times, there is only one active API version, and 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 an HTTP header,
Zotero-API-Version: <version>, while all other clients continue to receive the old version. After a transition period, the new API version will become the default. At that point, the previous API version may be discontinued, with the new API version being returned even to clients requesting the previous 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.
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
/groups/<groupID>. User IDs are different from usernames and can be found on the API Keys page and in OAuth responses.
|<userOrGroupPrefix>/items||The set of all items in the library|
|<userOrGroupPrefix>/items/top||The set of all top-level items in the library|
|<userOrGroupPrefix>/items/trash||The set of items in the trash|
|<userOrGroupPrefix>/items/<itemKey>||A specific item in the library|
|<userOrGroupPrefix>/items/<itemKey>/children||The set of all child items under a specific item|
|<userOrGroupPrefix>/items/<itemKey>/tags||The set of all tags associated with a specific item|
|<userOrGroupPrefix>/tags||The set of all tags in the library|
|<userOrGroupPrefix>/tags/<url+encoded+tag>||The set of tags (i.e., of all types) matching a specific name|
|<userOrGroupPrefix>/collections||The set of collections in the library|
|<userOrGroupPrefix>/collections/top||The set of all top-level collections in the library|
|<userOrGroupPrefix>/collections/<collectionKey>||A specific collection in the library|
|<userOrGroupPrefix>/collections/<collectionKey>/collections||The set of subcollections within a specific collection in the library|
|<userOrGroupPrefix>/collections/<collectionKey>/items||The set of all items within a specific collection in the library|
|<userOrGroupPrefix>/collections/<collectionKey>/items/top||The set of top-level items within a specific collection in the library|
|<userOrGroupPrefix>/collections/<collectionKey>/tags||The set of tags within a specific collection in the library|
|<userOrGroupPrefix>/searches||The set of all saved searches in the library|
|<userOrGroupPrefix>/searches/<searchKey>||A specific saved search in the library|
|/users/<userID>/groups||The set of groups the current API key has access to, including public groups the key owner belongs to even if the key doesn't have explicit permissions for it.|
|/users/<userID>/keys/<key>||The privileges of the given API key.|
All parameters are optional.
|format||“atom”, “bib”, “keys”, “versions”, export formats||“atom”|| “atom” will return an Atom feed.
“bib”, valid only for item requests, will return a formatted bibliography as XHTML. “bib” mode is currently limited to a maximum of 150 items.
“keys”, valid for multi-object requests, will return a newline-separated list of object keys. “keys” mode has no default or maximum limit.
“versions”, valid for multi-object collection, item, search, and tag requests, will return a JSON object with Zotero object keys as keys and object versions as values. Like “keys”, “versions” mode has no default or maximum limit.
Export formats, valid only for item requests, produce output in the specified format. The 'limit' parameter is required for multi-item export format requests.
|newer||integer||0||Return only objects modified after the specified library verson.|
|key||string||null||If a valid API key is provided, the request will be processed with the identity of the key's owner and the authority granted to the key.|
|itemKey||string||null||A comma-separated list of item keys. Valid only for item requests. Up to 50 items can be specified in a single request.|
|q||string||null||Field search. Currently searches titles and individual creator fields|
|itemType||search syntax||null||Item type search|
|tag||search syntax||search syntax||Tag search|
tag parameters support Boolean searches:
- “itemType=-attachment” (NOT)
- “tag=foo bar” (tag with space)
- “tag=foo&tag=bar” (AND)
- “tag=foo bar
- “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.
|order||“dateAdded”, “dateModified”, “title”, “creator”, “type”, “date”, “publisher”, “publicationTitle”, “journalAbbreviation”, “language”, “accessDate”, “libraryCatalog”, “callNumber”, “rights”, “addedBy”, “numItems” (tags)||dateAdded||The name of the field by which entries are ordered|
|sort||“asc”, “desc”||varies by “order”|| The sorting direction of the field specified in the
|limit||integer 1-99*||50*||The maximum number of results to return with a single request. Required for export formats.|
|start||integer||0||The index of the first result. Combine with the limit parameter to select a slice of the available results.|
* Applies to
format=versions have no default or maximum limit.
|pprint||boolean||false|| Pretty print the response:
|content|| “html”, “json”, “bib”, export formats, “none”|
Multiple formats can be specified by using a comma as the delimiter (“content=json,bib”).
|“html”|| The format of the Atom response's <content> node:
“html” (the default) will return an XHTML representation of each object, useful for display in feed readers and for parsing by XML tools.
“json”, currently valid only for item and collection requests, will return a JSON representation of all the item's fields.
“bib”, valid only for item requests, will return a formatted reference for each item.
Export formats, valid only for item requests, will return data in the specified format for each item.
If additional data is not required, use “none” to decrease the response size.
If multiple formats are requested, <content> will contain multiple <zapi:subcontent> elements (in the http://zotero.org/ns/api namespace), each with a zapi:type attribute matching one of the specified content parameters.
|style||string||“chicago-note-bibliography”||Citation style to use for formatted references. Should be the file name (without the ”.csl” extension) of one of the default styles in the Zotero Style Repository (e.g., “apa” for http://www.zotero.org/styles/apa). Support for other styles is forthcoming.|
Note the difference between
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:
|bookmarks||Netscape Bookmark Format|
|csljson||Citation Style Language data format|
|rdf_bibliontology||Bibliographic Ontology RDF|
|rdf_dc||Unqualified Dublin Core RDF|
|tei||Text Encoding Initiative (TEI)|
|wikipedia||Wikipedia Citation Templates|
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.,
<userOrGroupPrefix>/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.,
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 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. For example, a web page 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 web page would continue to display the cached bibliography for another hour before retrying.
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.
Several examples of read request URLs and their responses:
|Atom feed - List of items in collection|
|Response||https://gist.github.com/923206 (Not updated for API v2)|
|Atom feed - Single item|
|Atom feed - Single item with all possible content|
|Atom feed - List of collections for a user|
|Response||https://gist.github.com/1492705 (Not updated for API v2)|
These requests can be performed from the command line:
curl -H 'Zotero-API-Version: 2' 'https://api.zotero.org/users/475425/collections/9KH9TNSJ/items?format=atom' curl -H 'Zotero-API-Version: 2' 'https://api.zotero.org/users/475425/items/X42A7DEE?format=atom' curl -H 'Zotero-API-Version: 2' 'https://api.zotero.org/users/475425/items/X42A7DEE?format=atom&content=json,bib,html' curl -H 'Zotero-API-Version: 2' 'https://api.zotero.org/users/475425/collections?format=atom' curl -H 'Zotero-API-Version: 2' 'https://api.zotero.org/users/475425/collections/9KH9TNSJ/items?format=bib'
The API also supports write requests that allow the creation, modification, and deletion of data in online 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
Expect header, which is unsupported, will result in a
417 Expectation Failed response.
429 Too Many Requests indicates that the client has been rate-limited.