Zotero Server Write API

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

This page documents the write methods of the Zotero Web API. See the Read API page for basic information on accessing the API, including possible HTTP status codes not listed here.

An API key with write access to a given library is necessary to use write methods.

To-do:

• Mappings caching (If-Modified-Since)
• Non-English type/field locales

For an API client to present an editing UI to its users, it must know what combinations of Zotero item types, fields, and creator types are valid. Clients can request this data from the Zotero API.

As schema changes are currently rare, clients should cache type/field data for a period of time (e.g., one hour) without making further requests. Subsequent requests for new data should then include If-Modified-Since headers containing the contents of the Last-Modified header from the original response. If no changes have occurred, the server will return a 304 Not Modified and clients should continue to use cached data for the same period of time.

User-friendly type/field names will be returned in English by default. Clients can request names in other languages by passing a locale parameter (e.g., GET /itemTypes?locale=fr-FR).

Hint: For manual viewing, add pprint=1 to the following requests for easier-to-read output.

GET /itemTypes
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT

[
  { "itemType" : "book", "localized" : "Book" },
  { "itemType" : "note", "localized" : "Note" },
  (…)
]

GET /itemFields
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT

[
  { "field" : "title", "localized" : "Title" },
  { "field" : "url", "localized" : "URL" },
  (…)
]

Note: API consumers intending to write to the server should generally use /items/new combined with /itemTypes instead of this request.

GET /itemTypeFields?itemType=book
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT

[
  { "field" : "title", "localized" : "Title" },
  { "field" : "abstractNote", "localized" : "Abstract" },
  (…)
]

GET /itemTypeCreatorTypes?itemType=book

[
  { "creatorType" : "author", "localized" : "Author" },
  { "creatorType" : "editor", "localized" : "Editor" },
  (…)
]

GET /creatorFields
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT

[
  { "field" : "firstName", "localized" : "First" },
  { "field" : "lastName", "localized" : "Last" },
  { "field" : "name", "localized" : "Name" }
]

GET /items/new?itemType=book
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT

{
  "itemType" : "book",
  "title" : "",
  "creators" : [
    {
      "creatorType" : "author",
      "firstName" : "",
      "lastName" : ""
    }
  ],
  "url" : "",
  (...),
  "tags" : [],
  "notes" : []
}

GET /items/new?itemType=note
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT

{
  "itemType" : "note",
  "note" : "",
  "tags" : []
}

Adding attachments is not yet supported.

POST /users/1/items
Content-Type: application/json
X-Zotero-Write-Token: 19a4f01ad623aa7214f82347e3711f56

{
  "items" : [
    {
      "itemType" : "book",
      "title" : "My Book",
      "creators" : [
        {
          "creatorType":"author",
          "firstName" : "Sam",
          "lastName" : "McAuthor"
        },
        {
          "creatorType":"editor",
          "name" : "John T. Singlefield"
        }
      ],
      "tags" : [
        { "tag" : "awesome" },
        { "tag" : "rad", "type" : 1 }
      ],
      "notes" : [
        {
          "itemType" : "note",
          "note" : "<p>What a <strong>great</strong> book!</p>"
        }
      ]
    }
  ]
}

All fields other than itemType are optional.

Note content will be treated as HTML and sanitized automatically.

