• Readiant
• Converter
• Documents
• Distributor
• Analytics
• Embed
• Events
• Event Reference
• API Reference
• OAuth 2.0
• Documents
• Platform Documents
• Embeds
• Analytics
• Layouts
• Errors

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.

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

• Set a period in which the book can be read
• Set a limit on the number of concurrent readers
• Set a limit on the amount of pages that can be read
• Set a custom layout
• More features will be added in the future

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

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.

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.

// 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

• Ready state

Navigation

• Initial navigation
• Direct navigation
• Next page
• Previous page
• Closing navigation

Annotations

• Annotations
• Add annotations

Audio

• Audio play
• Audio pause
• Change audio highlighting
• Change audio playback rate

Usage

• Change colorblind filter
• Change countdown type
• Change font
• Change font size
• Change image quality
• Change letter spacing
• Change line height
• Change read stop
• Change screen mode
• Change subtitle
• Change subtitle font size
• Change text mode
• Change word spacing
• Change zoom level
• Print
• Resize
• Toggle fullscreen
• Toggle orientation
• Translate

Ready state

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

Event Information

Properties

{
    "type":"ready"
}

Initial navigation

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

Event Information

Properties

{
    "pages":[4,5],
    "type":"initial_page"
}

Direct navigation

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

Event Information

Properties

{
    "pages":[10,11],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 0.51
                },
                "page": 1
            }
        ]
    },
    "type":"goto_page"
}

{
    "pages":[5],
    "type":"goto_page"
}

Next page

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

Event Information

Properties

{
    "pages":[10,11],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 0.23
                },
                "page": 8
            },
            {
                "audio": {
                    "playbackPercentage": 0.83
                },
                "page": 9
            }
        ]
    },
    "type":"next_page"
}

{
    "type":"next_page"
}

Previous page

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

Event Information

Properties

{
    "pages":[4,5],
    "previous":
    {
        "duration":3413431,
        "pages": [
            {
                "audio": {
                    "playbackPercentage": 1
                },
                "page": 6
            },
            {
                "audio": {
                    "playbackPercentage": 0.24
                },
                "page": 7
            }
        ]
    },
    "type":"previous_page"
}

{
    "type":"previous_page"
}

Closing navigation

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

Event Information

Properties

