Cascade Reading, Comprehend more logo.

Cascade Reading API

The Cascade Reading API is a REST API that provides access to our text processing algorithm. The API accepts plain text as input and returns Cascaded Text and specific metadata about each word and the full sentences. 

The major version for the API is present in the URL path. e.g.
https://beta.cascadereading.com/v1/cascade/html

Authentication and Examples

The API supports OAuth client credentials for authentication. Contact us for a client ID and client secret. In order to authenticate with OAuth client credentials, first you request an access token using your client ID and client secret. Then you can use your access token to make API requests. Every API request requires a valid access token.

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://beta.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://beta.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 API attempts to return appropriate HTTP status codes for every request.

HTTP status codes
200 - OK
A request succeeded. For an example see POST /v1/cascade/meta.
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. e.g.

URL Path
https://beta.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 a single plain text sentence as input and returns Cascade metadata that defines line breaks, indentations and other useful information. 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 a single plain text sentence as input and returns Cascade HTML that defines line breaks and indentations. This endpoint does not automatically provide the sentence in Cascaded form. You can use CSS to control the appearance of the Cascade.

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 a single plain text sentence as input and returns the sentence in plain text cascaded form.

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" }
Cascade Reading

How was your experience?

Feedback(Required)