Readiant

With Readiant’s technology, ePub and PDF files are converted to a modern streaming format. The result is stored in a decentralized manner and therefore cannot be multiplied without permission.

This process consists of the following steps:

  1. Convert an ePub or PDF
  2. Maintain a collection of documents
  3. Distribute embedcodes
  4. Embed a document
  5. Analyze usage

All of these steps can be performed from the Readiant environment. Step 1 - 3 can also be performed through the Readiant API.

Latest Changes

Below are the latest changes to this documentation.

Changes
Made the analytics endpoint available for all account types.
Added the optional parameter: audioHighlightingLevel
Added the optional parameter: localeTranslations
Added the optional parameter: readStopLevel
Added the optional parameter: subtitleFontSize
Added the optional parameter: subtitleLevel
Added the optional parameter: textModeLevel
Added the event: Change audio highlighting
Added the event: Change read stop
Added the event: Change subtitle
Added the event: Change subtitle font size
Added the event: Translate
Expanded add embed with the translatable boolean
Expanded errors with an error_code overview

Last updated on September 23rd, 2022.

Converter

An ePub or PDF file can be converted in 2 different ways.

In the Readiant environment the user can add multiple files to the conversion queue, after which they are converted one by one.

Alternatively a file can also be converted via the add document-endpoint.

In both cases, the original files are not stored in any way.

Documents

All the converted documents will be available in the Readiant environment. Users can add, edit or delete metadata from the documents. These metadata fields will automatically become available to a linked platform.

In the Readiant environment documents can be filtered by metadata. These filters can be stored and used as a basis for Analytics.

The Readiant API also exposes add, update and delete-endpoints through which an authenticated user can add and manage documents. For more information about managing documents via the Readiant API we refer you to the Documents section.

Distributor

Unlimited embedcodes can be created for the converted documents. An embedcode should be created for every unique instance where you can have reader(s) for a document.

Embedcodes are only available for the given domain(s) which should be able to access the document. Every embedcode can have different settings, based on the needs for the specific reader(s). For instance, you can

It will not be necessary to convert a document multiple times.

Embedcodes can be created, managed and distributed in the Readiant environment.

The Readiant API also exposes add, update and delete-endpoints through which an authenticated user can add and manage documents. For more information about managing documents via the Readiant API we refer you to the Embeds section.

Recommended flow It's recommended to use temporary embedcodes when presenting documents to reader(s). When a reader requests to read a document, a temporary embedcode should be created on the fly for that document identifier using the API.

A temporary embedcode is active for 1 hour, activity in the reader extends this duration.

Embed

A document can be embedded on a selected domain using the following HTML-code:

<iframe
  src="https://readiant.app/e/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx"
  title="Describe the contents of the frame to people using assistive technology"
  sandbox="allow-modals allow-same-origin allow-scripts allow-popups" allowfullscreen>
</iframe>

Where xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx is the generated embedcode. When the domain is authorized to access the document, a reader will appear in the selected layout.

Optional Parameters

NameTypeDescription
audioHighlightingLevelintegerSet a default audio page highlighting level. Can be a value between 1 and 3
colorBlindFilterstringSet a default colorblind filter. Possibilities: Grayscale, Protonopia, Protanomaly, Deuteranopia, Deuteranomaly, Tritanopia, Tritanomaly, Achromatopsia, Achromatomaly
countdownLevelintegerSet a default countdown level. Can be a value between 1 and 3
disablestringReader functionalities that should be disabled (comma delimited). Possibilities: advanced, annotations, search
fontstringSet a default font. Possibilities: Original, Dyslexia, Lora, Merriweather, Mulish, Mukta, Roboto
fontSizeintegerSet a default font size. Can be a value between 1 and 12
idstringSet an identifier for the user reading the document, this can be used to analyze reading patterns for individual users
imageQualityLevelintegerSet a default image quality level. Can be a value between 1 and 3
letterSpacingintegerSet a default letter spacing value. Can be a value between 1 and 5
lineHeightintegerSet a default line height value. Can be a value between 1 and 3
localestringSet the language of the reader and audio based on this value. Possibilities: en-GB, en-US, nl-BE, nl-NL
localeTranslationsstringSet the default language of translations. Possibilities: bg, cs, da, de, el, en-GB, en-US, es, et, fi, fr, hu, id, it, ja, lt, lv, nl, pl, pt-BR, pt-PT, ro, ru, sk, sl, sv, tr, zh
orientationstringForce a reading orientation. landscape or portrait
pageintegerThe starting page of the document
playbackRatefloatSet a default audio playback rate. Can be a value between 0.5 and 1.6
readStopLevelintegerSet a default read stop level. Can be a value between 1 and 3
screenModeLevelintegerSet a default screen mode. Can be a value between 1 and 3
subtitleFontSizeintegerSet a default subtitle font size. Can be a value between 1 and 5
subtitleLevelintegerSet a default subtitle level. Can be a value between 1 and 3
textModeLevelintegerSet a default text mode. Can be a value between 1 and 3
wordSpacingintegerSet a default word spacing value. Can be a value between 1 and 5
zoomLevelintegerSet a default zoom level. Can be a value between 1 and 5

Events

In order to gain insight in the various events performed by an end user you can setup a postMessage communication link between the iframe and the parent. Using this communcation link you can listen to events being performed by the end user and use this information to your advantage.

