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
- Getting started with the Writing Score API
- Accessing the Writing Score API
- Examples
- Supported document formats
- Constraints
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:
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 |
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.