| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v3:write_requests [2021/06/02 16:29] – [Object Keys] dstillman | dev:web_api:v3:write_requests [2024/10/10 02:10] (current) – Keep Zotero-Write-Token before If-Unmodified-Since-Version for now dstillman |
|---|
| | ''400 Bad Request'' | Invalid type/field; unparseable JSON | | | ''400 Bad Request'' | Invalid type/field; unparseable JSON | |
| | ''409 Conflict'' | The target library is locked. | | | ''409 Conflict'' | The target library is locked. | |
| | ''412 Precondition Failed'' | The provided ''Zotero-Write-Token'' has already been submitted. | | | ''412 Precondition Failed'' | The version provided in ''If-Unmodified-Since-Version'' is out of date, or the provided ''Zotero-Write-Token'' has already been submitted. | |
| | ''413 Request Entity Too Large'' | Too many items submitted | | | ''413 Request Entity Too Large'' | Too many items submitted | |
| |
| |
| 204 No Content | 204 No Content |
| Last-Modified-Version: <version> | Last-Modified-Version: <library version> |
| |
| |
| POST <userOrGroupPrefix>/collections | POST <userOrGroupPrefix>/collections |
| Content-Type: application/json | Content-Type: application/json |
| Zotero-Write-Token: <write token> | Zotero-Write-Token: <write token> or If-Unmodified-Since-Version: <last library version> |
| |
| <code>[ | <code>[ |
| | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. | | | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. | |
| | ''409 Conflict'' | The target library is locked. | | | ''409 Conflict'' | The target library is locked. | |
| | ''412 Precondition Failed'' | The provided Zotero-Write-Token has already been submitted. | | | ''412 Precondition Failed'' | The version provided in ''If-Unmodified-Since-Version'' is out of date, or the provided ''Zotero-Write-Token'' has already been submitted. | |
| |
| ==== Updating an Existing Collection ==== | ==== Updating an Existing Collection ==== |
| POST <userOrGroupPrefix>/searches | POST <userOrGroupPrefix>/searches |
| Content-Type: application/json | Content-Type: application/json |
| Zotero-Write-Token: <write token> | Zotero-Write-Token: <write token> or If-Unmodified-Since-Version: <last library version> |
| |
| <code>[ | <code>[ |
| | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. | | | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. | |
| | ''409 Conflict'' | The target library is locked. | | | ''409 Conflict'' | The target library is locked. | |
| | ''412 Precondition Failed'' | The provided Zotero-Write-Token has already been submitted. | | | ''412 Precondition Failed'' | The version provided in ''If-Unmodified-Since-Version'' is out of date, or the provided ''Zotero-Write-Token'' has already been submitted. | |
| |
| ==== Deleting Multiple Searches ==== | ==== Deleting Multiple Searches ==== |
| POST <userOrGroupPrefix>/collections | POST <userOrGroupPrefix>/collections |
| Content-Type: application/json | Content-Type: application/json |
| | Zotero-Write-Token: <write token> or If-Unmodified-Since-Version: <last library version> |
| |
| <code>[ | <code>[ |
| ]</code> | ]</code> |
| |
| For syncing objects with predetermined keys, an object key can also be provided with new objects. See the [[Syncing]] documentation for more information. | For [[syncing]] objects with predetermined keys, an [[#object_keys|object key]] can also be provided with new objects. |
| |
| ''200'' response: | ''200'' response: |
| |
| Content-Type: application/json | Content-Type: application/json |
| Last-Modified-Version: <version> | Last-Modified-Version: <library version> |
| |
| <code>{ | <code>{ |
| ''Zotero-Write-Token'' is 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). 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. | ''Zotero-Write-Token'' is 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). 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. |
| |
| If using versioned write requests (i.e., those that include an ''If-Unmodified-Since-Version'' HTTP header or individual object ''version'' properties), ''Zotero-Write-Token'' is redundant and should be omitted. | If using [[syncing#version_numbers|versioned write requests]] (i.e., those that include an ''If-Unmodified-Since-Version'' HTTP header or individual object ''version'' properties), ''Zotero-Write-Token'' is redundant and should be omitted. |
| |
| ===== Examples ===== | ===== Examples ===== |
| |
| See the [[Syncing]] page for an example workflow that puts together read and write methods for complete and efficient syncing of Zotero data via the API. | See the [[Syncing]] page for an example workflow that puts together read and write methods for complete and efficient syncing of Zotero data via the API. |
Upgrade Storage