CloudPublish API

The CloudPublish API is a REST-style interface to the CloudPublish platform, outputing data in JSON format. The purpose of the API is to allow a publisher to create a front-end to the CloudPublish system. The front-end can be as simple as a catalogue listing or as complex as an ecommerce book-store.

It is important to note a few things that the CloudPublish API does not do:

  1. There is no customer/user database provided, as such. It is expected that you maintain your own customer-facing systems / website, and then supply a unique customer identifier to the API when referring to a specific customer (e.g., retrieving subscription data for a customer). This identifier would typically be the same ID or unique customer number as used in your own customer account database, thereby enabling you to link records effectively.
  2. The batch processing of PDFs into ebooks is not done via the API, although you can check the progress of ebooks by using the BookGetAll and BookGet methods.

For more information, please see the CloudPublish support pages.

API Documentation

Connection and authentication

Results format


Catalogue: General

These methods are applicable to more than one type of item.

Get subjects data

Expand a subject

Catalogue: Books

A book typically represents a single ebook.

Get book data (all books)

Get book data (single book)

Get Table of Contents (single book)

Get citation for book(s)

Get imprints data

Get imprint details (single imprint)

Get series data

Catalogue: Contributors

A contributor is either an author or an editor (or both). Authors are associated with books, chapters, and journal articles only. Editors are associated with books and journal issues only.

Get contributors data

Get contributor details (single contributor)

Get authors data [DEPRECATED]

Get author details (single author) [DEPRECATED]

Catalogue: Chapters

A chapter consists of a fragment of a book that is already in your catalogue, defined by a page range within that book. While books are added by sending ONIX metadata, chapters are created via the API. Chapters are currently only available via the online eReader.

Get chapter data (all chapters)

Get chapter data (single chapter)

Create a chapter

Update a chapter

Delete a chapter

Catalogue: Journals

Journals are handled slightly differently to books. There are several levels in the structure:

  • Journal: An entire publication. Does not exist as a readable item.
  • Issue: A single issue of a Journal. Can exist as a readable item, or as a container for Articles.
  • Article: A single article within a single Issue of a Journal. Can exist as a readable item or as a metadata container for use with Issue.
  • Reference: A single reference or endnote, associated with a single Article.

Therefore, a Journal may have multiple Issues, each of which may have multiple Articles, each of which may have multiple References.

The corresponding files you upload depend on whether you want to provide access by issue, or by article, or both. In any case you will need to upload issues and/or articles with unique filenames.

Important: In order to ensure uniqueness of your filenames, you must incorporate an ISSN or other identifier unique to your organisation. For books, the ISBN system accomplishes this for you. We recommend naming files as follows:

  • Issue: ISSNvolXissY.pdf (where X and Y are integers)
  • Article: ISSNvolXissYpZ.pdf (where Z is the page number of the article)

Get journal data (all journals)

Get journal data (single journal)

Get journal volume data

Get journal issue data (all issues)

Get journal issue data (single issue)

Get journal article data (all articles)

Get journal article data (single article)

Get a reference in citation format

Get all articles by an author

Get all references to an author


Collections are simply groups of the same type of item. They are typically used to group items for sales purposes, e.g. by subject. A collection can contain items of one (and only one) of the following types:

  • Books
  • Journals (i.e. complete journals)
  • Journal issues (i.e. single issues)
  • Journal articles

Get collections data

Get collection details (single collection)

Accessing items for reading

Items can be accessed for online reading (using CloudPublish CloudReader) for download (PDF via Adobe Digital Editions with Adobe CRM).

Access an item (download or online)

Get number of current readers for an item


Searches are conducted either across the catalogue, searching either catalogue metadata or within the text of specific items. Searches can be saved against a customer identifier.

  • /Search is for searching catalogue metadata, using keyword matching
  • /SearchText is for searching within the text of one or more items, or your entire catalogue, using natural language matching

Natural language matching allows for the search term to be enclosed in double-quotes (") to prioritise a seach for the exact phrase.

Searches conducted via /Search can be saved, using /SearchSave, but fulltext searches via /SearchText cannot be saved.

Search catalogue

Save a search for a customer

Search within the text of items

Retrieve a customer's saved searches

Run a saved search


An order is a submitted cart. When processed, it generates subscriptions and transactions.

Create an order

Get order(s)

Update an order

Delete an order

Update an order's items

Delete an item from an order

Process an order (convert to subscriptions)


A subscription entitles a customer to access one or more copies of a book. It can be created directly or by processing an order. Note that creating a subscription directly also creates a corresponding transaction.

It is possible for a customer to have more than one subscription to a given book. In this case, the /CustomerSubscriptionCheck method will check all matching subscription, and will return affirmatively if at least one is valid/current for the book.

Create a subscription

Get subscriptions data

Get a subscription

Update a subscription

Delete a subscription


A Transaction is generated when an order is processed or when a subscription is created directly.

Get transactions data

Get single transaction details

Manually create a transaction

Update a transaction

Delete a transaction

Update a transaction's items

Delete an item from a transaction

Access Tokens

An access token provides access to content for a user (possibly but not necessarily an existing customer), usually with various restrictions in place.

Create an access token


A customer is a single actor within your customer-base. In CloudPublish, customers are described by a unique identifier, customer_ref (string), which we recommend setting to be the same as the complete corresponding customer record in your own systems.

A CloudPublish customer is typically an institution / organisation entity, and will have one or more customer users, which can be created and managed by further API calls as described below. Again, these can correspond to users in your own systems, this time via the unique identifier customer_user_ref.

Identify a customer

Retrieve customer details

Get customer-specific order information

Get customer-specific subscription information

Check whether a customer has a subscription to an item

Check whether a customer can access an item

Get customer-specific transaction information

Get customer usage statistics (excl. COUNTER stats)

Get statistical reports in COUNTER format.

Create a Customer User

Retrieve a Customer User

Retrieve all Customer Users

Update a Customer User

Delete a Customer User


A list is simply an arbitrary list of items, typically created by an end-user (for example, a search result, or a "read later" list, etc.)

Create a list

Update a list

Delete a list

Get many lists

Get a single list

Content Management

The CloudPublish Admin Tool allows you to create content "snippets" which are intended to be displayed on any related landing page on your site. Use the API to retrieve them.

Retrieve CMS Content


For technical support, you can open a ticket any time by emailing:

Alternatively, please use any of the following:

Call: +44 (0)203 0313 866
Fax: +44 (0)20 7608 1387