Example 201 Created response:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:zapi="http://zotero.org/ns/api">
  <title>Zotero / Zotero User / Items</title>
  <id>http://zotero.org/users/1/items?itemKey=ABCD2345</id>
  <link rel="self" type="application/atom+xml" href="https://api.zotero.org/users/1/items?itemKey=ABCD2345"/>
  <link rel="first" type="application/atom+xml" href="https://api.zotero.org/users/1/items?itemKey=ABCD2345"/>
  <link rel="last" type="application/atom+xml" href="https://api.zotero.org/users/1/items?itemKey=ABCD2345"/>
  <zapi:totalResults>1</zapi:totalResults>
  <zapi:apiVersion>1</zapi:apiVersion>
  <updated>2010-12-17T00:18:51Z</updated>
    <entry>
      <title>My Book</title>
      <author>
          <name>Zotero User</name>
          <uri>http://zotero.org/zuser</uri>
      </author>
      <id>http://zotero.org/users/zuser/items/ABCD2345</id>
      <published>2010-12-17T00:18:51Z</published>
      <updated>2010-12-17T00:18:51Z</updated>
      <link rel="self" type="application/atom+xml" href="https://api.zotero.org/users/1/items/ABCD2345?content=json"/>
      <link rel="alternate" type="text/html" href="http://zotero.org/users/zuser/items/ABCD2345"/>
      <zapi:key>ABCD2345</zapi:key>
      <zapi:itemType>book</zapi:itemType>
      <zapi:creatorSummary>McAuthor</zapi:creatorSummary>
      <zapi:numChildren>1</zapi:numChildren>
      <zapi:numTags>2</zapi:numTags>
      <content type="application/json" etag="8e984e9b2a8fb560b0085b40f6c2c2b7">
        {
          "itemType" : "book",
          "title" : "My Book",
          "creators" : [
            {
              "creatorType" : "author",
              "firstName" : "Sam",
              "lastName" : "McAuthor"
            },
            {
              "creatorType":"editor",
              "name" : "John T. Singlefield"
            }
          ],
          "tags" : [
            { "tag" : "awesome" },
            { "tag" : "rad", "type" : 1 }
          ]
        }
      </content>
    </entry>
</feed>

JSON for multiple items can be passed in the items array. A maximum of 50 items can be added in a single request.

First, retrieve the current version of the item, specifying JSON as the format for the Atom <content> node:

GET /users/1/items/ABCD2345?content=json

See Creating an Item above for an example response.

Next, modify the JSON and resubmit to the server. Include the value of the <content> node's etag attribute in the If-Match HTTP header:

PUT /users/1/items/ABCD2345
Content-Type: application/json
If-Match: "8e984e9b2a8fb560b0085b40f6c2c2b7"

{
  "itemType" : "book",
  "title" : "My Amazing Book",
  "creators" : [
    {
      "creatorType":"author",
      "firstName" : "Sam",
      "lastName" : "McAuthor"
    },
    {
      "creatorType":"editor",
      "name" : "John T. Singlefield"
    }
  ],
  "tags" : [
    { "tag" : "awesome" },
    { "tag" : "rad", "type" : 1 }
  ]
}

All fields other than itemType, creators, and tags are optional. If creators and/or tags are empty, any associated creators and/or tags will be removed from the item.

Child notes can be added only with new items. To add child notes to an existing item, POST an items array containing note items to /users/<userID>/items/<itemKey>/children.

PUT requests must include an If-Match header with an ETag provided by a previous request for the item. If the item has been changed on the server since the item was retrieved, the PUT request will be rejected with a 412 Precondition Failed error, and the most recent version of the item will have to be retrieved from the server before changes can be made.

GET /users/1/items/ABCD2345?content=json

DELETE /users/1/items/ABCD2345
If-Match: "8e984e9b2a8fb560b0085b40f6c2c2b7"

POST /users/1/collections/QRST9876/items

ABCD2345 BCDE3456 CDEF4567 DEFG5678

The POST body is a space-delimited list of item keys from the same library as the collection. Existing items not specified will not be removed from the collection.

Child items cannot be added directly to collections.

DELETE /users/1/collections/QRST9876/items/ABCD2345

POST /users/1/collections
Content-Type: application/json
X-Zotero-Write-Token: 19a4f01ad623aa7214f82347e3711f56

{
  "name" : "My Collection",
  "parent" : "QRST9876"
}

GET /users/1/collections/RSTU8765?content=json

PUT /users/1/collections/RSTU8765
Content-Type: application/json
If-Match: "f0ebb2240a57f4115b3ce841d5218fa2"

{
  "name" : "My Collection",
  "parent" : false
}

GET /users/1/collections/RSTU8765?content=json

DELETE /users/1/collections/RSTU8765
If-Match: "f0ebb2240a57f4115b3ce841d5218fa2"

X-Zotero-Write-Token: 19a4f01ad623aa7214f82347e3711f56

X-Zotero-Write-Token is an optional HTTP header, containing a client-generated identifier string between 8 and 32 characters in length, that can be included with item and collection creation requests to prevent them from being processed more than once (e.g., if a user clicks a form submit button twice). The Zotero server caches write tokens for successful requests for 12 hours, and subsequent requests from the same API key using the same write token will be rejected with a 412 Precondition Failed status code. If a request fails, the write token will not be stored.