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

AnAPI keywith write access to a given library is necessary to use write methods.

By default, objects returned from the API informat=jsonmode include adataproperty containing "editable JSON" — that is, all the object fields that can be modified and sent back to the server:

{   "key": "ABCD2345",   "version": 1,   "library": { ...},   "links": { ...},   "meta": { ...188BET靠谱吗},   "data": {     "key": "ABCD2345",     "version": 1,     "itemType": "webpage",     "title": "Zotero Quick Start Guide",     "creators": [         {             "creatorType": "author",             "name": "Center for History and New Media"         }     ],     "abstractNote": "",     "websiteTitle": "Zotero",     "websiteType": "",     "date": "",     "shortTitle": "",     "url": "//www.brodersterzo.com/support/quick_start_guide",     "accessDate": "2014-06-12T21:28:55Z",     "language": "",     "rights": "",     "extra": "",     "dateAdded": "2014-06-12T21:28:55Z",     "dateModified": "2014-06-12T21:28:55Z",     "tags": [],     "collections": [],     "relations": {}   } }

There are two ways to make changes to the provided JSON:

For programmatic access to the API, the recommended approach is to extract the editable JSON from thedataproperty, make changes as necesssary, and upload just the editable JSON back to the API.For new items, anempty templateof the editable JSON can be retrieved from the API.

This approach reduces upload bandwidth by sending only the data that is actually processed by the server.(For an even more efficient upload, the HTTPPATCHmethod, discussed below, can be used to send only the fields that have changed.) The examples in this documentation assume programmatic access.

For more casual access, the API supports standard REST behavior, allowing the entire downloaded JSON to be reuploaded.This allows edits to be performed without writing a single line of code:

188BET靠谱吗$ URL="https://api.zotero.org/users/1234567/items" $ API_KEY="P9NiFoyLeZu2bZNvvuQPDWsd" $ curl -H "Zotero-API-Key: $API_KEY" $URL > items.json $ vi items.json  # edit the item data $ curl -H "Zotero-API-Key: $API_KEY" -d @items.json -v $URL

In this example, a JSON array of items is being saved to a text file, modified in a text editor, and then POSTed back to the same URL.

This approach allows a complicated task such as batch editing to be performed using only cURL and a text editor.Any objects modified in the text file will be updated on the server, while unmodified objects will be left unchanged.

A similar process can be used with PUT for individual objects:

188BET靠谱吗$ URL="https://api.zotero.org/users/1234567/items/ABCD2345" $ API_KEY="P9NiFoyLeZu2bZNvvuQPDWsd" $ curl -H "Zotero-API-Key: $API_KEY" $URL > item.json $ vi items.json  # edit the item data $ curl -H "Zotero-API-Key: $API_KEY" -X PUT -d @item.json -v $URL

Note that when uploading full JSON, only thedataproperty is processed.All other properties (library,links,meta, etc.) are ignored.

When creating a new item, first get empty JSON for the item type with anitem template request(or use a cached version of the template).Then modify it and resubmit it to the server in an array:

POST
        
         188BET靠谱吗/items Content-Type: application/json Zotero-Write-Token:
         
          or If-Unmodified-Since-Version:
          
         
        

[   {     "itemType" : "book",     "title" : "My Book",     "creators" : [       {         "creatorType":"author",         "firstName" : "Sam",         "lastName" : "McAuthor"       },       {         "creatorType":"editor",         "name" : "John T.188BET靠谱吗Singlefield"       }     ],     "tags" : [       { "tag" : "awesome" },       { "tag" : "rad", "type" : 1 }     ],     "collections" : [       "BCDE3456", "CDEF4567"     ],     "relations" : {       "owl:sameAs" : "//www.brodersterzo.com/groups/1/items/JKLM6543",       "dc:relation" : "//www.brodersterzo.com/groups/1/items/PQRS6789",       "dc:replaces" : "//www.brodersterzo.com/users/1/items/BCDE5432"     }   } ]

All properties other thanitemType,tags,collections, andrelationsare optional.

200 OKresponse:

