AI Detection API (Beta)
Overview
The AI Detection API allows organizations to evaluate the authenticity of written content by estimating the likelihood it was generated by AI tools. This API provides a score indicating the confidence level that a document was AI-generated and the percentage of text that appears AI-generated, helping organizations maintain trust, accountability, and responsible AI usage in their workflows.
This AI 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 breaks down your text into smaller sections, checking each section against the model for patterns that are typically present in AI-generated text (language patterns, syntax, and complexity). Grammarly then returns a percentage score indicating how much of the provided text appears AI-generated and an average confidence level that the text is AI-generated. Our extensive machine-learning model is trained on hundreds of thousands of human and AI-generated texts. It assesses whether text resembles AI-generated writing, but, like other AI text checkers, it cannot provide a definitive conclusion. You can learn more in this article: How to use Grammarly’s AI detection
Accessing AI Detection API
The base URL for accessing the AI Detection API:
https://api.grammarly.com/ecosystem/api/v1/ai-detection
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 ai-detection-api:read and ai-detection-api:write.
Requesting a transaction
POST https://api.grammarly.com/ecosystem/api/v1/ai-detection
This API endpoint initiates transactions for AI 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:
bash
curl -X POST \
'https://api.grammarly.com/ecosystem/api/v1/ai-detection \
-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 AI detection evaluation results. |
file_upload_url | String | URL for uploading the requested file. |
Example response
An example response body:
json
{
"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
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 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:
bash
curl -T example.doc <file_upload_url>
Requesting the evaluation result
GET https://api.grammarly.com/ecosystem/api/v1/ai-detection
This API endpoint returns the result of the AI 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:
bash
curl -X GET \
'https://api.grammarly.com/ecosystem/api/v1/ai-detection/<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 AI 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.average_confidence | Number | The number that represents the confidence that the document is AI-generated. |
score.ai_generated_percentage | Number | A decimal number between 0 and 1, which represents the percentage of the document that was AI-generated. |
Example response
An example response body:
json
{
"score_request_id": "4bed7ce8-95f1-4e84-85d4-8f1e5744f950",
"status": "COMPLETED",
"updated_at": "2024-11-18T14:55:27.337443115Z",
"score": {
"average_confidence": 0.89,
"ai_generated_percentage": 0.5
}
}Supported Document Formats
The AI Detection 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 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/ai-detection.
50 requests per second. The maximum number of requests per second is 50 for GET /ecosystem/api/v1/ai-detection/\<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.