Table of Contents

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:

Item Type/Field Requests

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 All Item Types

GET /itemTypes
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT
[
  { "itemType" : "book", "localized" : "Book" },
  { "itemType" : "note", "localized" : "Note" },
  ()
]
Common responses
200 OK
304 Not Modified No changes have occurred since If-Modified-Since time.
400 Bad Request Locale not supported.

Get All Item Fields

GET /itemFields
If-Modified-Since: Mon, 14 Mar 2011 22:30:17 GMT
[
  { "field" : "title", "localized" : "Title" },
  { "field" : "url", "localized" : "URL" },
  ()
]
Common responses
200 OK
304 Not Modified No changes have occurred since If-Modified-Since time.
400 Bad Request Locale not supported.

Get All Valid Fields for an Item Type

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" },
  ()
]
Common responses
200 OK
304 Not Modified No changes have occurred since If-Modified-Since time.
400 Bad Request Locale not supported.

Get Valid Creator Types for an Item Type

GET /itemTypeCreatorTypes?itemType=book
[
  { "creatorType" : "author", "localized" : "Author" },
  { "creatorType" : "editor", "localized" : "Editor" },
  ()
]
Common responses
200 OK
304 Not Modified No changes have occurred since If-Modified-Since time.
400 Bad Request 'itemType' is unspecified or invalid; locale not supported.

Get Localized Creator Fields

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" }
]
Common responses
304 Not Modified No changes have occurred since If-Modified-Since time.
400 Bad Request Locale not supported.

Get Template for a New Item

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.

Common responses
200 OK
304 Not Modified No changes have occurred since If-Modified-Since time.
400 Bad Request itemType is unspecified or invalid.

Write Requests

Creating an Item

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.

Common responses
201 Created Item(s) successfully created — see example Atom response below
400 Bad Request Invalid type/field; unparseable JSON
409 Conflict The target library is locked.
412 Precondition Failed The provided X-Zotero-Write-Token has already been submitted.
413 Request Entity Too Large Too many items submitted

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>

Creating Multiple Items

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

Updating an Existing Item

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.

Common responses
200 OK Same as Atom response above, but with updated data.
400 Bad Request Invalid type/field; unparseable JSON; client did not include ETag.
409 Conflict The target library is locked.
412 Precondition Failed The item has changed since retrieval (i.e., the provided ETag no longer matches).

Deleting an Item

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

DELETE /users/1/items/ABCD2345
If-Match: "8e984e9b2a8fb560b0085b40f6c2c2b7"
Common responses
204 No Content The item was deleted.
409 Conflict The target library is locked.
412 Precondition Failed The item has changed since retrieval (i.e., the provided ETag no longer matches).

Adding Items to a Collection

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.

Common responses
204 No Content Items were added to collection.
400 Bad Request Item not found in library; attempt to add child item to collection.
409 Conflict The target library is locked.

Removing an Item from a Collection

DELETE /users/1/collections/QRST9876/items/ABCD2345
Common responses
204 No Content Item was removed from the collection.
409 Conflict The target library is locked.

Creating a Collection

POST /users/1/collections
Content-Type: application/json
X-Zotero-Write-Token: 19a4f01ad623aa7214f82347e3711f56
{
  "name" : "My Collection",
  "parent" : "QRST9876"
}
Common responses
201 Created The collection was created.
409 Conflict The target library is locked.
412 Precondition Failed The provided X-Zotero-Write-Token has already been submitted.

Updating an Existing Collection

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

PUT /users/1/collections/RSTU8765
Content-Type: application/json
If-Match: "f0ebb2240a57f4115b3ce841d5218fa2"
{
  "name" : "My Collection",
  "parent" : false
}
Common responses
200 OK The collection was updated.
409 Conflict The target library is locked.
412 Precondition Failed The collection has changed since retrieval (i.e., the provided ETag no longer matches).

Deleting a Collection

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

DELETE /users/1/collections/RSTU8765
If-Match: "f0ebb2240a57f4115b3ce841d5218fa2"
Common responses
204 No Content The collection was deleted.
409 Conflict The target library is locked.
412 Precondition Failed The collection has changed since retrieval (i.e., the provided ETag no longer matches).

X-Zotero-Write-Token

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.