Writing Score API
Overview
The Writing Score API allows organizations to evaluate the quality of individual written documents by receiving an overall Grammarly score, as well as separate scores in four categories: engagement, correctness, delivery, and clarity.
This Writing Score API developer guide explains how to create a score request, upload a document for scoring, and get the document scoring status and result.
The API is intended for programmatic consumption, enabling organizations to build custom applications that integrate seamlessly with Grammarly. Organizations can access the API through an HTTP REST interface.
How scoring works
The Writing Score API receives a document and extracts the text from it. The extracted text is initially assumed to be 100% correct. Grammarly then generates writing suggestions in four categories: engagement, correctness, delivery, and clarity. The suggestions are then prioritized and weighted. Finally, Grammarly calculates a score based on the suggestions and subtracts that score from the original 100% score. The resulting score is returned in the response to the API request.
Accessing Writing Score API
The base URL for accessing the Writing Score API is
https://api.grammarly.com/ecosystem/api/v2/scores
For authentication, requests to the API must include an Access token as the Authorization header with a type of Bearer. For details, please refer to the OAuth 2.0 section.
The scopes required for the Access token are scores-api:read and scores-api:write.
Submit writing score request
POST https://api.grammarly.com/ecosystem/api/v2/scores
This API endpoint initiates transactions for the writing score calculation.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
filename | String | Yes | Name of the file that will be uploaded |
Example Request
An example cURL request to create a score request:
bash
curl -X POST \
'https://api.grammarly.com/ecosystem/api/v2/scores' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'user-agent: API client' \
-d '{ "filename": "example.doc" }'Response Format
The response body contains fields score_request_id and file_upload_url, which will be required in subsequent steps.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
score_request_id | String | Request ID, which is used to request the writing score evaluation results. |
file_upload_url | String | URL that has to be used to upload the requested file. |
Example response
json
{
"score_request_id":"401124dd-c774-46af-b652-f6627a4ca5f6",
"file_upload_url":"https://prod-writingscore-file-upload.s3-external-1.amazonaws.com/625270646/401124dd-c774-46af-b652-f6627a4ca5f6?..."
}Upload file
Using the pre-signed URL from the response, file_upload_url, upload the document to be scored. The upload must start before the pre-signed URL expires, which is 120 seconds.
This request is a simple PUT request that does not require the Authorization header. All security parameters are specified as query attributes of file_upload_url.
An example cURL request to upload a file to the pre-signed URL:
bash
curl -T example.doc <file_upload_url>Requesting the evaluation result
GET https://api.grammarly.com/ecosystem/api/v2/scores/\<score_request_id>
This API endpoint returns the result of the writing score evaluation
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
score_request_id | String | Yes | Request ID from the previous step. |
Example Request
An example cURL request to check the status of the score:
bash
curl -X GET \
'https://api.grammarly.com/ecosystem/api/v2/scores/<score_request_id>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Accept: application/json' \
-H 'user-agent: API client'Response Format
The response body contains fields describing the status of the evaluation process. If evaluation results are ready, they are provided in the object score.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
score_request_id | String | The request ID is used to request the writing score evaluation results. |
status | String | Request processing status (PENDING, FAILED, COMPLETED). |
updated_at | DateTime | DateTime when the status was updated. |
score | Object | Object with the resulting values. |
score.general_score | Number | The overall score represents the quality of writing in this document. |
score.engagement | Number | The engagement score highlights the potential to make the writing more engaging. |
score.correctness | Number | The correctness score reflects issues related to spelling, punctuation, and grammar. |
score.delivery | Number | The delivery score assesses striking the right balance of politeness, formality, and friendliness. |
score.clarity | Number | The clarity score signifies potential clarity and conciseness improvements. |
Example response
An example response body:
json
{
"score_request_id":"401124dd-c774-46af-b652-f6627a4ca5f6",
"status":"COMPLETED",
"updated_at":"2024-04-02T17:09:20.588388505Z",
"score":{
"general_score":0.86,
"engagement":0.86,
"correctness":0.89,
"delivery":0.86,
"clarity":0.83
}
}Supported Document Formats
The Writing Score API supports the document formats listed below.
| Format | MIME type | Extension |
|---|---|---|
| Microsoft Word | application/msword | .doc |
| Microsoft Word (OpenXML) | application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
| OpenDocument Text | application/vnd.oasis.opendocument.text | .odt |
| Text | text/plain | .txt |
| Rich Text Format | application/rtf | .rtf |
| (Adobe) Portable Document Format | application/pdf |
Constraints
Max File Size
4 MB. The file size limit is 4 megabytes (MB) or 4,194,304 bytes. Uploaded documents larger than 4 MB will result in FAILED status.
Common error reason(s): document_size_exceeds_limit
Max Text Length
100,000 characters. The text limit is 100,000 characters, including white space. Text extracted from a document exceeding the limit will result in FAILED status.
Common error reason(s): content_length_exceeds_limit
Minimum Text Length
30 words. The minimum word count is 30, including special characters (e.g., emoji). Text extracted from a document with less than 30 words will result in an unexpected score status. A document that contains at least 1 word will result in COMPLETED with no score (i.e., score is null).
Common error reason(s): file_upload_failed (blank document, 0 bytes), text_extraction_failed (blank document, > 0 bytes)
Max Timeout Duration
120 seconds. The maximum duration for uploading a document after submitting a score request (creation) is 120 seconds. A score request without an uploaded document will result in FAILED status.
Common error reason(s): document_text_not_found
Score Variance
Score results may vary for document formats that support content other than text (e.g., images, macros, metadata).
Max Request Rates
Consider exponential backoff to handle requests with status code 429. Load test results indicate an ideal base factor of 2 seconds.
10 requests per second. The maximum number of requests per second is 10 for POST /ecosystem/api/v2/scores.
50 requests per second. The maximum number of requests per second is 50 for GET /ecosystem/api/v2/scores/<score_request_id>.
Score Retention
The score is accessible via API for 30 days starting when it was requested.
Data Retention
Grammarly retains documents only for the duration necessary to perform the analysis, but not longer than 24 hours.