====== Zotero Server Read API ====== **This is version 1 of the Zotero Web API. For new development, use [[:dev/web_api/v2/start|API version 3]].** The Read API, part of the [[start|Zotero Web API]], provides read-only access to online Zotero libraries. ===== Base URL ===== The base URL for all API requests is https://api.zotero.org All requests must use HTTPS rather than HTTP. ===== API Versioning ===== 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. ===== Authentication ===== Accessing non-public data via the API requires use of an API key. Third-party developers should [[oauth|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 [[/settings/keys/new|their Zotero account settings]]. ===== GET Requests ===== Requests for data in a specific library begin with ''/users/'' or ''/groups/''. User IDs are different from usernames and can be found on the [[/settings/keys|API Keys]] page and in OAuth responses. ==== Requests for "/users/" or "/groups/" ==== ^ URI ^ Description ^ | /items | The set of all items in the library | | /items/top | The set of all top-level items in the library | | /items/trash | The set of items in the trash | | /items/ | A specific item in the library | | /items//children | The set of all child items under a specific item | | /items//tags | The set of all tags associated with a specific item | | /tags | The set of all tags in the library | | /tags/ | The set of tags (i.e., of all types) matching a specific name | | /collections | The set of collections in the library | | /collections/top | The set of all top-level collections in the library | | /collections/ | A specific collection in the library | | /collections//collections | The set of subcollections within a specific collection in the library | | /collections//items | The set of items within a specific collection in the library | | /collections//tags | The set of tags within a specific collection in the library | ==== Requests Specific to "/users/" ==== |< 100% 30% >| ^ URI ^ Description ^ | /users//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//keys/ | The privileges of the given API key. | ===== URL Parameters ===== All parameters are optional. ==== Parameters for All Requests ==== ^ Parameter ^ Values ^ Default ^ Description ^ | format | "atom", "bib", "keys", [[#export_formats|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 only for multi-item requests, will return a newline-separated list of item keys. "keys" 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. | | 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.| | version | integer | null | If a developer wishes to use a version of the API other than the latest available version, they can pass the desired version. If the requested method is no longer supported for the passed version, the server will return an error message and an HTTP status code of 400. | ==== Search Parameters ==== ^ Parameter ^ Values ^ Default ^ Description ^ | 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|search syntax]] | null | Item type search | | tag | [[#search_syntax|search syntax]] | search syntax | Tag search | ==== Search Syntax ==== ''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) ==== Parameters for "format=atom", "format=keys", and "format={export_format}" ==== 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. ^ Parameter ^ Values ^ Default ^ Description ^ | 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 ''order'' parameter | | limit | integer 1-100* | 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=atom and format={export_format} only. format=keys has no default or maximum limit. ==== Parameters for "format=atom" and "format={export_format}" ==== ^ Parameter ^ Values ^ Default ^ Description ^ | pprint | boolean | false | format=atom: Outputs the response with content type "text/xml" instead of "application/atom+xml" and adds a long comment before to disable Firefox's feed auto-detection.\\ format={export_format}: Outputs the response with content type "text/plain" for easier display in browsers. | ==== Parameters for "format=atom" ==== ^ Parameter ^ Values ^ Default ^ Description ^ | content | "html", "json", "bib", [[#export_formats|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 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, will contain multiple elements (in the %%http://zotero.org/ns/api%% namespace), each with a zapi:type attribute matching one of the specified content parameters. | ==== Parameters for "format=bib" and "content=bib" ==== ^ Parameter ^ Values ^ Default ^ Description ^ | 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'' 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 '''' 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. ==== Export Formats ==== The following bibliographic data formats can be used as 'format' and 'content' parameters: ^ Parameter ^ Description ^ | bibtex | BibTeX | | bookmarks | Netscape Bookmark Format | | coins | COinS | | csljson | [[https://github.com/citation-style-language/schema/blob/master/csl-data.json|Citation Style Language data format]] | | mods | MODS | | refer | Refer/BibIX | | rdf_bibliontology | [[http://bibliontology.com/|Bibliographic Ontology]] RDF | | rdf_dc | Unqualified Dublin Core RDF | | rdf_zotero | Zotero RDF | | ris | RIS | | tei | Text Encoding Initiative (TEI) | | wikipedia | Wikipedia Citation Templates | ===== Example Requests and Responses ===== Several examples of Read API request URLs and their responses: ^ Atom feed - List of items in collection ^^ | Request | https://api.zotero.org/users/475425/collections/9KH9TNSJ/items?format=atom | | Response | https://gist.github.com/923206 | ^ Atom feed - Single item ^^ | Request | https://api.zotero.org/users/475425/items/X42A7DEE?format=atom | | Response | https://gist.github.com/1489999 | ^ Atom feed - Single item with all possible content^^ | Request | https://api.zotero.org/users/475425/items/X42A7DEE?format=atom&content=json,bib,html | | Response | https://gist.github.com/2794754 | ^ Atom feed - List of collections for a user ^^ | Request | https://api.zotero.org/users/475425/collections?format=atom | | Response | https://gist.github.com/1492705 | ^ Formatted bibliography ^^ | Request | https://api.zotero.org/users/475425/collections/9KH9TNSJ/items?format=bib | | Response | https://gist.github.com/923201 | ===== Write API ===== 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. ===== HTTP Status Codes ===== 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.