{
    "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

Properties

{
    "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

Properties

{
    "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

Properties

{
    "type":"audio_play"
}

{
    "type":"audio_play"
}

Audio Pause

This event is triggered when a user pauses the audio.

Event Information

Properties

{
    "type":"audio_pause"
}

{
    "type":"audio_pause"
}

Change audio highlighting

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

Event Information

Properties

{
    "audioHighlightingLevel":2,
    "type":"change_audio_highlighting"
}

{
    "audioHighlightingLevel":3,
    "type":"change_audio_highlighting"
}

Change audio playback rate

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

Event Information

Properties

{
    "playbackRate":1.2,
    "type":"change_playback_rate"
}

{
    "playbackRate":0.7,
    "type":"change_playback_rate"
}

Change colorblind filter

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

Event Information

Properties

{
    "colorBlindFilter":"Grayscale",
    "type":"change_color_blind_filter"
}

{
    "colorBlindFilter":"Protonopia",
    "type":"change_color_blind_filter"
}

Change countdown type

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

Event Information

Properties

{
    "countdownLevel":2,
    "type":"change_countdown"
}

{
    "countdownLevel":3,
    "type":"change_countdown"
}

Change font

This event is triggered when a user changes the font.

Event Information

Properties

{
    "font":"Dyslexia",
    "type":"change_font"
}

{
    "font":"Roboto",
    "type":"change_font"
}

Change font size

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

Event Information

Properties

{
    "fontSize":12,
    "type":"change_font_size"
}

{
    "fontSize":3,
    "type":"change_font_size"
}

Change image quality

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

Event Information

Properties

{
    "imageQuality":"2g",
    "imageQualityLevel":2,
    "type":"change_image_quality"
}

{
    "imageQualityLevel":3,
    "type":"change_image_quality"
}

Change letter spacing

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

Event Information

Properties

{
    "letterSpacing":2,
    "type":"change_letter_spacing"
}

{
    "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

Properties

{
    "lineHeight":2,
    "type":"change_line_height"
}

{
    "lineHeight":1,
    "type":"change_line_height"
}

Change read stop

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

Event Information

Properties

{
    "readStopLevel":2,
    "type":"change_read_stop"
}

{
    "readStopLevel":3,
    "type":"change_read_stop"
}

Change screen mode

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

Event Information

Properties

{
    "screenModeLevel":2,
    "type":"change_screen_mode"
}

{
    "screenModeLevel":1,
    "type":"change_screen_mode"
}

Change subtitle

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

Event Information

Properties

{
    "subtitleLevel":2,
    "type":"change_subtitle"
}

{
    "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

Properties

{
    "subtitleFontSize":2,
    "type":"change_subtitle_font_size"
}

{
    "subtitleFontSize":3,
    "type":"change_subtitle_font_size"
}

Change text mode

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

Event Information

Properties

{
    "textModeLevel":2,
    "type":"change_text_mode"
}

{
    "textModeLevel":3,
    "type":"change_text_mode"
}

Change word spacing

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

Event Information

Properties

{
    "wordSpacing":4,
    "type":"change_word_spacing"
}

{
    "wordSpacing":1,
    "type":"change_word_spacing"
}

Change zoom level

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

Event Information

Properties

{
    "zoomLevel":2,
    "type":"change_zoom_level"
}

{
    "zoomLevel":3,
    "type":"change_zoom_level"
}

Print

This event is triggered when a user prints a page.

Event Information

Properties

{
    "pages":[2,3],
    "type":"print"
}

Resize

This event is triggered when a user resizes the window.

Event Information

Properties

{
    "height":200,
    "width":400,
    "type":"resize"
}

Toggle fullscreen

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

Event Information

Properties

{
      "isFullscreen":false,
      "type":"toggle_fullscreen"
}

{
      "type":"toggle_fullscreen"
}

Toggle orientation

This event is triggered when a user toggles the orientation.

Event Information

Properties

{
    "orientation":"landscape",
    "type":"toggle_orientation"
}

{
    "type":"toggle_orientation"
}

Translate

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

Event Information

Properties

{
    "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:

• A Readiant account
• A registered client
• A developer environment setup
• Authentication

API Reference Index

Authentication

• POST - /api/oauth2/token.json (Access Token)
• POST - /api/oauth2/token.json (Refresh Token)
• POST - /api/oauth2/revoke.json

Documents

• POST - /api/documents/add.json
• GET - /api/documents/get.json
• GET - /api/documents/text.json
• GET - /api/documents/texts.json
• GET - /api/documents/list.json
• GET - /api/documents/filter.json
• PUT - /api/documents/update.json
• DELETE - /api/documents/delete.json

Platform Documents

• POST - /api/platform/documents/add.json
• GET - /api/platform/documents/received.json
• GET - /api/platform/documents/shared.json
• PUT - /api/platform/documents/update.json
• DELETE - /api/platform/documents/delete.json

Embeds

• POST - /api/embeds/add.json
• GET - /api/embeds/get.json
• GET - /api/embeds/list.json
• PUT - /api/embeds/update.json
• DELETE - /api/embeds/delete.json

Analytics

• GET - /api/analytics/list.json

Layouts

• GET - /api/layouts/list.json

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

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

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

Parameters

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

Parameters

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

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

Parameters

Example request

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

{
    "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 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

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

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

Parameters

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

Parameters

Example request

DELETE /api/platform/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.

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

Parameters

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

Parameters

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

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

Parameters

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

Parameters

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

Parameters

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

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

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
}