← Jellybooks Technical Documentation
This guide explains how to deliver publication assets to Jellybooks for ingestion into our platform. Each publication requires three files — the ebook, a cover image, and an Onix metadata record — and there are two supported ways to organise them for transfer.
Jellybooks operates two SFTP servers for asset delivery:
The two servers are identical in content and capability. Use whichever is geographically closer to you; you will get a more reliable connection.
You will have been assigned a dedicated username for SFTP access. This is not the same as any username you may have for Jellybooks web-based resources.
Connect using your assigned username and the hostname of your preferred server:
sftp <your-username>@assets.jellybooks.com sftp <your-username>@usa-assets.jellybooks.com
Depending on your SFTP client you may need to supply the username and hostname as separate fields rather than in the combined user@host form above.
When you connect, you will see a directory called incoming. Place all your asset files inside that directory, following the structure described in the Asset delivery structure section below.
For each publication, Jellybooks requires the following three assets in order to process and integrate the title into our platform:
| Asset | Extension | Notes |
|---|---|---|
| Ebook | .epub | ePub version 3.0 or greater is preferred. Version 2 is still accepted but deprecated. |
| Cover image | .jpg, .jpeg | High-resolution cover image. A long edge of 1200 px or greater is preferred; 800 px is the minimum we accept. The vast majority of covers are portrait, so this corresponds to a preferred height of ≥ 1200 px and a minimum height of ≥ 800 px. |
| Onix metadata | .xml, .onx | Book metadata should be in Onix version 3. Version 2 is still accepted but deprecated. |
An Onix message can carry a wide range of metadata. We require at minimum the following fields:
The Onix metadata, and therefore the ISBN-13 code, must be for the ebook product form of the publication.
In addition, we strongly recommend including the following fields where applicable:
Tag format: Onix 3 supports both short tags and long tags. We currently support long tags only.
All assets are placed inside the incoming directory on the SFTP server. To allow us to associate the three asset files for a single publication with each other, two formats are supported.
Create a sub-directory inside incoming whose name is the publication's ISBN-13. Place the ebook, cover image, and Onix file inside that directory.
In this format the individual filenames within the directory may be arbitrary, but it is good practice to prefix them with the same ISBN-13.
incoming/
9123456123456/
9123456123456.epub
9123456123456.jpg
9123456123456.xml
9321321654654/
9321321654654_epub3.epub
9321321654654_hires.jpg
9321321654654_onix.xml
Alternatively, all assets may be placed directly inside the incoming directory without sub-directories. In this case every file must be prefixed with its publication's ISBN-13 so that the three assets can be grouped correctly.
incoming/ 9123456123456.epub 9123456123456.jpg 9123456123456.xml 9321321654654_epub3.epub 9321321654654_hires.jpg 9321321654654_onix.xml
ISBNs used in directory and file names must not contain spaces, hyphens, or other separators. Use the strictly numeric 13-digit format as specified in the Onix standard.