Access Cascade Reading API Documentation

Introduction

API Overview
Authentication
HTTP Status Codes
Versions
Backwards Compatibility

Endpoints

/v1/cascade/json
/v1/cascade/html
/v1/cascade/text

Cascade Reading API

Cascade Reading provides access to the Cascade algorithm through a REST API suite. This API is the basis for all Cascade service integrations and enables access to all of the capabilities provided by the Cascade algorithm. Input is plain text and output can be plain text, HTML or JSON. Some features of the Cascade algorithm require HTML or JSON and are not available through the plain text service. The minimum input for any Cascade API call is one complete sentence. Efficiency can be gained by sending in multiple sentences per API call up to 32k characters. Larger inputs will take increased time to process. Often paragraphs serve as a good balance between efficiency and processing time. Please consult a Cascade Reading associate for guidance on getting the most from the API service.

The major version for the API is present in the URL path. e.g.

https://live.cascadereading.com/v1/cascade/html

Authentication and Examples

The API supports OAuth client credentials for authentication. Contact Cascade Reading for a client ID and client secret. In order to authenticate with OAuth client credentials you must first request an access token using your client ID and client secret. You can then use your access token to make repeated API requests. Every API call requires a valid access token be submitted with the request. Tokens expire after a period of time and must be renewed to maintain API access.

This example shows how to request an access token using a client ID and client secret:

curl --request POST \ --url 'https://auth.cascadereading.com/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id=YOUR_CLIENT_ID \ --data client_secret=YOUR_CLIENT_SECRET \ --data audience='https://live.cascadereading.com'

Example response:

{ "access_token": "eyfJz4...4j2nzw", "token_type": "Bearer", "expires_in": 86400 }

After you receive an access token, you can make authenticated requests to the Cascade Reading API. The following example shows how to use a valid access token to make an API request:

curl --request POST \ 'https://live.cascadereading.com/v1/cascade/html' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "text": "This is a sentence." }'

HTTP Status Codes and Responses

The service attempts to return appropriate HTTP status code for every request. The status code can be used to determine an appropriate action based on the result. In the unlikely event an error occurs that precludes a response the request can be resubmitted for proper processing.

HTTP status codes

200 - OK

A request succeeded. For an example see POST /v1/cascade/html.

401 – Unauthorized

The request failed due to an invalid access token.

500 – Server Error

The server encountered an error and could not provide a response.

Versions

The major version for the API is present in the URL path. In the provided example the version is represented by the value “v1”. A change in version number would imply a breaking change in the input or output format and at this time only version 1 is supported.

URL Path

https://live.cascadereading.com/v1/cascade/json

Backwards Compatibility

The API spec follows semantic versioning. We won’t introduce backwards-incompatible changes to a major version of the API. If backwards-incompatible changes are necessary to support new features, then a new major version of the API will be introduced. When a new major version is introduced, both the new version and the prior version will be supported simultaneously. Prior versions of the API will eventually be deprecated and removed.

Backwards-compatible changes include:

Adding a new attribute to an existing object.
Adding a new API path.

Backwards-incompatible changes include:

Changing or removing an existing path name.
Changing or removing an existing object name.
Changing or removing an existing attribute name.

POST /v1/cascade/json

Takes at a minimum a single plain text sentence as input and returns Cascade metadata in JSON format that defines line breaks, indentations and other useful information. Sending multiple sentences in the input is advised if a large quantity of text is to be processed. Often a paragraph at a time is a good compromise between latency and throughput. This endpoint does not automatically provide the sentence in Cascaded form. You can use the metadata to format the sentence however you wish: plain text, HTML, markdown, etc.

Parameters

Authorization *Required
A valid OAuth access token.

Request Application/json

{"text": "When the men hunt, the birds with bright feathers typically scatter."}

Response Code 200 Application/json

{ "sentences": [ { "original_sentence": "When the men hunt, the birds with bright feathers typically scatter.", "json_cascade": [ { "indent_level": 0, "line": "When the men" }, { "indent_level": 0, "line": "hunt," }, { "indent_level": 0, "line": "the birds" }, { "indent_level": 1, "line": "with bright feathers" }, { "indent_level": 1, "line": "typically" }, { "indent_level": 0, "line": "scatter" } ], "errors": [] } ] }

POST /v1/cascade/html

Takes at a minimum a single plain text sentence as input and returns Cascade HTML that defines line breaks and indentations. Sending multiple sentences in the input is advised if a large quantity of text is to be processed. Often a paragraph at a time is a good compromise between latency and throughput. This endpoint does not automatically provide the sentence in Cascaded form. You can use CSS to control the appearance of the Cascade. Cascade Reading can provide various examples of CSS that will effectively format the Cascaded Text for various purposes.

Parameters

Authorization *Required
A valid OAuth access token.

Request Application/json

{"text": "When the men hunt, the birds with bright feathers typically scatter."}

Response Code 200 Application/json

{ "sentences": [ { "original_sentence": "When the men hunt, the birds with bright feathers typically scatter.", "html_cascade": "

<div class="cascade-node has-children tier-0"><span class="cascade-text">When</span><div class="cascade-node tier-1"><span class="cascade-text">the men hunt,</span></div><div class="cascade-node has-children tier-1"><span class="cascade-text">the birds</span><div class="cascade-node has-children tier-2"><span class="cascade-text">with</span><div class="cascade-node tier-3"><span class="cascade-text">bright feathers</span></div></div><div class="cascade-node has-children tier-2"><span class="cascade-text">typically</span><div class="cascade-node"><span class="cascade-text">scatter.</span></div></div></div></div>

", "errors": [] } ] }

POST /v1/cascade/text

Takes at a minimum a single plain text sentence as input and returns the sentence in plain text cascaded form. Sending multiple sentences in the input is advised if a large quantity of text is to be processed. Often a paragraph at a time is a good compromise between latency and throughput. The output from this call is the simplest format for Cascaded Text and works well in plain text environments or for copy/paste.

Parameters

Authorization *Required
A valid OAuth access token.

Request Application/json

{ "text": "When the men hunt, the birds with bright feathers typically scatter.", "indentation_character": "tab", "count": 2 }

Response Code 200 Application/json

{ "sentences": [ { "original_sentence": "When the men hunt, the birds with bright feathers typically scatter.", "text_cascade": "When the men\nhunt,\nthe birds\n with bright feathers\n typically\nscatter.\n" "errors": [] } ] }

Response Code 401 Application/json

{ "message": "Unauthorized request" }

Response Code 422 Application/json

{ "message": "Unprocessable Entity" }