Zotero API client

A lightweight, minimalistic Zotero API client developed in JavaScript with the following goals in mind:

• Small, single purpose module, i.e. talk to the API
• Works in both node & browser environment
• No abstraction over Zotero data, what you see is what you get
• Clean api
• Small bundle footprint
• Minimal request validation
• Predictable and consistent responses
• Full test coverage

It doesn't do any of the following:

• Version management - version headers need to be provided explictely
• Caching - each call to get(), post() etc. will actually call the api
• Abstraction - There is no Item or Collection objects, only raw JSON

Getting The Library

NPM package contains source of the library which can be used as part of your build (e.g. when using browserify/rollup/webpack etc.) process or directly in node:

npm install zotero-api-client

Also included in the package is an UMD bundle which can be loaded using common loaders or included directly in a `

Example
=======

Simple example reading items from the public/test user library.

1. Import the library, pick one depending on your environment:

```javascript
// es module, most scenarios when using a bundler:
import api from 'zotero-api-client'
// common-js, node and some cases when using a bundler:
const { default: api } = require('zotero-api-client');
// UMD bundle creates `ZoteroApiClient` global object
const { default: api } = ZoteroApiClient;

2. Use the api to make the request (we're using async functions)

const response = await api().library('user', 475425).collections('9KH9TNSJ').items().get();

3. Extract items from the response

const items = response.getData();

4. Print titles of all the items in the library to console

console.log(items.map(i => i.title));

Overview

Library composes of three layers:

• An api function, which is the only interface exported.
• A request engine called by the api. It does the heavy lifting. Should not be used directly.
• An ApiResponse, which has multiple specialised variants

API interface

API interface is a function that returns set of functions bound to previously configured options. This way it can be chained and stored at any level. Common scenario is to store authentication details and library details, which can be done quite simply:

import api from 'zotero-api-client';
const myapi = api('AUTH_KEY').library('user', 0);

That produces api client already configured with your credentials and user library id. You can re-use it obtain list of collections in that library:

const itemsResponse = await myapi.items().get();

Items in that library:

const itemsResponse = await myapi.collections().get();

Or items in specific collection:

const collectionItemsResponse = await myapi.collections('EXAMPLE1').items().get();

There two types of api functions, configuration functions (e.g. items()) that can be further chained and execution functions (e.g. get()) that fire up the request.

For complete reference, please see documentation for api().

Response

Response is an instance of a specialised response class object returned by one of the execution functions of the api. Each response contains a specialised getData() method that will return entities requested or modified, depending on request configuration.

For complete reference, please see documentation SingleReadResponse, MultiReadResponse, SingleWriteResponse, MultiWriteResponse, DeleteResponse, FileUploadResponse, FileDownloadResponse, FileUrlResponse.

Request

Request is a function that takes a complex configuration object generated by the api interface, communicates with the API and returns one of the response objects (see below). Some rarely used properties cannot be configured using api configuration functions and have to be specified as optional properties when calling api() or one of the execution functions of the api.

For a complete list of all the properties request() accepts, please see documentation for request().

API Reference

• zotero-api-client
  • ~ApiResponse
    • .getResponseType() ⇒ string
    • .getData() ⇒ object
    • .getLinks() ⇒ object
    • .getMeta() ⇒ object
    • .getVersion() ⇒ number
  • ~SingleReadResponse ⇐ ApiResponse
    • .getResponseType()
    • .getData() ⇒ Object
  • ~MultiReadResponse ⇐ ApiResponse
    • .getResponseType()
    • .getData() ⇒ Array
    • .getLinks() ⇒ Array
    • .getMeta() ⇒ Array
    • .getTotalResults() ⇒ string
    • .getRelLinks() ⇒ object
  • ~SingleWriteResponse ⇐ ApiResponse
    • .getResponseType()
    • .getData() ⇒ Object
  • ~MultiWriteResponse ⇐ ApiResponse
    • .getResponseType()
    • .isSuccess() ⇒ Boolean
    • .getData() ⇒ Array
    • .getLinks()
    • .getMeta()
    • .getErrors() ⇒ Object
    • .getEntityByKey(key)
    • .getEntityByIndex(index) ⇒ Object
  • ~DeleteResponse ⇐ ApiResponse
    • .getResponseType()
  • ~FileUploadResponse ⇐ ApiResponse
    • .getResponseType()
    • .getVersion()
  • ~FileDownloadResponse ⇐ ApiResponse
    • .getResponseType()
  • ~FileUrlResponse ⇐ ApiResponse
    • .getResponseType()
  • ~RawApiResponse ⇐ ApiResponse
    • .getResponseType()
  • ~PretendResponse ⇐ ApiResponse
    • .getResponseType()
    • .getVersion() ⇒ Object
  • ~ErrorResponse ⇐ Error
    • .getVersion() ⇒ number
    • .getResponseType()
  • ~api() ⇒ Object
    • ~api(key, opts) ⇒ Object
    • ~library([typeOrKey], [id]) ⇒ Object
    • ~items(items) ⇒ Object
    • ~itemTypes() ⇒ Object
    • ~itemFields() ⇒ Object
    • ~creatorFields() ⇒ Object
    • ~schema() ⇒ Object
    • ~itemTypeFields(itemType) ⇒ Object
    • ~itemTypeCreatorTypes(itemType) ⇒ Object
    • ~template(itemType, subType) ⇒ Object
    • ~collections(items) ⇒ Object
    • ~subcollections() ⇒ Object
    • ~publications() ⇒ Object
    • ~tags(tags) ⇒ Object
    • ~searches(searches) ⇒ Object
    • ~top() ⇒ Object
    • ~trash() ⇒ Object
    • ~children() ⇒ Object
    • ~settings(settings) ⇒ Object
    • ~deleted() ⇒ Object
    • ~groups() ⇒ Object
    • ~version(version) ⇒ Object
    • ~attachment([fileName], [file], [mtime], [md5sum], patch, [algorithm]) ⇒ Object
    • ~registerAttachment(fileName, fileSize, mtime, md5sum) ⇒ Object
    • ~attachmentUrl() ⇒ Object
    • ~verifyKeyAccess() ⇒ Object
    • ~get(opts) ⇒ Promise
    • ~post(data, opts) ⇒ Promise
    • ~put(data, opts) ⇒ Promise
    • ~patch(data, opts) ⇒ Promise
    • ~del(keysToDelete, opts) ⇒ Promise
    • ~getConfig() ⇒ Object
    • ~pretend(verb, data, opts) ⇒ Promise
    • ~use(extend) ⇒ Object
  • ~request() ⇒ Object

zotero-api-client~ApiResponse

Represents a generic Zotero API response. Usually a specialised variant inheriting from this class is returned when doing an API request

Kind: inner class of zotero-api-client

• ~ApiResponse
  • .getResponseType() ⇒ string
  • .getData() ⇒ object
  • .getLinks() ⇒ object
  • .getMeta() ⇒ object
  • .getVersion() ⇒ number

apiResponse.getResponseType() ⇒ string

Name of the class, useful to determine instance of which specialised class has been returned

Kind: instance method of ApiResponse
Returns: string - name of the class

apiResponse.getData() ⇒ object

Content of the response. Specialised classes provide extracted data depending on context.

Kind: instance method of ApiResponse

apiResponse.getLinks() ⇒ object

Links available in the response. Specialised classes provide extracted links depending on context.

Kind: instance method of ApiResponse

apiResponse.getMeta() ⇒ object

Meta data available in the response. Specialised classes provide extracted meta data depending on context.

Kind: instance method of ApiResponse

apiResponse.getVersion() ⇒ number

Value of "Last-Modified-Version" header in response if present. Specialised classes provide version depending on context

Kind: instance method of ApiResponse
Returns: number - Version of the content in response

zotero-api-client~SingleReadResponse ⇐ ApiResponse

Represents a response to a GET request containing a single entity

Kind: inner class of zotero-api-client
Extends: ApiResponse

• ~SingleReadResponse ⇐ ApiResponse
  • .getResponseType()
  • .getData() ⇒ Object

singleReadResponse.getResponseType()

Kind: instance method of SingleReadResponse
See: getResponseType

singleReadResponse.getData() ⇒ Object

Kind: instance method of SingleReadResponse
Returns: Object - entity returned in this response

zotero-api-client~MultiReadResponse ⇐ ApiResponse

represnets a response to a GET request containing multiple entities

Kind: inner class of zotero-api-client
Extends: ApiResponse

• ~MultiReadResponse ⇐ ApiResponse
  • .getResponseType()
  • .getData() ⇒ Array
  • .getLinks() ⇒ Array
  • .getMeta() ⇒ Array
  • .getTotalResults() ⇒ string
  • .getRelLinks() ⇒ object

multiReadResponse.getResponseType()

Kind: instance method of MultiReadResponse
See: getResponseType

multiReadResponse.getData() ⇒ Array

Kind: instance method of MultiReadResponse
Returns: Array - a list of entities returned in this response

multiReadResponse.getLinks() ⇒ Array

Kind: instance method of MultiReadResponse
Returns: Array - a list of links, indexes of the array match indexes of entities in getData

multiReadResponse.getMeta() ⇒ Array

Kind: instance method of MultiReadResponse
Returns: Array - a list of meta data, indexes of the array match indexes of entities in getData

multiReadResponse.getTotalResults() ⇒ string

Kind: instance method of MultiReadResponse
Returns: string - Total number of results

multiReadResponse.getRelLinks() ⇒ object

Kind: instance method of MultiReadResponse
Returns: object - Parsed content of "Link" header as object where value of "rel" is a key and the URL is the value, contains values for "next", "last" etc.

zotero-api-client~SingleWriteResponse ⇐ ApiResponse

Represents a response to a PUT or PATCH request

Kind: inner class of zotero-api-client
Extends: ApiResponse

• ~SingleWriteResponse ⇐ ApiResponse
  • .getResponseType()
  • .getData() ⇒ Object

singleWriteResponse.getResponseType()

Kind: instance method of SingleWriteResponse
See: getResponseType

singleWriteResponse.getData() ⇒ Object

Kind: instance method of SingleWriteResponse
Returns: Object - For put requests, this represents a complete, updated object. For patch requests, this reprents only updated fields of the updated object.

zotero-api-client~MultiWriteResponse ⇐ ApiResponse

Represents a response to a POST request

Kind: inner class of zotero-api-client
Extends: ApiResponse

• ~MultiWriteResponse ⇐ ApiResponse
  • .getResponseType()
  • .isSuccess() ⇒ Boolean
  • .getData() ⇒ Array
  • .getLinks()
  • .getMeta()
  • .getErrors() ⇒ Object
  • .getEntityByKey(key)
  • .getEntityByIndex(index) ⇒ Object

multiWriteResponse.getResponseType()

Kind: instance method of MultiWriteResponse
See: getResponseType

multiWriteResponse.isSuccess() ⇒ Boolean

Kind: instance method of MultiWriteResponse
Returns: Boolean - Indicates whether all write operations were successful

multiWriteResponse.getData() ⇒ Array

Returns all entities POSTed in an array. Entities that have been written successfully are returned updated, other entities are returned unchanged. It is advised to verify if request was entirely successful (see isSuccess and getError) before using this method.

Kind: instance method of MultiWriteResponse
Returns: Array - A modified list of all entities posted.

multiWriteResponse.getLinks()

Kind: instance method of MultiWriteResponse
See: getLinks

multiWriteResponse.getMeta()

Kind: instance method of MultiWriteResponse
See: getMeta

multiWriteResponse.getErrors() ⇒ Object

Returns all errors that have occurred.

Kind: instance method of MultiWriteResponse
Returns: Object - Errors object where keys are indexes of the array of the original request and values are the erorrs occurred.

multiWriteResponse.getEntityByKey(key)

Allows obtaining updated entity based on its key, otherwise identical to getEntityByIndex

Kind: instance method of MultiWriteResponse
Throws:

• Error If key is not present in the request

See: module:zotero-api-client.getEntityByIndex

Param	Type
key	String

multiWriteResponse.getEntityByIndex(index) ⇒ Object

Allows obtaining updated entity based on its index in the original request

Kind: instance method of MultiWriteResponse
Throws:

• Error If index is not present in the original request
• Error If error occured in the POST for selected entity. Error message will contain reason for failure.

Param	Type
index	Number

zotero-api-client~DeleteResponse ⇐ ApiResponse

Represents a response to a DELETE request

Kind: inner class of zotero-api-client
Extends: ApiResponse

deleteResponse.getResponseType()

Kind: instance method of DeleteResponse
See: getResponseType

zotero-api-client~FileUploadResponse ⇐ ApiResponse

Represents a response to a file upload request

Kind: inner class of zotero-api-client
Extends: ApiResponse
Properties

Name	Type	Description
authResponse	Object	Response object for the stage 1 (upload authorisation) request
response	Object	alias for "authResponse"
uploadResponse	Object	Response object for the stage 2 (file upload) request
registerResponse	Objext	Response object for the stage 3 (upload registration) request

• ~FileUploadResponse ⇐ ApiResponse
  • .getResponseType()
  • .getVersion()

fileUploadResponse.getResponseType()

Kind: instance method of FileUploadResponse
See: getResponseType

fileUploadResponse.getVersion()

Kind: instance method of FileUploadResponse
See: getVersion

zotero-api-client~FileDownloadResponse ⇐ ApiResponse

Represents a response to a file download request

Kind: inner class of zotero-api-client
Extends: ApiResponse

fileDownloadResponse.getResponseType()

Kind: instance method of FileDownloadResponse
See: getResponseType

zotero-api-client~FileUrlResponse ⇐ ApiResponse

Represents a response containing temporary url for file download

Kind: inner class of zotero-api-client
Extends: ApiResponse

fileUrlResponse.getResponseType()

Kind: instance method of FileUrlResponse
See: getResponseType

zotero-api-client~RawApiResponse ⇐ ApiResponse

Represents a raw response, e.g. to data requests with format other than json

Kind: inner class of zotero-api-client
Extends: ApiResponse

rawApiResponse.getResponseType()

Kind: instance method of RawApiResponse
See: getResponseType

zotero-api-client~PretendResponse ⇐ ApiResponse

Represents a response for pretended request, mostly for debug purposes. See module:zotero-api-client.api~pretend

Kind: inner class of zotero-api-client
Extends: ApiResponse

• ~PretendResponse ⇐ ApiResponse
  • .getResponseType()
  • .getVersion() ⇒ Object

pretendResponse.getResponseType()

Kind: instance method of PretendResponse
See: getResponseType

pretendResponse.getVersion() ⇒ Object

Kind: instance method of PretendResponse
Returns: Object - For pretended request version will always be null.

zotero-api-client~ErrorResponse ⇐ Error

Represents an error response from the api

Kind: inner class of zotero-api-client
Extends: Error
Properties

Name	Type	Description
response	Object	Response object for the request, with untouched body
message	String	What error occurred, ususally contains response code and status
reason	String	More detailed reason for the failure, if provided by the API
options	String	Configuration object used for this request

• ~ErrorResponse ⇐ Error
  • .getVersion() ⇒ number
  • .getResponseType()

errorResponse.getVersion() ⇒ number

Value of "Last-Modified-Version" header in response if present. This is generally only available if server responded with 412 due to version mismatch.

Kind: instance method of ErrorResponse
Returns: number - Version of the content in response

errorResponse.getResponseType()

Kind: instance method of ErrorResponse
See: getResponseType

zotero-api-client~api() ⇒ Object

Wrapper function creates closure scope and calls api()

Kind: inner method of zotero-api-client
Returns: Object - Partially configured api functions

• ~api() ⇒ Object
  • ~api(key, opts) ⇒ Object
  • ~library([typeOrKey], [id]) ⇒ Object
  • ~items(items) ⇒ Object
  • ~itemTypes() ⇒ Object
  • ~itemFields() ⇒ Object
  • ~creatorFields() ⇒ Object
  • ~schema() ⇒ Object
  • ~itemTypeFields(itemType) ⇒ Object
  • ~itemTypeCreatorTypes(itemType) ⇒ Object
  • ~template(itemType, subType) ⇒ Object
  • ~collections(items) ⇒ Object
  • ~subcollections() ⇒ Object
  • ~publications() ⇒ Object
  • ~tags(tags) ⇒ Object
  • ~searches(searches) ⇒ Object
  • ~top() ⇒ Object
  • ~trash() ⇒ Object
  • ~children() ⇒ Object
  • ~settings(settings) ⇒ Object
  • ~deleted() ⇒ Object
  • ~groups() ⇒ Object
  • ~version(version) ⇒ Object
  • ~attachment([fileName], [file], [mtime], [md5sum], patch, [algorithm]) ⇒ Object
  • ~registerAttachment(fileName, fileSize, mtime, md5sum) ⇒ Object
  • ~attachmentUrl() ⇒ Object
  • ~verifyKeyAccess() ⇒ Object
  • ~get(opts) ⇒ Promise
  • ~post(data, opts) ⇒ Promise
  • ~put(data, opts) ⇒ Promise
  • ~patch(data, opts) ⇒ Promise
  • ~del(keysToDelete, opts) ⇒ Promise
  • ~getConfig() ⇒ Object
  • ~pretend(verb, data, opts) ⇒ Promise
  • ~use(extend) ⇒ Object

api~api(key, opts) ⇒ Object

Entry point of the interface. Configures authentication. Can be used to configure any other properties of the api Returns a set of function that are bound to that configuration and can be called to specify further api configuration.

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
key	String	Authentication key
opts	Object	Optional api configuration. For a list of all possible properties, see documentation for request() function

api~library([typeOrKey], [id]) ⇒ Object

Configures which library api requests should use.

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
[typeOrKey]	*	Library key, e.g. g1234. Alternatively, if second parameter is present, library type i.e either 'group' or 'user'
[id]	Number	Only when first argument is a type, library id

api~items(items) ⇒ Object

Configures api to use items or a specific item Can be used in conjuction with library(), collections(), top(), trash(), children(), tags() and any execution function (e.g. get(), post())

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Default	Description
items	String		Item key, if present, configure api to point at this specific item

api~itemTypes() ⇒ Object

Configure api to request all item types Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~itemFields() ⇒ Object

Configure api to request all item fields Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~creatorFields() ⇒ Object

Configure api to request localized creator fields Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~schema() ⇒ Object

Configure api to request schema Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~itemTypeFields(itemType) ⇒ Object

Configure api to request all valid fields for an item type Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
itemType	String	item type for which valid fields will be requested, e.g. 'book' or 'journalType'

api~itemTypeCreatorTypes(itemType) ⇒ Object

Configure api to request valid creator types for an item type Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
itemType	String	item type for which valid creator types will be requested, e.g. 'book' or 'journalType'

api~template(itemType, subType) ⇒ Object

Configure api to request template for a new item Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
itemType	String	item type for which template will be requested, e.g. 'book' or 'journalType'
subType	String	annotationType if itemType is 'annotation' or linkMode if itemType is 'attachment'

api~collections(items) ⇒ Object

Configure api to use collections or a specific collection Can be used in conjuction with library(), items(), top(), tags() and any of the execution function (e.g. get(), post())

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
items	String	Collection key, if present, configure api to point to this specific collection

api~subcollections() ⇒ Object

Configure api to use subcollections that reside underneath the specified collection. Should only be used in conjuction with both library() and collection() and any of the execution function (e.g. get(), post())

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~publications() ⇒ Object

Configure api to narrow the request to only consider items filled under "My Publications" Should only be used in conjuction with both library() and items() and any of the execution function (e.g. get(), post())

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~tags(tags) ⇒ Object

Configure api to request or delete tags or request a specific tag Can be used in conjuction with library(), items(), collections() and any of the following execution functions: get(), delete() but only if the first argument is not present. Otherwise can only be used in conjuctin with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Default	Description
tags	String		name of a tag to request. If preset, configure api to request specific tag.

api~searches(searches) ⇒ Object

Configure api to use saved searches or a specific saved search Can be used in conjuction with library() and any of the execution functions

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Default	Description
searches	String		Search key, if present, configure api to point at this specific saved search

api~top() ⇒ Object

Configure api to narrow the request only to the top level items Can be used in conjuction with items() and collections() and only with conjuction with a get() execution function

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~trash() ⇒ Object

Configure api to narrow the request only to the items in the trash Can be only used in conjuction with items() and get() execution function

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~children() ⇒ Object

Configure api to narrow the request only to the children of given item Can be only used in conjuction with items() and get() execution function

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~settings(settings) ⇒ Object

Configure api to request settings Can only be used in conjuction with get(), put(), post() and delete() For usage with put() and delete() settings key must be provided For usage with post() settings key must not be included

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Default	Description
settings	String		Settings key, if present, configure api to point at this specific key within settings, e.g. tagColors.

api~deleted() ⇒ Object

Configure api to request deleted content Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~groups() ⇒ Object

Configure api to request user-accessible groups (i.e. The set of groups the current API key has access to, including public groups the key owner belongs to even if the key doesn't have explicit permissions for them.) Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~version(version) ⇒ Object

Configure api to specify local version of given entity. When used in conjuction with get() exec function, it will populate the If-Modified-Since-Version header. When used in conjuction with post(), put(), patch() or delete() it will populate the If-Unmodified-Since-Version header.

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
version	Number	local version of the entity

api~attachment([fileName], [file], [mtime], [md5sum], patch, [algorithm]) ⇒ Object

Configure api to upload or download an attachment file. Can be only used in conjuction with items() and post()/get()/patch(). Method patch() can only be used to upload a binary patch, in this case last two argument must be provided. Method post() is used for full uploads. If md5sum is provided, it will update existing file, otherwise it uploads a new file. Last two arguments are not used in this scenario. Method get() is used for downloads, in this case skip all arguments. Use items() to select attachment item for which file is uploaded/downloaded. Will populate format on download as well as Content-Type, If*Match headers in case of upload.

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
[fileName]	String	For upload: name of the file, should match values in attachment item entry
[file]	ArrayBuffer	New file to be uploaded
[mtime]	Number	New file's mtime, leave empty to assume current date/time
[md5sum]	String	MD5 hash of an existing file, required for uploads that update existing file
patch	ArrayBuffer	Binary patch, to be applied to the old file, to produce a new file
[algorithm]	String	Algorithm used to compute a diff: xdelta, vcdiff or bsdiff

api~registerAttachment(fileName, fileSize, mtime, md5sum) ⇒ Object

Advanced function that will attempt to register existing file with given attachment-item based on known file metadata. Can be only used in conjuction with items() and post(). Use items() to select attachment item for which file is registered. Will populate Content-Type, If-Match headers. Will fail with a ErrorResponse if API does not return "exists".

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

Param	Type	Description
fileName	String	name of the file, should match values in attachment item entry
fileSize	Number	size of the existing file
mtime	Number	mtime of the existing file
md5sum	String	md5sum of the existing file

api~attachmentUrl() ⇒ Object

Configure api to request a temporary attachment file url Can be only used in conjuction with items() and get() Use items() to select attachment item for which file is url is requested Will populate format, redirect

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~verifyKeyAccess() ⇒ Object

Configure api to request information on the API key. Can only be used in conjuction with get()

Kind: inner method of api
Chainable
Returns: Object - Partially configured api functions

api~get(opts) ⇒ Promise

Execution function. Specifies that the request should use a GET method.

Kind: inner method of api
Returns: Promise - A promise that will eventually return either an ApiResponse, SingleReadResponse or MultiReadResponse. Might throw Error or ErrorResponse.

Param	Type	Description
opts	Object	Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function

api~post(data, opts) ⇒ Promise

Execution function. Specifies that the request should use a POST method.

Kind: inner method of api
Returns: Promise - A promise that will eventually return MultiWriteResponse. Might throw Error or ErrorResponse

Param	Type	Description
data	Array	An array of entities to post
opts	Object	Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function

api~put(data, opts) ⇒ Promise

Execution function. Specifies that the request should use a PUT method.

Kind: inner method of api
Returns: Promise - A promise that will eventually return SingleWriteResponse. Might throw Error or ErrorResponse

Param	Type	Description
data	Object	An entity to put
opts	Object	Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function

api~patch(data, opts) ⇒ Promise

Execution function. Specifies that the request should use a PATCH method.

Kind: inner method of api
Returns: Promise - A promise that will eventually return SingleWriteResponse. Might throw Error or ErrorResponse

Param	Type	Description
data	Object	Partial entity data to patch
opts	Object	Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function

api~del(keysToDelete, opts) ⇒ Promise

Execution function. Specifies that the request should use a DELETE method.

Kind: inner method of api
Returns: Promise - A promise that will eventually return DeleteResponse. Might throw Error or ErrorResponse

Param	Type	Description
keysToDelete	Array	An array of keys to delete. Depending on how api has been configured, these will be item keys, collection keys, search keys or tag names. If not present, api should be configured to use specific item, collection, saved search or settings key, in which case, that entity will be deleted
opts	Object	Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function

api~getConfig() ⇒ Object

Execution function. Returns current config without doing any requests. Usually used in advanced scenarios where config needs to be tweaked manually before submitted to the request method or as a debugging tool.

Kind: inner method of api
Returns: Object - current config

api~pretend(verb, data, opts) ⇒ Promise

Execution function. Prepares the request but does not execute fetch() instead returning a "pretended" response where details for the actual fetch that would have been used are included. Usually used in advanced scenarios where config needs to be tweaked manually before it is submitted to the request method or as a debugging tool.

Kind: inner method of api
Returns: Promise - A promise that will eventually return PretendResponse. Might throw Error or ErrorResponse

Param	Type	Default	Description
verb	String	get	Defines which execution function is used to prepare the request. Should be one of 'get', 'post', 'patch' 'put', 'delete'. Defaults to 'get'.
data	Object		This argument is passed over to the actual execution function. For 'get' it is ignored, for 'post', 'patch' and 'put' see 'data' of that execution function, for 'delete' see 'keysToDelete'
opts	Object		Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function

api~use(extend) ⇒ Object

Used for extending capabilities of the library by installing plugins. In most cases plugins inject additional executors or bind api to an alternative/extended set of functions

Kind: inner method of api
Returns: Object - Extended/partially configured api functions

Param	Type	Description
extend	function	function that installs alternative or additional functionality of the api. It should return bound api functions, usually by caling arguments[0].ef()

zotero-api-client~request() ⇒ Object

Executes request and returns a response. Not meant to be called directly, instead use api.

Kind: inner method of zotero-api-client
Returns: Object - Returns a Promise that will eventually return a response object
Throws:

• Error If options specify impossible configuration
• ErrorResponse If API responds with a non-ok response

Param	Type	Description
options.apiScheme	String	Scheme part of the API URL
options.apiAuthorityPart	String	Authority part of the API URL
options.apiPath	String	Path part of the API URL
options.authorization	String	'Authorization' header
options.zoteroWriteToken	String	'Zotero-Write-Token' header
options.ifModifiedSinceVersion	String	'If-Modified-Since-Version' header
options.ifUnmodifiedSinceVersion	String	'If-Unmodified-Since-Version' header
options.contentType	String	'Content-Type' header
options.collectionKey	String	'collectionKey' query argument
options.content	String	'content' query argument
options.direction	String	'direction' query argument
options.format	String	'format' query argument
options.include	String	'include' query argument
options.includeTrashed	String	'includeTrashed' query argument
options.itemKey	String	'itemKey' query argument
options.itemQ	String	'itemQ' query argument
options.itemQMode	String	'itemQMode' query argument
options.itemTag	String | Array.<String>	'itemTag' query argument
options.itemType	String	'itemType' query argument
options.limit	Number	'limit' query argument
options.linkMode	String	'linkMode' query argument
options.locale	String	'locale' query argument
options.q	String	'q' query argument
options.qmode	String	'qmode' query argument
options.searchKey	String	'searchKey' query argument
options.since	Number	'since' query argument
options.sort	String	'sort' query argument
options.start	Number	'start' query argument
options.style	String	'style' query argument
options.tag	String | Array.<String>	'tag' query argument
options.pretend	Boolean	triggers pretend mode where fetch request is prepared and returned without execution
options.resource.top	String	use 'top' resource
options.resource.trash	String	use 'trash' resource
options.resource.children	String	use 'children' resource
options.resource.groups	String	use 'groups' resource
options.resource.itemTypes	String	use 'itemTypes' resource
options.resource.itemFields	String	use 'itemFields' resource
options.resource.creatorFields	String	use 'creatorFields' resource
options.resource.itemTypeFields	String	use 'itemTypeFields' resource
options.resource.itemTypeCreatorTypes	String	use 'itemTypeCreatorTypes' resource
options.resource.library	String	use 'library' resource
options.resource.collections	String	use 'collections' resource
options.resource.items	String	use 'items' resource
options.resource.searches	String	use 'searches' resource
options.resource.tags	String	use 'tags' resource
options.resource.template	String	use 'template' resource
options.method	String	forwarded to fetch()
options.body	String	forwarded to fetch()
options.mode	String	forwarded to fetch()
options.cache	String	forwarded to fetch()
options.credentials	String	forwarded to fetch()
options.uploadRegisterOnly	Boolean	this file upload should only perform stage 1 error if file with provided meta does not exist
options.retry	Number	retry this many times after transient error.
options.retryDelay	Number	wait this many seconds before retry. If not set an exponential backoff algorithm will be used