An example of how to setup a postMessage event listener
window.addEventListener('message', (event) => {
    if (event.origin !== 'https://readiant.app') {
        return;
    }

    // Contains the data relevant for the event type.
    const data = event.data;

    switch (data.type) {
        case 'audio_play': {
            // Perform an action based upon the end user playing audio.
        }
        case 'next_page': {
            // Perform an action based upon the end user flipping a page.
        }
        // Etc.
    }
});

Some events can also be used to send requests to the iframe (after the ready state event was sent by the iframe) containing the document in order to perform certain actions in the reader. This uses the same postMessage communication link as when listening for events.

An example of how to send a postMessage event to the iframe
// The iframe embedding the Readiant document.
const iframe = document.getElementById('example');

// Play audio on the current page.
iframe.contentWindow.postMessage({ type: 'audio_play' }, '*');

// Navigate the document to the next page.
iframe.contentWindow.postMessage({ type: 'next_page' }, '*');

// Etc.

Event Reference Index

Ready state

Navigation

Annotations

Audio

Usage

Ready state

This event is triggered when the document has loaded and is ready to accept events.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
typestringThe type property must be set to ready.
An example of a received event data object
{
    "type":"ready"
}

Initial navigation

This event is triggered when the initial pages are loaded in the document.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
pagesinteger[]An array containing the initial page(s) loaded in the document.
typestringThe type property must be set to initial_page.
An example of a received event data object
{
    "pages":[4,5],
    "type":"initial_page"
}

Direct navigation

This event is triggered when a user directly navigates to a specific page.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
pagesinteger[]An array containing the page(s) to which the user navigates.
previousobjectAn object containing reading information about the previous page(s).
previous.durationintegerThe total duration in milliseconds the user spent on the page(s).
previous.pagesobject[]An array of objects containing page specific information.
previous.pages.audioobjectAn object containing audio information about a specific page.
previous.pages.audio.playbackPercentagefloatThe percentage of audio that was played on this specific page.
previous.pages.pageintegerThe page number of the previous page.
typestringThe type property must be set to goto_page.
An example of a received event data object
{
    "pages":[10,11],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 0.51
                },
                "page": 1
            }
        ]
    },
    "type":"goto_page"
}
An example of a sent event data object
{
    "pages":[5],
    "type":"goto_page"
}

Next page

This event is triggered when a user goes to the next page.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
pagesinteger[]An array containing the page(s) to which the user navigates.
previousobjectAn object containing reading information about the previous page(s).
previous.durationintegerThe total duration in milliseconds the user spent on the page(s).
previous.pagesobject[]An array of objects containing page specific information.
previous.pages.audioobjectAn object containing audio information about a specific page.
previous.pages.audio.playbackPercentagefloatThe percentage of audio that was played on this specific page.
previous.pages.pageintegerThe page number of the previous page.
typestringThe type property must be set to next_page.
An example of a received event data object
{
    "pages":[10,11],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 0.23
                },
                "page": 8
            },
            {
                "audio": {
                    "playbackPercentage": 0.83
                },
                "page": 9
            }
        ]
    },
    "type":"next_page"
}
An example of a sent event data object
{
    "type":"next_page"
}

Previous page

This event is triggered when a user goes to the previous page.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
pagesinteger[]An array containing the page(s) to which the user navigates.
previousobjectAn object containing reading information about the previous page(s).
previous.durationintegerThe total duration in milliseconds the user spent on the page(s).
previous.pagesobject[]An array of objects containing page specific information.
previous.pages.audioobjectAn object containing audio information about a specific page.
previous.pages.audio.playbackPercentagefloatThe percentage of audio that was played on this specific page.
previous.pages.pageintegerThe page number of the previous page.
typestringThe type property must be set to previous_page.
An example of a received event data object
{
    "pages":[4,5],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 1
                },
                "page": 6
            },
            {
                "audio": {
                    "playbackPercentage": 0.24
                },
                "page": 7
            }
        ]
    },
    "type":"previous_page"
}
An example of a sent event data object
{
    "type":"previous_page"
}

Closing navigation

This event is triggered when a user closes the iframe or navigates away in the browser.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
pagesinteger[]An array containing the page(s) to which the user navigates.
previousobjectAn object containing reading information about the previous page(s).
previous.durationintegerThe total duration in milliseconds the user spent on the page(s).
previous.pagesobject[]An array of objects containing page specific information.
previous.pages.audioobjectAn object containing audio information about a specific page.
previous.pages.audio.playbackPercentagefloatThe percentage of audio that was played on this specific page.
previous.pages.pageintegerThe page number of the previous page.
typestringThe type property must be set to closing_page.
An example of a received event data object
{
    "pages":[10,11],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 0.51
                },
                "page": 1
            }
        ]
    },
    "type":"closing_page"
}

Annotations

This event is triggered when a user created annotations and left the page upon which the annotations were made.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
annotationsstringA base64 encoded string of the relevant annotation data.
pageintegerThe page number of the page where the annotations were created.
typestringThe type property must be set to annotation.
An example of a received event data object
{
    "annotations":"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2
    NpbmcgZWxpdC4gSW4gYSBsYWNpbmlhIG1ldHVzLCBzZWQgcHVsdmluYXIgZXJvcy4gTnVuYyBuZWM
    gbWkgdXJuYS4gUHJvaW4gaW50ZXJkdW0gdmVsaXQgdXJuYSwgdmVsIGRpZ25pc3NpbSBwdXJ1cyB2
    b2x1dHBhdCBmZXJtZW50dW0u",
    "page":5,
    "type":"annotation"
}

