This is an old revision of the document!
Version 3 of the Zotero Web API introduces a new all-JSON response format and various other changes. While API v3 is mostly backwards compatible, existing clients may need to make a few small adjustments for full compatibility, depending on usage.
Changes in API v3
- New default all-JSON response format,
format=json
- Contains a single JSON object for single-object requests and an array of objects for multi-object requests
- All individual objects contain top-level
key
andversion
properties and top-levellibrary
,links
, andmeta
objects. meta
contains non-editable system-generated properties likecreatedByUser
/lastModifiedByUser
(for group items),creatorSummary
, andnumChildren
.- Other Atom-specific feed properties (
title
,author
,published
,updated
) have been removed.
- The
parsedDate
property in theformat=json
meta
object gives the full parsed date in YYYY-MM-DD form, so that clients don't need to replicate Zotero's date-parsing logic to get exact dates. In v3 Atom,zapi:parsedDate
replaceszapi:year
. - For
format=json
,include=data
has replaced Atom'scontent=json
and is now the default mode, with a top-leveldata
object containing the editable fields. As withcontent
, additional comma-separated types can be requested (e.g.,include=data,bib
). The requested types are provided as top-level properties.content=html
remains the default in Atom. zapi:numTags
is removed in v3 Atom, since it's unnecessary with thetags
array in the editable json.- The total result count for multi-object responses is available in a new custom HTTP header,
Total-Results
.zapi:totalResults
is removed in v3 Atom. rel=first
/prev
/next
/last
/alternate
links for multi-object responses are now provided in theLink
HTTP header.- The API key can be provided in the
Authorization
request header instead of thekey
query parameter. Since API keys have never been included in the URLs provided in responses, previously all provided URLs had to be modified for key-based access. - The API version can be provided as a query parameter (
v=3
) instead of theZotero-API-Version
header for easier debugging and sharing of requests, though both will remain supported. - For formats other than Atom,
dateModified
descending is the default sort instead ofdateAdded
descending. itemKey
/itemVersion
(and similar properties on collections and searches) in the editable JSON are now justkey
andversion
for easier handling by clients. Clients that simply pass back the edited JSON without touching those properties shouldn't be affected. Clients that store the JSON will need to modify it before sending in v3.- The
version
metadata field in thecomputerProgram
item type is nowversionNumber
to avoid a conflict with the renamed object version property. - dateAdded/dateModified are included in the 'data' object in ISO 8601 form. Previously these timestamps were provided only in the Atom
published
/updated
elements, though in v2 they can be sent back in the JSON asdateAdded
/dateModified
in SQL DATETIME format, interpreted as UTC. In v3 write requests, either is accepted, though SQL DATETIME is deprecated. - The
accessDate
field, which was also previously an SQL DATETIME, is ISO 8601 in v3 (including in Atom) for both reading and writing. SQL DATETIME is accepted but deprecated. - The pagination links (
rel=self
/first
/prev
/next
/last
) on multi-object responses can be used without modification by clients using theAuthorization
header. Therel=self
links in individual objects are meant as base URIs and do not include any query parameters (e.g.,include=data,bib
). This is a change from the previous behavior, where the Atom entryrel=“self”
links include all non-default provided parameters. But with theAuthorization
header andinclude=data
as the new default, the base URI may be sufficient for most individual-object requests. - The
newer
parameter is nowsince
for clarity.newer
is deprecated. - The
order
parameter is nowsort
andsort
is nowdirection
.order=<field>
andsort=<asc/desc>
are deprecated. - Requests for updated group metadata can now use
format=versions
instead offormat=etags
.format=etags
is deprecated. pprint=1
has been removed, and all responses are now pretty-printed.- '<', '>', and '&' are no longer unnecessarily escaped to \u…. in returned JSON data. In Atom, these characters are instead turned into XML numeric character references. Proper XML and JSON parsers shouldn't be affected by these changes.
- The HTTP Warning header may be used to send clients non-fatal warnings — such as deprecation warnings — that can be logged.
- New recommendation: Clients that store editable JSON should save the current API version alongside the JSON. When the clients are later updated for an API version that changes how passed JSON is handled, they will need to make changes to the stored JSON or retrieve it again before sending it up.
tl;dr for existing Atom consumers
- Use
zapi:parsedDate
instead ofzapi:year
- Use
Total-Results
HTTP header instead ofzapi:totalResults
- Count the
tags
array in content JSON instead of usingzapi:numTags
- Use
key
/version
instead ofitemKey
/itemVersion
(andcollection*
/search*
) in content JSON - Use
versionNumber
instead ofversion
metadata field incomputerProgram
item type - Use ISO 8601 dates for
accessDate
,dateAdded
, anddateModified
- Use
since
parameter instead ofnewer
- Use
sort
parameter instead oforder
anddirection
instead ofsort
- Optionally, use
Authorization: Bearer <apiKey>
instead ofkey
parameter - Use
v
parameter instead ofZotero-API-Version
for debugging