Plagiarism Detection API (Beta)

Overview

The plagiarism detection API allows organizations to evaluate the authenticity of written content. This API provides a score indicating the originality of the text, helping organizations maintain trust and accountability and ensure proper citation of sources.

This plagiarism detection 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 and is accessible through an HTTP REST interface.

How scoring works

Grammarly compares the text of the uploaded document to billions of web pages and academic papers in private databases, looking for sentences or paragraphs that have been published elsewhere. The API then calculates an originality score— the higher the score, the more original the text.

Accessing Plagiarism Detection API

The base URL for accessing the plagiarism detection API:

https://api.grammarly.com/ecosystem/api/v1/plagiarism

For authentication, API requests must include an Access token as the Authorization header with the Bearer type. For more information, please refer to the OAuth 2.0 article.

The scopes required for the Access token are plagiarism-api:read and plagiarism-api:write.

Requesting a transaction

POST https://api.grammarly.com/ecosystem/api/v1/plagiarism

This API endpoint initiates transactions for plagiarism detection.

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:

curl -X POST \
  'https://api.grammarly.com/ecosystem/api/v1/plagiarism \
  -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 the score_request_id and file_upload_url fields, which will be required in subsequent steps.

Response Parameters

Parameter	Type	Description
score_request_id	String	Request ID that is used to request the plagiarism detection evaluation results.
file_upload_url	String	URL for uploading the requested file.

Example response

An example response body:

{
  "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
Upload the document to be scored using the pre-signed URL from the response, file_upload_url. The upload must start before the pre-signed URL expires, which is in 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:

curl -T example.doc <file_upload_url>

Requesting the evaluation result

GET https://api.grammarly.com/ecosystem/api/v1/plagiarism

This API endpoint returns the result of the plagiarism detection 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:

curl -X GET \
'https://api.grammarly.com/ecosystem/api/v1/plagiarism/<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 score object.

Response Parameters

Parameter	Type	Description
score_request_id	String	Request ID that is used to request the plagiarism detection score evaluation results.
status	String	Request processing status (PENDING, FAILED, COMPLETED).
updated_at	DateTime	Date and time of the status update.
score	Object	Object with the resulting value.
score.originality	Number	A number from 0 to 1 that represents the originality of the text. The higher the score, the more original the text. Therefore, a completely plagiarised text will have a score of 0.

Example response

An example response body:

{
  "score_request_id": "4bed7ce8-95f1-4e84-85d4-8f1e5744f950",
  "status": "COMPLETED",
  "updated_at": "2024-11-18T14:55:27.337443115Z",
  "score": {
    "originality": 0.89
  }
}

Supported Document Formats

The plagiarism 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/v1/plagiarism.

50 requests per second. The maximum number of requests per second is 50 for GET /ecosystem/api/v1/plagiarism/<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.