Add Annotations

This event can only be sent to the iframe and is used to add (previously) created annotations to a document after the iframe sends its ready state event.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
annotationsobject[]An array of annotation objects that should be added to the document.
annotations.annotationsstringA base64 encoded string of the relevant annotation data.
annotations.pageintegerThe page number on which page the annotations should be added.
typestringThe type property must be set to add_annotations.
An example of a sent event data object
{
    "annotations":[
        annotations: "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2
    NpbmcgZWxpdC4gSW4gYSBsYWNpbmlhIG1ldHVzLCBzZWQgcHVsdmluYXIgZXJvcy4gTnVuYyBuZWM
    gbWkgdXJuYS4gUHJvaW4gaW50ZXJkdW0gdmVsaXQgdXJuYSwgdmVsIGRpZ25pc3NpbSBwdXJ1cyB2
    b2x1dHBhdCBmZXJtZW50dW0u",
        "page":5,
    ],
    "type":"add_annotations"
}

Audio Play

This event is triggered when a user plays the audio.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
typestringThe type property must be set to audio_play.
An example of a received event data object
{
    "type":"audio_play"
}
An example of a sent event data object
{
    "type":"audio_play"
}

Audio Pause

This event is triggered when a user pauses the audio.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
typestringThe type property must be set to audio_pause.
An example of a received event data object
{
    "type":"audio_pause"
}
An example of a sent event data object
{
    "type":"audio_pause"
}

Change audio highlighting

This event is triggered when a user changes the type of audio highlighting.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
audioHighlightingLevelintegerThe audio highlighting level, can be a value between 1 and 3.
typestringThe type property must be set to change_audio_highlighting.
An example of a received event data object
{
    "audioHighlightingLevel":2,
    "type":"change_audio_highlighting"
}
An example of a sent event data object
{
    "audioHighlightingLevel":3,
    "type":"change_audio_highlighting"
}

Change audio playback rate

This event is triggered when a user changes the audio playback rate.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
playbackRatefloatThe audio playback rate, can be a value between 0.5 and 1.6.
typestringThe type property must be set to change_playback_rate.
An example of a received event data object
{
    "playbackRate":1.2,
    "type":"change_playback_rate"
}
An example of a sent event data object
{
    "playbackRate":0.7,
    "type":"change_playback_rate"
}

Change colorblind filter

This event is triggered when a user changes a colorblind filter.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
colorBlindFilterstringThe colorblind filter, can be one of the following possibilities: Grayscale, Protonopia, Protanomaly, Deuteranopia, Deuteranomaly, Tritanopia, Tritanomaly, Achromatopsia, Achromatomaly.
typestringThe type property must be set to change_color_blind_filter.
An example of a received event data object
{
    "colorBlindFilter":"Grayscale",
    "type":"change_color_blind_filter"
}
An example of a sent event data object
{
    "colorBlindFilter":"Protonopia",
    "type":"change_color_blind_filter"
}

Change countdown type

This event is triggered when a user changes an audio countdown type.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
countdownLevelintegerThe countdown level, can be a value between 1 and 3.
typestringThe type property must be set to change_countdown.
An example of a received event data object
{
    "countdownLevel":2,
    "type":"change_countdown"
}
An example of a sent event data object
{
    "countdownLevel":3,
    "type":"change_countdown"
}

Change font

This event is triggered when a user changes the font.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
fontstringThe font name, can be one of the following possibilities: Original, Dyslexia, Lora, Merriweather, Mulish, Mukta, Roboto.
typestringThe type property must be set to change_font.
An example of a received event data object
{
    "font":"Dyslexia",
    "type":"change_font"
}
An example of a sent event data object
{
    "font":"Roboto",
    "type":"change_font"
}

Change font size

This event is triggered when a user changes the font size.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
fontSizeintegerThe font size, can be a value between 1 and 12.
typestringThe type property must be set to change_font_size.
An example of a received event data object
{
    "fontSize":12,
    "type":"change_font_size"
}
An example of a sent event data object
{
    "fontSize":3,
    "type":"change_font_size"
}

Change image quality

This event is triggered when a user changes the image quality.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
imageQualitystringThe effectiveType of the chosen image quality, this value is only passed when listening for this event. Can be one of the following possibilities: slow-2g, 2g, 3g, or 4g
imageQualityLevelintegerThe image quality level, can be a value between 1 and 3.
typestringThe type property must be set to change_image_quality.
An example of a received event data object
{
    "imageQuality":"2g",
    "imageQualityLevel":2,
    "type":"change_image_quality"
}
An example of a sent event data object
{
    "imageQualityLevel":3,
    "type":"change_image_quality"
}

Change letter spacing

This event is triggered when a user changes the letter spacing value.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
letterSpacingintegerThe letter spacing, can be a value between 1 and 5.
typestringThe type property must be set to change_letter_spacing.
An example of a received event data object
{
    "letterSpacing":2,
    "type":"change_letter_spacing"
}
An example of a sent event data object
{
    "letterSpacing":5,
    "type":"change_letter_spacing"
}

Change line height

This event is triggered when a user changes the line height in an ePub.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
lineHeightintegerThe line height, can be a value between 1 and 3.
typestringThe type property must be set to change_line_height.
An example of a received event data object
{
    "lineHeight":2,
    "type":"change_line_height"
}
An example of a sent event data object
{
    "lineHeight":1,
    "type":"change_line_height"
}

