Thank you! Your feedback helps us improve.

Writing Score API Developer Guide

Included in: Grammarly Enterprise and Grammarly for Education plans

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, tone, and clarity. The Writing Score API is available through the HTTP REST interface, enabling organizations to build custom applications that integrate seamlessly with Grammarly.

How it 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, tone, 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.

Note: Supported document types are DOC, DOCX, ODT, TXT, RTF, and PDF.

Here’s an example of what a custom-built application that uses the Writing Score API might look like:

Writing Score.png

Getting started with the Writing Score API

The Writing Score API is included in Grammarly Enterprise and Grammarly for Education plans.

Interested in upgrading to an Enterprise account? Contact our Sales team.

The API is intended for programmatic consumption and is accessible through an HTTP REST interface. Access to the API requires authentication using an Access Token provided by Grammarly’s OAuth functionality.

Admins can create a Client ID and a Client Secret on the appropriate page of their Admin panel. For more information on managing OAuth credentials, please review this article: Receive OAuth 2.0 credentials

Accessing the Writing Score API

Base URL for accessing the Writing Score API:

https://api.grammarly.com/ecosystem/api/v2/scores

Authentication requests to the API must include an Access Token as the Authorization header with the Bearer type. The scopes required for the Access Token are scores-api:read and scores-api:write.

Examples

Submit writing score request

An example of a cURL request to create a score request:

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" }'

The response body contains the score_request_id and file_upload_url fields, which are required in the next steps.

An example of a response body:

{
 "score_request_id":"401124dd-c774-46af-b652-f6627a4ca5f6",
  "file_upload_url":"https://prod-writingscore-file-upload.s3-exter
  nal-1.amazonaws.com/625270646/401124dd-c774-46af-b652-f6627a4ca5
f6?..."
}

Upload file

Use the file_upload_url from the response to upload the document for scoring. The upload must start before the pre-signed URL expires, which is 120 seconds.

It should be a PUT request without the Authorization header. All security parameters are specified as query attributes of the file_upload_url.

An example of a cURL request to upload a file to the pre-signed URL:

curl -T example.doc <file_upload_url>

Check score status

Use the score_request_id to check the status of the score.

An example of a cURL request to check the score status:

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" }'

An example of a response body:

{
"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 following document formats:

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 .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 the FAILED status.

Common error reason: document_size_exceeds_limit

Max Text Length: 100,000 characters

The text limit is 100,000 characters, including spaces and new lines. Text extracted from a document exceeding the limit will result in the FAILED status.

Common error reason: 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 containing fewer than 30 words will result in an unexpected score status. A document that contains at least 1 word will result in the COMPLETED status with no score (i.e., score is null).

Common error reasons: 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 is 120 seconds. A score request without an uploaded document will result in the FAILED status.

Common error reason: 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 the API for 30 days starting from the date it was requested.

Data Retention

Grammarly retains documents only for the duration necessary to perform the analysis, but not longer than 24 hours.

Was this article helpful?
Tell us what you think. We promise to act on your feedback to make Grammarly's support pages even more helpful.
Have more questions? Submit a request
API