{   "success": {     "0": "
        
         "   },   "unchanged": {},   "failed": {},   } }
        

SeeCreating Multiple Objectsfor more information on the response format.

SeeCreating Multiple Objects.

To update an existing item, first retrieve the current version of the item:

GET
        
         /items/
         
        

The editable data, similar to the item data shown above inCreating an Item, will be found in thedataproperty in the response.

The API supports two ways of modifying item data: by uploading full item data (PUT) or by sending just the data that changed (PATCH).

WithPUT, you submit the item's complete editable JSON to the server, typically by modifying the downloaded editable JSON — that is, the contents of thedataproperty — directly and resubmitting it:

PUT
        
         /items/
         
          Content-Type: application/json
         
        

{   "key": "ABCD2345",   "version": 1,   "itemType" : "book",   "title" : "My Amazing Book",   "creators" : [     {       "creatorType":"author",       "firstName" : "Sam",       "lastName" : "McAuthor"     },     {       "creatorType":"editor",       "name" : "Jenny L.188BET靠谱吗Singlefield"     }   ],   "tags" : [     { "tag" : "awesome" },     { "tag" : "rad", "type" : 1 }   ],   "collections" : [     "BCDE3456", "CDEF4567"   ],   "relations" : {     "owl:sameAs" : "//www.brodersterzo.com/groups/1/items/JKLM6543",     "dc:relation" : "//www.brodersterzo.com/groups/1/items/PQRS6789",     "dc:replaces" : "//www.brodersterzo.com/users/1/items/BCDE5432"   } }

All properties other thanitemType,tags,collections, andrelationsare optional.Any existing fields not specified will be removed from the item.Ifcreators,tags,collections, orrelationsare empty, any associated creators/tags/collections/relations will be removed from the item.

WithPATCH, you can submit just the properties that have actually changed, for a potentially much more efficient operation.Properties not included in the uploaded JSON are left untouched on the server.To clear a property, pass an empty string or an empty array as appropriate.

PATCH
        
         /items/
         
          If-Unmodified-Since-Version:
          
         
        

{   "date" : "2013"   "collections" : [     "BCDE3456", "CDEF4567"   ] }

This would add adatefield to the item and add it in the two specified collections if not already present.Array properties are interpreted as complete lists, so omitting a collection key would cause the item to be removed from that collection.

ThePATCHbehavior is also available whenmodifying multiple itemsviaPOST.

Notes and attachments can be made child items by assigning the parent item's key to theparentItemproperty.If parent and child items are created in the samePOSTrequest, the child items must appear after the parent item in the array of items, with a locally createditem key.

The item's current version number is included in theversionJSON property, as well as in theLast-Modified-Versionheader of single-item requests.PUTandPATCHrequests must include the item's current version number in either theversionproperty or theIf-Unmodified-Since-Versionheader.(versionis included in responses from the API, so clients that simply modify the editable data do not need to bother with a version header.) If the item has been changed on the server since the item was retrieved, the write request will be rejected with a412 Precondition Failederror, and the most recent version of the item will have to be retrieved from the server before changes can be made.SeeVersion Numbersfor more on library and object versioning.

SeeUpdating Multiple Objects.

DELETE
        
         /items/
         
          If-Unmodified-Since-Version:
          
         
        

Up to 50 items can be deleted in a single request.

DELETE
        
         /items?itemKey=
         
          ,
          
           ,
           
            If-Unmodified-Since-Version:
            
           
          
         
        

204 No Content Last-Modified-Version:
        

POST
        
         188BET靠谱吗/collections Content-Type: application/json Zotero-Write-Token:
         
        

[   {     "name" : "My Collection",     "parentCollection" : "QRST9876"   } ]

GET
        
         /collections/
         
        

Editable JSON will be found in thedataproperty.

PUT
        
         /collections/
         
          Content-Type: application/json
         
        

{   "key" : "DM2F65CA",   "version" : 156,   "name" : "My Collection",   "parentCollection" : false }

Items can be added to or removed from collections via thecollectionsproperty in the item JSON.

DELETE
        
         /collections/
         
          If-Unmodified-Since-Version:
          
         
        

Up to 50 collections can be deleted in a single request.

DELETE
        
         /collections?collectionKey=
         
          ,
          
           ,
           
            If-Unmodified-Since-Version:
            
           
          
         
        

204 No Content Last-Modified-Version:
        

POST
        
         188BET靠谱吗/searches Content-Type: application/json Zotero-Write-Token:
         
        

[   {     "name": "My Search",     "conditions": [       {         "condition": "title",         "operator": "contains",         "value": "foo"       },       {         "condition": "date",         "operator": "isInTheLast",         "value": "7 days"       }     ]   } ]

Up to 50 searches can be deleted in a single request.

DELETE
        
         /searches?searchKey=
         
          ,
          
           ,
           
            If-Unmodified-Since-Version:
            
           
          
         
        

204 No Content Last-Modified-Version:
        

Up to 50 tags can be deleted in a single request.

DELETE
        
         /tags?tag=
         
          ||
          
           ||
           
            If-Unmodified-Since-Version:
            
           
          
         
        

204 No Content Last-Modified-Version:
        

Up to 50 collections, saved searches, or items can be created in a single request by including multiple objects in an array:

POST
        
         /collections Content-Type: application/json
        

[   {     "name" : "My Collection",     "parentCollection": "QRST9876"   },   {     "name": "My Other Collection"   } ]

Forsyncingobjects with predetermined keys, anobject keycan also be provided with new objects.

200response:

Content-Type: application/json Last-Modified-Version:
        

{   "successful": {     "0": "
        
         ",     "2": "
         
          "   },   "unchanged": {     "4": "
          
           "   }   "failed": {     "1": {       "key": "
           
            ",       "code":
            
             ,       "message": "
             
              "     },     "3": {       "key": "
              
               ",       "code":
               
                ,       "message": "
                
                 "     },   } }
                
               
              
             
            
           
          
         
        

The keys of thesuccessful,unchanged, andfailed188BET靠谱吗objects are the numeric indexes of the Zotero objects in the uploaded array.TheLast-Modified-Version188BET靠谱吗is the version that has been assigned to any Zotero objects in thesuccessfulobject — that is, objects that were modified in this request.

Up to 50 collections, saved searches, or items can be updated in a single request.

Follow the instructions inCreating Multiple Objects, but include akeyandversionproperty in each object.If modifying editable JSON returned from the API, these properties will already exist and shouldn't be modified.As an alternative to individualversionproperties, the last-known library version can be passed via theIf-Unmodified-Since-VersionHTTP Header.

Items can also includedateAddedanddateModifiedproperties containing timestamps inISO 8601 format(e.g., "2014-06-10T13:52:43Z").IfdateAddedis included with an existing item, it must match the existingdateAddedvalue or else the API will return a 400 error.If a newdateModifiedtime is not included with an update to existing item, the item'sdateModifiedvalue will be set to the current time.Editable JSON returned from the API includesdateAddedanddateModifiedin the correct format, so clients that are content with server-set modification times can simply ignore these properties.

POST
        
         /collections Content-Type: application/json
        

[   {     "key": "BD85JEM4",     "version": 414,     "name": "My Collection",     "parentCollection": false   },   {     "key": "MNC5SAPD",     "version": 416     "name": "My Subcollection",     "parentCollection": "BD85JEM4"   } ]

The response is the same as that inCreating Multiple Objects.

Note thatPOSTfollowsPATCHsemantics, meaning that any properties not specified will be left untouched on the server.To erase an existing property, include it with an empty string orfalseas the value.

While the server will automatically generate valid keys for uploaded objects, in some situations, such as whensyncingor creating a parent and child item in the same request, it may be desirable or necessary to create object keys locally.

Local object keys should conform to the pattern/[23456789ABCDEFGHIJKLMNPQRSTUVWXYZ]{8}/.

188BET靠谱吗Zotero-Write-Token: 19a4f01ad623aa7214f82347e3711f56

188BET靠谱吗Zotero-Write-Tokenis an optional HTTP header, containing a client-generated random 32-character identifier string, that can be included with unversioned write requests to prevent them from being processed more than once (e.g., if a user clicks a form submit button twice).188BET靠谱吗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 a412 Precondition Failedstatus code.If a request fails, the write token will not be stored.

If using versioned write requests (i.e., those that include anIf-Unmodified-Since-VersionHTTP header or individual objectversionproperties),188BET靠谱吗Zotero-Write-Tokenis redundant and should be omitted.

See theSyncing188BET靠谱吗page for an example workflow that puts together read and write methods for complete and efficient syncing of Zotero data via the API.