Change read stop

This event is triggered when a user changes the type of read stop.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
readStopLevelintegerThe read stop level, can be a value between 1 and 3.
typestringThe type property must be set to change_read_stop.
An example of a received event data object
{
    "readStopLevel":2,
    "type":"change_read_stop"
}
An example of a sent event data object
{
    "readStopLevel":3,
    "type":"change_read_stop"
}

Change screen mode

This event is triggered when a user changes a screen mode.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
screenModeLevelintegerThe screen mode level, can be a value between 1 and 3.
typestringThe type property must be set to change_screen_mode.
An example of a received event data object
{
    "screenModeLevel":2,
    "type":"change_screen_mode"
}
An example of a sent event data object
{
    "screenModeLevel":1,
    "type":"change_screen_mode"
}

Change subtitle

This event is triggered when a user changes the type of subtitles.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
subtitleLevelintegerThe subtitle level, can be a value between 1 and 3.
typestringThe type property must be set to change_subtitle.
An example of a received event data object
{
    "subtitleLevel":2,
    "type":"change_subtitle"
}
An example of a sent event data object
{
    "subtitleLevel":3,
    "type":"change_subtitle"
}

Change subtitle font size

This event is triggered when a user changes the font size of the subtitles.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
subtitleFontSizeintegerThe font size of the subtitles, can be a value between 1 and 5.
typestringThe type property must be set to change_subtitle_font_size.
An example of a received event data object
{
    "subtitleFontSize":2,
    "type":"change_subtitle_font_size"
}
An example of a sent event data object
{
    "subtitleFontSize":3,
    "type":"change_subtitle_font_size"
}

Change text mode

This event is triggered when a user changes the text mode.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
textModeLevelintegerThe text mode level, can be a value between 1 and 3.
typestringThe type property must be set to change_text_mode.
An example of a received event data object
{
    "textModeLevel":2,
    "type":"change_text_mode"
}
An example of a sent event data object
{
    "textModeLevel":3,
    "type":"change_text_mode"
}

Change word spacing

This event is triggered when a user changes the word spacing value.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
wordSpacingintegerThe word spacing, can be a value between 1 and 5.
typestringThe type property must be set to change_word_spacing.
An example of a received event data object
{
    "wordSpacing":4,
    "type":"change_word_spacing"
}
An example of a sent event data object
{
    "wordSpacing":1,
    "type":"change_word_spacing"
}

Change zoom level

This event is triggered when a user changes the zoom level.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
zoomLevelintegerThe zoom level, can be a value between 1 and 5.
typestringThe type property must be set to change_zoom_level.
An example of a received event data object
{
    "zoomLevel":2,
    "type":"change_zoom_level"
}
An example of a sent event data object
{
    "zoomLevel":3,
    "type":"change_zoom_level"
}

Print

This event is triggered when a user prints a page.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
pagesinteger[]An array containing the page(s) being printed.
typestringThe type property must be set to print.
An example of a received event data object
{
    "pages":[2,3],
    "type":"print"
}

Resize

This event is triggered when a user resizes the window.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
heightintegerThe new height of the iframe containing the document.
widthintegerThe new width of the iframe containing the document.
typestringThe type property must be set to resize.
An example of a received event data object
{
    "height":200,
    "width":400,
    "type":"resize"
}

Toggle fullscreen

This event is triggered when a user toggles the fullscreen mode.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
isFullscreenbooleanA boolean indicating if the document is currently showing in fullscreen.
typestringThe type property must be set to toggle_fullscreen.
An example of a received event data object
{
      "isFullscreen":false,
      "type":"toggle_fullscreen"
}
An example of a sent event data object
{
      "type":"toggle_fullscreen"
}

Toggle orientation

This event is triggered when a user toggles the orientation.

Event Information

FormatOnly listenable?
Javascript ObjectNo

Properties

NameTypeDescription
orientationstringThe orientation, can be one of the following possibilities: Portrait or Landscape.
typestringThe type property must be set to toggle_orientation.
An example of a received event data object
{
    "orientation":"landscape",
    "type":"toggle_orientation"
}
An example of a sent event data object
{
    "type":"toggle_orientation"
}

Translate

This event is triggered when a user requests a translation of text in a document.

Event Information

FormatOnly listenable?
Javascript ObjectYes

Properties

NameTypeDescription
languagestringThe language in which the text should be translated, can be one of the following possibilities: bg, cs, da, de, el, en-GB, en-US, es, et, fi, fr, hu, id, it, ja, lt, lv, nl, pl, pt-BR, pt-PT, ro, ru, sk, sl, sv, tr, zh.
textstringThe string of text which should be translated.
typestringThe type property must be set to translate.
An example of a received event data object
{
    "language":"es",
    "string":"This is a test sentence.",
    "type":"translate"
}

Analytics

Readiant tracks detailed, real-time user data of all embedded documents. In the Readiant environment users can generate document specific statistics based on stored document filters and added metadata.

Because Readiant doesn’t have (and doesn’t want to have) access to privacy sensitive end-user data, we only store anonymous end-user activity. This way the statistics generated in the Readiant environment only reflect global anonoymous end-user activity, specified by embedcode or domain.

However, if there is a need to track the patterns of individual users an identifier can be sent as an optional parameter when embedding the document. This way Readiant can generate analytics based upon the patterns of these identifiers.

