[
{ "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 [[#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" },
(…)
]
^ 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" : "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 ''{
"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/{
"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.