Text assessment

Text submitted to the API is assessed using an 'assessment pipeline' which consists of a particular combination of scoring models and other assessment functionality. For example, the scoring model could be one that returns scores on the CEFR scale, or the IELTS scale. Error detection and suggested corrections is another feature which depends on the configuration of the assessment pipeline. Different API clients can have differing assessment pipelines depending on the client's requirements.

Submitting text for assessment

Request

Method and URI:

PUT /VERSION/account/ACCOUNT_ID/text/ID

Request parameters:

Request body JSON:

{"text": "Some text to be assessed", "author_id": "id of the author", "task_id" : "id of the task", "question_text": "The text of the question being asked"}

The attribute values are as follows:

Response

Successful submission

HTTP status code: 200

Response body JSON:

{"type": "success", "code": 200}

Failed submission

Submission can fail for a number of reasons. The general response format is as follows:

HTTP status code: 400

Example response body JSON:

{"type": "error", "code": 400, "message": "id already exists"}

type is always "error". The message attribute value can vary depending on the specific error as shown by the examples below.

Some errors can occur before the validation of each attribute is performed:

Retrieving text assessment results

Request

GET /VERSION/account/ACCOUNT_ID/text/ID/results

Parameters:

Response

Results successfully retrieved

HTTP status code: 200

Example response body JSON:

{
 "type": "success", "code": 200, "overall_score": 7.3,
 "score_dimensions": {"prompt_relevance": 3.0},
 "sentence_scores": [[0, 5, -0.23], [6, 42, 0.56]],
 "suspect_tokens": [[0, 5], [40, 42]],
 "textual_errors": [[0, 5, "Greetings", "S"], [32, 35, "the", "MD+"]],
 "text_stats": {"r1": 0.333333, "r2": 0.103448, "r3": 0.0, "lcs": 7.0, "feature_count": 344.0, "word_count": 36.0}
}

Some of the attributes can be absent or empty, depending on the assessment pipeline in use. This is indicated in the attribute's description in the following table.

Results not retrieved

In addition to the general possible responses outlined earlier in this document, there are a few specific reasons why results may not be retrieved.

Waiting for results

The system generally takes a few seconds to assess a piece of text. If results for a piece of text are not available when this API endpoint is called, the anticipated time remaining until the results will be available is returned in the estimated_seconds_to_completion response attribute. A client which wants to receive results as soon as possible (for example, because it needs to return results to its users as quickly as possible) should not poll in a tight loop, but must wait at least 1 second before requesting results again. A client which does not need results as quickly as possible can of course wait an arbitrary amount of time before requesting results again. In either case, a more sophisticated approach might take into account the estimated seconds to completion, instead of polling at a fixed time interval. However, note that the estimated seconds to completion is only a guide. Assessment of a particular piece of text may be faster or slower than expected, depending on its characteristics. If it is slower than expected, the estimated seconds to completion could reach 0 and remain there until the text has completed assessment.

Deleting submissions by an author

Text submissions and their results can be deleted by specifying the author whose submissions should be deleted. If no submissions are found when searching using the specified author ID, this API call will not return an error, but will instead say that 0 submissions were deleted.

If a deletion API call for the same author ID is made multiple times the same result will be returned, assuming no submissions with the author ID are made in between. For example, if a deletion request is made and reports that 2 submissions were deleted and the same deletion request is made again, it will still respond that 2 submissions were deleted, along with the timestamp that the original deletion request was processed.

Request

DELETE /VERSION/account/ACCOUNT_ID/author/ID

Parameters:

Response

Success

HTTP status code: 200

Example response body JSON:

{
  "type":"success","code":200,"submissions_deleted":2,"timestamp":"2018-09-11T11:15:14Z"
}

Failure

The request can fail if the author ID format is invalid.

HTTP status code: 400

Example response body JSON:

{"type": "error", "code": 400, "message": "id too long"}

type is always "error". The message attribute value can vary depending on the specific error as shown by the examples below.