API Reference

This version of the Readiant API uses a REST API Architecture with JSON data formats. The API follows the standard HTTP request-response exchange.

All endpoints require you to have the following:

API Reference Index

Authentication

Documents

Platform Documents

Embeds

Analytics

Layouts

OAuth 2.0

Readiant implements OAuth 2.0 to provide authorized access to the API.

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supersedes the work done on the original OAuth protocol created in 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

Access Token

Access tokens are the thing that applications use to make API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user’s data.

Access tokens must be kept confidential in transit and in storage. The only parties that should ever see the access token are the application itself, the authorization server, and resource server. The application should ensure the storage of the access token is not accessible to other applications on the same device. The access token can only be used over an https connection, since passing it over a non-encrypted channel would make it trivial for third parties to intercept.

The token endpoint is where apps make a request to get an access token for a user. Access tokens are short lived (3600 seconds). When the service issues the access token it also generates a refresh token that lasts for 14 days and returns that in the response as well.

This endpoint requires basic authentication via a bearer token. The steps to encode an application’s client ID and secret into a set of credentials to obtain a bearer token are:

  1. URL encode the consumer key and the consumer secret according to RFC 1738. Note that at the time of writing, this will not actually change the client id and secret, but this step should still be performed in case the format of those values changes in the future.
  2. Concatenate the encoded client id, a colon character ”:”, and the encoded client secret into a single string.
  3. Base64 encode the string from the previous step.

Resource URL

https://readiant.app/api/oauth2/token.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
grant_typestringrequiredThe grant_type parameter must be set to client_credentials.

Example request

POST /api/oauth2/token.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Basic base64<client_id:client_secret>

