Cascade Reading API
The Cascade Reading API is a REST API that provides access to our text processing algorithm. The API accepts a plain text sentence as input and returns cascade-specific metadata about the WordPress or the full sentence in plain text cascaded form. During the beta period, the API only accepts and returns single sentences. The major version for the API is present in
the URL path. e.g.
https://beta.cascadereading.com/v1/cascade/meta
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/meta' \ --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. ParametersAuthorization *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. ParametersAuthorization *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>POST /v1/cascade/text
Takes a single plain text sentence as input and returns the sentence in plain text cascaded form. ParametersAuthorization *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" }
