Zotero / Zotero User / Items

====== Zotero Server Write API ====== **This is version 1 of the Zotero Web API. For new development, use [[:dev/web_api/v3/start|API version 3]].** This page documents the write methods of the [[start|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 ===== 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" },
  (…)
]

[
  { "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 [[#get_template_for_a_new_item|/items/new]] combined with [[#get_all_item_types|/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" },
  (…)
]

[
  { "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" : "What a great book!"
        }
      ]
    }
  ]
}

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:



  Zotero / Zotero User / Items
  http://zotero.org/users/1/items?itemKey=ABCD2345
  
  
  
  1
  1
  2010-12-17T00:18:51Z
    
      My Book
      
          Zotero User
          http://zotero.org/zuser
      
      http://zotero.org/users/zuser/items/ABCD2345
      2010-12-17T00:18:51Z
      2010-12-17T00:18:51Z
      
      
      ABCD2345
      book
      McAuthor
      1
      2
      
        {
          "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 }
          ]
        }

==== 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 '''' node: GET /users/1/items/ABCD2345?content=json See [[#creating_an_item|Creating an Item]] above for an example response. Next, modify the JSON and resubmit to the server. Include the value of the '''' 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//items//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.