{
    "grant_type":"client_credentials"
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"xxxxxxxxxxx",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"xxxxxxxxxxx"
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Refresh Token

The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired.

This allows clients to continue to have a valid access token without further interaction with the user.

This endpoint requires basic authentication via a bearer token. The steps to encode an application’s client ID and secret into a set of credentials to obtain a bearer token are:

  1. URL encode the consumer key and the consumer secret according to RFC 1738. Note that at the time of writing, this will not actually change the client id and secret, but this step should still be performed in case the format of those values changes in the future.
  2. Concatenate the encoded client id, a colon character ”:”, and the encoded client secret into a single string.
  3. Base64 encode the string from the previous step.

Resource URL

https://readiant.app/api/oauth2/token.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
grant_typestringrequiredThe grant_type parameter must be set to refresh_token.
refresh_tokenstringrequiredThe refresh token previously issued to the client.

Example request

POST /api/oauth2/token.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Basic base64<client_id:client_secret>

{
    "grant_type":"refresh_token",
    "refresh_token":"xxxxxxxxxxx"
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"xxxxxxxxxxx",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"xxxxxxxxxxx"
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Revoke Token

This endpoint requires basic authentication via a bearer token. The steps to encode an application’s client ID and secret into a set of credentials to revoke a previously issued refresh token are:

  1. URL encode the consumer key and the consumer secret according to RFC 1738. Note that at the time of writing, this will not actually change the client id and secret, but this step should still be performed in case the format of those values changes in the future.
  2. Concatenate the encoded client id, a colon character ”:”, and the encoded client secret into a single string.
  3. Base64 encode the string from the previous step.

Resource URL

https://readiant.app/api/oauth2/revoke.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
tokenstringrequiredThe refresh token previously issued to the client.
token_type_hintstringrequiredThe token_type_hint parameter must be set to refresh_token.

Example request

POST /api/oauth2/revoke.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Basic base64<client_id:client_secret>
{
    "token":"xxxxxxxxxxx",
    "token_type_hint":"refresh_token",
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Documents

Add Document

Adds a new document for the authenticated user using a PDF/ePub file and if neccesary custom metadata in the FormData.

Metadata can be any key, value combination. Where keys are limited to strings only containing letters and values are limited to strings, numbers, and arrays of strings and numbers.

Note that the amount of documents a user can add depends on the chosen license type.

Resource URL

https://readiant.app/api/documents/add.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescriptionLimit
filePDF / ePubrequiredAn ePub or PDF file to be converted512MB

Example request

POST /api/documents/add.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>
Content-Length: 3532589
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
Cache-Control: no-cache

Content-Disposition: form-data; name="file"; filename="example.pdf

------WebKitFormBoundary--

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": {
    // The ID contains 20 alphanumeric characters
    "id":"xxxxxxxxxxx"
  }
  "messages": [
    "The document has been successfully converted."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Get Document

Returns a single document with all corresponding metadata, specified by the ID parameter.

Resource URL

https://readiant.app/api/documents/get.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the desired document

Example request

GET /api/documents/get.json?id=xxxxxxxxxxx HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": {
    "id":"xxxxxxxxxxx",
    "audio": [{
      "pagesOrChapters": [{
        "pageOrChapter": 5,
        "active": true,
        "characterCount": 2600
      },{
        "pageOrChapter": 6,
        "active": true,
        "characterCount": 800
      }],
      "provider": "google",
      "languageCode": "en-GB",
      "voiceId": "en-GB-Wavenet-B"
    }],
    "chapters": [{
      "title": "Chapter 1",
      "startPage": 5
    },{
      "title": "Chapter 2",
      "startPage": 12
    }],
    "any":"other",
    "added":"metadata",
    "field":1337
  },
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Get Document Text

Returns the raw text of page from a single document.

Resource URL

https://readiant.app/api/documents/text.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the desired document
pageintegerIn case of a PDF-document, request the desired page number
fromPagefloatIn case of an ePub-document, the starting page from which you want to request data
toPagefloatIn case of an ePub-document, the end page to which you want to request data

Example request

GET /api/documents/text.json?id=xxxxxxxxxxx&page=1 HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": {
    "characters": 1339,
    "readingTime": {
      "average": 60,
      "child": 160,
      "fast": 40,
      "slow": 80,
    },
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec blandit, ipsum vitae mattis ultricies, lorem dolor tempus arcu, nec vulputate lorem turpis a eros. Nulla facilisi. Donec sed ligula at nunc volutpat consequat quis et nisl. Aliquam cursus, mauris vitae luctus interdum, ipsum mauris efficitur dolor, et maximus ligula nisl ac sem. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Duis imperdiet metus a egestas luctus. Aenean malesuada pulvinar tempor. Phasellus ut risus arcu. Nam dictum volutpat convallis. Pellentesque pellentesque quis mauris blandit molestie. Aenean efficitur elementum eros id euismod. Donec ut nulla quis velit mattis lobortis non lacinia risus. Praesent non orci ligula. Pellentesque sed cursus nisi. Mauris dapibus, est in egestas elementum, nisl turpis mattis nisi, nec iaculis nunc sapien eget neque. Aenean non orci dolor. Etiam lorem odio, rhoncus et venenatis id, sodales in lacus. Etiam diam quam, suscipit a accumsan ut, convallis iaculis libero. Sed egestas non nibh ut sagittis. Proin viverra metus at enim condimentum, et sodales quam porta. Sed consequat ligula risus, eget interdum odio viverra eget. Aenean in tortor et tortor fringilla eleifend. Nunc ornare, quam malesuada pretium iaculis, orci velit pellentesque mauris, ac rhoncus velit erat eu.",
    "words": 200
  },
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

List Document Texts

Returns the raw text of all pages from a single document.

Resource URL

https://readiant.app/api/documents/texts.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the desired document

Example request

GET /api/documents/texts.json?id=xxxxxxxxxxx HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [{
    "characters": 1339,
    "page": 1,
    "readingTime": {
      "average": 60,
      "child": 160,
      "fast": 40,
      "slow": 80,
    },
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec blandit, ipsum vitae mattis ultricies, lorem dolor tempus arcu, nec vulputate lorem turpis a eros. Nulla facilisi. Donec sed ligula at nunc volutpat consequat quis et nisl. Aliquam cursus, mauris vitae luctus interdum, ipsum mauris efficitur dolor, et maximus ligula nisl ac sem. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Duis imperdiet metus a egestas luctus. Aenean malesuada pulvinar tempor. Phasellus ut risus arcu. Nam dictum volutpat convallis. Pellentesque pellentesque quis mauris blandit molestie. Aenean efficitur elementum eros ID euismod. Donec ut nulla quis velit mattis lobortis non lacinia risus. Praesent non orci ligula. Pellentesque sed cursus nisi. Mauris dapibus, est in egestas elementum, nisl turpis mattis nisi, nec iaculis nunc sapien eget neque. Aenean non orci dolor. Etiam lorem odio, rhoncus et venenatis id, sodales in lacus. Etiam diam quam, suscipit a accumsan ut, convallis iaculis libero. Sed egestas non nibh ut sagittis. Proin viverra metus at enim condimentum, et sodales quam porta. Sed consequat ligula risus, eget interdum odio viverra eget. Aenean in tortor et tortor fringilla eleifend. Nunc ornare, quam malesuada pretium iaculis, orci velit pellentesque mauris, ac rhoncus velit erat eu.",
    "words": 200
  }],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

List Documents

Lists all documents from the authenticated user with all corresponding metadata.

Resource URL

https://readiant.app/api/documents/list.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/documents/list.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [
    {
      "id":"xxxxxxxxxxx",
      "audio": [{
        "pagesOrChapters": [{
          "pageOrChapter": 5,
          "active": true,
          "characterCount": 2600
        },{
          "pageOrChapter": 6,
          "active": true,
          "characterCount": 800
        }],
        "provider": "google",
        "languageCode": "en-GB",
        "voiceId": "en-GB-Wavenet-B"
      }],
      "chapters": [{
        "title": "Chapter 1",
        "startPage": 5
      },{
        "title": "Chapter 2",
        "startPage": 12
      }],
      "any":"other",
      "added":"metadata",
      "field":1337
    }
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Filter Documents

Filter all documents where from the authenticated user with all corresponding metadata.

Resource URL

https://readiant.app/api/documents/filter.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/documents/filter.json?field=1337&added=metadata HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [
    {
      "id":"xxxxxxxxxxx",
      "audio": [{
        "pagesOrChapters": [{
          "pageOrChapter": 5,
          "active": true,
          "characterCount": 2600
        },{
          "pageOrChapter": 6,
          "active": true,
          "characterCount": 800
        }],
        "provider": "google",
        "languageCode": "en-GB",
        "voiceId": "en-GB-Wavenet-B"
      }],
      "chapters": [{
        "title": "Chapter 1",
        "startPage": 5
      },{
        "title": "Chapter 2",
        "startPage": 12
      }],
      "any":"other",
      "added":"metadata",
      "field":1337
    }
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Update Document

Updates a single document with custom metadata, specified by the id parameter.

Metadata can be any key, value combination. Where keys are limited to strings only containing letters and values are limited to strings, numbers, and arrays of strings and numbers.

All updates overwrite any previously stored metadata.

Resource URL

https://readiant.app/api/documents/update.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the document

Example request

PUT /api/documents/update.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Access Token>

{
  "id":"xxxxxxxxxxx",
  "any":"metadata field",
  "can":["also","be","an","array"],
  "or":12345
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The document has been successfully updated."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Delete Document

Deletes a single document with all corresponding metadata, specified by the ID parameter.

Resource URL

https://readiant.app/api/documents/delete.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the document

Example request

DELETE /api/documents/delete.json?id=xxxxxxxxxxx HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The document has been successfully deleted."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Platform Documents

List Available Platforms

Lists all platforms that are able to receive documents.

Resource URL

https://readiant.app/api/platform/list.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/platform/list.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [
    {
      "id":"xxxxxxxxxxx",
      "name":"Platform"
    }
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Share a Document with a Platform

Shares a document of the authenticated user with a platform in Readiant.

Resource URL

https://readiant.app/api/platform/documents/add.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
documentsstring[]requiredThe IDs of the desired documents
platformstringrequiredThe ID of the platform

Example request

POST /api/platform/documents/add.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Access Token>

{
    "documents":["xxxxxxxxxxx"],
    "platform":"xxxxxxxxxxx"
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The document has been successfully added."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Received Documents

Lists all received documents from publishers in Readiant with all corresponding metadata.

Resource URL

https://readiant.app/api/platform/documents/received.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/platform/documents/received.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [
    {
      "id":"xxxxxxxxxxx",
      "any":"other",
      "added":"metadata",
      "field":1337
    }
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Shared Documents

Lists all documents shared with platforms in Readiant.

Resource URL

https://readiant.app/api/platform/documents/shared.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/platform/documents/shared.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [
    {
      "document":"xxxxxxxxxxx",
      "platform":"xxxxxxxxxxx"
    }
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Update Platform Document

Update the conditions of a document that is shared with a platform.

All updates overwrite any previously stored data.

Resource URL

https://readiant.app/api/platform/documents/update.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the document

Example request

PUT /api/platform/documents/update.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Access Token>

{
  "id":"xxxxxxxxxxx",
  "document":"xxxxxxxxxxx",
  "platform":"xxxxxxxxxxx"
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The document has been successfully updated."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Delete Platform Document

Deletes the sharing of a document with a platform in Readiant.

Resource URL

https://readiant.app/api/platform/documents/delete.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
documentsstring[]requiredThe IDs of the documents
platformstringrequiredThe ID of the platform

Example request

POST /api/platform/documents/delete.json HTTP/2
        Host: readiant.app
        Content-Type: application/json
        Accept: application/json
        Authorization: Bearer <Access Token>
        
        {
            "documents":["xxxxxxxxxxx"],
            "platform":"xxxxxxxxxxx"
        }

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The document has been successfully deleted."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Embeds

Add Embedcode

Adds a new embedcode for the authenticated user, corresponding to a specified document.

Recommended flow It's recommended to use temporary embedcodes when presenting documents to reader(s). When a reader requests to read a document, a temporary embedcode should be created on the fly for that document identifier using the API.

A temporary embedcode is active for 1 hour, activity in the reader extends this duration.

Resource URL

https://readiant.app/api/embeds/add.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
documentstringrequiredThe ID of the desired document
domainsstring[]requiredAn array of at least 1 domain from where a reader can read the document via this embedcode
layoutstringrequiredThe ID of the desired reader layout
audiobooleanWhether or not to include audio in the embedcode. (default: true)
fromPageintegerThe starting page from which a reader can read the document via this embedcode
toPageintegerThe last page until which a reader can read the document via this embedcode
pagesinteger[]An array of pages which a reader can read the document via this embedcode
offlinebooleanWhether or not to include the option for offline reading in the embedcode. (default: false)
printablebooleanWhether or not to include the print option in the embedcode. (default: false)
fromDatestring (ISO 8601)The date from which a reader can read the document via this embedcode
toDatestring (ISO 8601)The date until which a reader can read the document via this embedcode
translatablebooleanWhether or not to include the translate option in the embedcode. (default: false)
maxConcurrentUsersintegerRestricts the amount of people that can concurrently read the document via this embedcode
temporarybooleanGenerates an embedcode that can only be accessed temporarily

Example request

POST /api/embeds/add.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Access Token>

{
    "document":"xxxxxxxxxxx",
    "domains":["readiant.app"],
    "fromDate":"2019-01-01T00:00:00+00:00",
    "toDate":"2020-01-01T00:00:00+00:00",
    "pages":[1,2,3,4,5,20],
    "maxConcurrentUsers":1
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": {
    "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "messages": [
    "The embedcode has been successfully added."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Get Embedcode

Returns a single embedcode, specified by the ID parameter.

Resource URL

https://readiant.app/api/embeds/get.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the desired embedcode

Example request

GET /api/embeds/get.json?id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": {
    "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "document":"xxxxxxxxxxx"
    "layout":"xxxxxxxxxxx"
    "fromDate":"2019-01-01T00:00:00+00:00",
    "toDate":"2020-01-01T00:00:00+00:00",
    "maxConcurrentUsers":1,
    "domains":["readiant.app"]
  },
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

List Embedcodes

Lists all embedcodes from the authenticated user.

Resource URL

https://readiant.app/api/embeds/list.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/embeds/list.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [
    {
      "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "document":"xxxxxxxxxxx"
      "layout":"xxxxxxxxxxx",
      "fromDate":"2019-01-01T00:00:00+00:00",
      "toDate":"2020-01-01T00:00:00+00:00",
      "maxConcurrentUsers":1,
      "domains":["readiant.app"]
    }
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Update Embedcode

Updates a single embedcode, specified by the ID parameter.

All updates overwrite any previously stored parameters.

Recommended flow It's recommended to use temporary embedcodes when presenting documents to reader(s). When a reader requests to read a document, a temporary embedcode should be created on the fly for that document identifier using the API.

A temporary embedcode is active for 1 hour, activity in the reader extends this duration.

Resource URL

https://readiant.app/api/embeds/update.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
documentstringrequiredThe ID of the desired document
domainsstring[]requiredAn array of at least 1 domain from where a reader can read the document via this embedcode
layoutstringrequiredThe ID of the desired reader layout
fromPageintegerThe starting page from which a reader can read the document via this embedcode
toPageintegerThe last page until which a reader can read the document via this embedcode
pagesinteger[]An array of pages which a reader can read the document via this embedcode
fromDatestring (ISO 8601)The date from which a reader can read the document via this embedcode
toDatestring (ISO 8601)The date until which a reader can read the document via this embedcode
maxConcurrentUsersintegerRestricts the amount of people that can concurrently read the document via this embedcode

Example request

PUT /api/embeds/update.json HTTP/2
Host: readiant.app
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Access Token>

{
    "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    "document":"xxxxxxxxxxx",
    "domains":["readiant.app"],
    "fromDate":"2019-01-01T00:00:00+00:00",
    "toDate":"2020-01-01T00:00:00+00:00",
    "maxConcurrentUsers":2
}

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The embedcode has been successfully updated."
  ],
  "status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Delete Embedcode

Deletes a single embedcode, specified by the ID parameter.

Resource URL

https://readiant.app/api/embeds/delete.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
idstringrequiredThe ID of the embedcode

Example request

DELETE /api/embeds/delete.json?id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "messages": [
    "The embedcode has been successfully deleted."
  ],
  "status":200
}

Analytics

Lists all sessions from the authenticated application. Generates paginated results, limited to 200 results per page. The sessions are ordered by timestamp and can be combined with the "startAfter" parameter in order to go through the pagination.

Note that the "available" boolean in the response refers to the document if it's still available or if it may have been deleted.

Resource URL

https://readiant.app/api/analytics/list.json

Resource Information

Response formatsRequires authentication?
JSONYes

Parameters

NameTypeRequiredDescription
startnumberA Unix timestamp indicating the starting time at which the analytics should start.
startAfternumberA Unix timestamp indicating the starting time after which the analytics should start.
endnumberA Unix timestamp indicating the starting time at which the analytics should end.
documentstringFilter the analytics by a document identifier.
idstringFilter the analytics based on the identifier value optionally passed to an embedcode.

Example request

GET /api/analytics/list.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "data": [{
    "available":true,
    "document":"xxxxxxxxxxx",
    "events":[{
      "timestamp":1568025846,
      "data":{
        "pages":[1],
        "type":"initial_page"
      }
    }],
    "numberOfPagesViewed":1,
    "pagesViewed":[1],
    "timestamp":1568025846
  }],
  "status":200
}

Layouts

Lists all available layouts from the authenticated user.

Resource URL

https://readiant.app/api/layouts/list.json

Resource Information

Response formatsRequires authentication?
JSONYes

Example request

GET /api/layouts/list.json HTTP/2
Host: readiant.app
Authorization: Bearer <Access Token>

Example response

HTTP/2 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
"data": [
{
"id":"xxxxxxxxxxx",
"Title":"Readiant"
}
],
"status":200
}

Errors

In the event that the API returns an error, we refer you to the Errors section.

Errors

Error responses are served with a non-200-series HTTP code. Usually a JSON response will be attached, but some errors will respond with different kinds of body. In these circumstances where a response structure cannot be parsed, consider the HTTP code's core meaning to take precedence. For instance, you may occasionally see a HTTP 404 along with a HTML response. In this case, it's safe to assume that the content cannot be found (HTTP 404 means "Not Found").

Resource Information

HTTP CodeError Code
403ACCOUNT_NOT_FOUND
404ANALYTICS_NOT_FOUND
404APPLICATION_NOT_FOUND
404CLIENT_NOT_FOUND
404DOCUMENT_NOT_FOUND
404EMBEDCODE_NOT_FOUND
404FILE_NOT_FOUND
404FILTER_NOT_FOUND
500INTERNAL_ERROR
400INVALID_ACCOUNT
400INVALID_CLIENT
400INVALID_DOCUMENT
400INVALID_DOMAINS
400INVALID_EMBEDCODE
400INVALID_FILE
400INVALID_HEADER
400INVALID_PASSWORD
400INVALID_TOKEN
400INVALID_USER
404ISSUES_NOT_FOUND
404LAYOUT_NOT_FOUND
400REQUEST_TOO_COMPLEX
404SESSION_NOT_FOUND
403USER_NOT_FOUND

Example response

HTTP/2 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "code":"ERROR_CODE",
  "messages":[
    "A descriptive error message explaining why the API returns an error message."
  ],
  "status":400
}