POST https://api.copyleaks.com/v1/writing-feedback/{scanId}/check

Use Copyleaks Writing Assistant to generate grammar, spelling and sentence corrections for a given text.

This endpoint will receive submitted text to be checked. The response will show the suggested corrections to the input text.

Authentication Required

You need to login with a user and API key in order to access this method. Add this HTTP header to your request:

Authorization: Bearer < Your-Login-Token >

Request

Path Parameters

scanId string Required

A unique scan id provided by you. We recommend you use the same id in your database to represent the scan in the Copyleaks database. This will help you to debug incidents. Using the same ID for the same file will help you to avoid network problems that may lead to multiple scans for the same file. learn more about the criteria for creating a Scan ID.

>= 3 characters <= 36 characters

Match pattern: [a-z0-9] !@$^&-+%=_(){}<>';:/.",~|

Headers

Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

Request Body

The request body is a JSON object containing the text to scan.

text string Required

Text to produce Writing Assistant report for.

>= 1 characters <= 25000 characters

sandbox boolean default: "false"

Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.

Submit content for Writing Assistant and get returned mock results, simulating Copyleaks’s API functionality to ensure you have successfully integrated the API.

This feature is intended to be used for development purposes only.

score object

grammarScoreWeight number<float> default: "1.0"

Grammar correction category weight in the overall score.

>= 0.0 <=1.0

mechanicsScoreWeight number<float> default: "1.0"

Mechanics correction category weight in the overall score.

>= 0.0 <=1.0

sentenceStructureScoreWeight number<float> default: "1.0"

Sentence structure correction category weight in the overall score.

>= 0.0 <=1.0

wordChoiceScoreWeight number<float> default: "1.0"

Word choice correction category weight in the overall score.

>= 0.0 <=1.0

language string

The language code of your content. The selected language should be on the Supported Languages list above. If the ‘language’ field is not supplied , our system will automatically detect the language of the content.

Example: "en"

Responses

200

200 OK

The command was executed.

Response Schema

The response contains the following fields:

score object

Writing quality analysis and scores.

corrections object

Detailed correction scores and counts.

grammarCorrectionsCount integer

Number of grammar corrections needed.

grammarCorrectionsScore integer

Grammar quality score (0-100).

grammarScoreWeight number

Weight applied to grammar score.

mechanicsCorrectionsCount integer

Number of mechanics corrections needed.

mechanicsCorrectionsScore integer

Mechanics quality score (0-100).

mechanicsScoreWeight number

Weight applied to mechanics score.

sentenceStructureCorrectionsCount integer

Number of sentence structure corrections needed.

sentenceStructureCorrectionsScore integer

Sentence structure quality score (0-100).

sentenceStructureScoreWeight number

Weight applied to sentence structure score.

wordChoiceCorrectionsCount integer

Number of word choice corrections needed.

wordChoiceCorrectionsScore integer

Word choice quality score (0-100).

wordChoiceScoreWeight number

Weight applied to word choice score.

overallScore integer

Overall writing quality score (0-100).

readability object

Readability analysis and metrics.

score integer

Readability score (0-100).

readabilityLevel integer

Reading grade level.

readabilityLevelText string

Human-readable description of reading level.

readabilityLevelDescription string

Detailed description of reading difficulty.

statistics object

Text statistics and analysis.

sentenceCount integer

Number of sentences in the text.

averageSentenceLength number

Average number of words per sentence.

averageWordLength number

Average length of words in characters.

readingTimeSeconds number

Estimated reading time in seconds.

speakingTimeSeconds number

Estimated speaking time in seconds.

corrections object

Detailed correction information with text positions.

text object

Text correction data with character positions and suggestions.

scannedDocument object

Metadata about the scan.

scanId string

The unique identifier for this scan.

totalWords integer

Total number of words analyzed.

totalExcluded integer

Number of words excluded from analysis.

actualCredits integer

Credits actually consumed for this scan.

expectedCredits integer

Expected credits for this scan.

creationTime string

ISO 8601 timestamp when the scan was created.

Example Response

A typical response from this endpoint:

Show full example (102 lines)

{
  "score": {
    "corrections": {
      "grammarCorrectionsCount": 2,
      "grammarCorrectionsScore": 87,
      "grammarScoreWeight": 1,
      "mechanicsCorrectionsCount": 9,
      "mechanicsCorrectionsScore": 38,
      "mechanicsScoreWeight": 1,
      "sentenceStructureCorrectionsCount": 0,
      "sentenceStructureCorrectionsScore": 100,
      "sentenceStructureScoreWeight": 1,
      "wordChoiceCorrectionsCount": 1,
      "wordChoiceCorrectionsScore": 93,
      "wordChoiceScoreWeight": 1,
      "overallScore": 79
    },
    "readability": {
      "score": 59,
      "readabilityLevel": 5,
      "readabilityLevelText": "10th to 12th Grader",
      "readabilityLevelDescription": "Fairly difficult to read"
    },
    "statistics": {
      "sentenceCount": 5,
      "averageSentenceLength": 12.2,
      "averageWordLength": 5.5,
      "readingTimeSeconds": 16,
      "speakingTimeSeconds": 28.2
    }
  },
  "corrections": {
    "text": {
      "chars": {
        "types": [
          5,
          18,
          3,
          18,
          18,
          18,
          18,
          10,
          18,
          16,
          18,
          18
        ],
        "starts": [
          13,
          22,
          61,
          104,
          118,
          136,
          179,
          233,
          288,
          347,
          353,
          374
        ],
        "lengths": [
          2,
          10,
          9,
          6,
          8,
          35,
          13,
          9,
          12,
          4,
          8,
          11
        ],
        "operationTexts": [
          "an ",
          "plagiarism ",
          "businesses ",
          "their ",
          "original.",
          "texts from the internet and data bases ",
          "similarities.",
          "multilingual ",
          "positives, ",
          "it's ",
          "useful ",
          "maintaining "
        ]
      }
    }
  },
  "scannedDocument": {
    "scanId": "{scanId}",
    "totalWords": 61,
    "totalExcluded": 0,
    "actualCredits": 1,
    "expectedCredits": 1,
    "creationTime": "2025-08-06T08:00:08.0429909Z"
  }
}

{
  "score": {
    "corrections": {
      "grammarCorrectionsCount": 2,
      "grammarCorrectionsScore": 87,
      "grammarScoreWeight": 1,
      "mechanicsCorrectionsCount": 9,
      "mechanicsCorrectionsScore": 38,
      "mechanicsScoreWeight": 1,
      "sentenceStructureCorrectionsCount": 0,
      "sentenceStructureCorrectionsScore": 100,
      "sentenceStructureScoreWeight": 1,
      "wordChoiceCorrectionsCount": 1,
      "wordChoiceCorrectionsScore": 93,
      "wordChoiceScoreWeight": 1,
// ... truncated

400

400 Bad Request

Bad request.

401

401 Unauthorized

Authorization has been denied for this request.

402

402 Payment Required

User does not have enough credits.

429

429 Too Many Requests

Too many requests have been sent. The request has been rejected.

Examples

HTTP

POST https://api.copyleaks.com/v1/writing-feedback/my-scan-123/check
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

{
  "text": "Copyleaks is a comprehensive plagiarism detection platform that performs extensive searches across 60 trillion websites, 15,000+ academic journals, 20+ code data repositories, and 1M+ internal documents. Using AI-powered text analysis, easily scan documents, raw text, code, and URLs and instantly receive detailed reporting on the findings."
}

cURL

curl --request POST \
  --url https://api.copyleaks.com/v1/writing-feedback/my-scan-123/check \
  --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Copyleaks is a comprehensive plagiarism detection platform that performs extensive searches across 60 trillion websites, 15,000+ academic journals, 20+ code data repositories, and 1M+ internal documents. Using AI-powered text analysis, easily scan documents, raw text, code, and URLs and instantly receive detailed reporting on the findings."
  }'

Python

import requests

# Sample text to analyze for writing feedback
sample_text = """Copyleaks is a comprehensive plagiarism detection platform that performs extensive searches across 60 trillion websites, 15,000+ academic journals, 20+ code data repositories, and 1M+ internal documents. Using AI-powered text analysis, easily scan documents, raw text, code, and URLs and instantly receive detailed reporting on the findings."""

url = "https://api.copyleaks.com/v1/writing-feedback/my-scan-123/check"
payload = {
    "text": sample_text
}
headers = {
    "Authorization": "Bearer YOUR_LOGIN_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print("Writing Feedback Results:")
if 'score' in result:
    print(f"Overall Score: {result['score'].get('overallScore', 'N/A')}")
    print(f"Grammar Score: {result['score'].get('grammarCorrectionsScore', 'N/A')}")
    print(f"Mechanics Score: {result['score'].get('mechanicsCorrectionsScore', 'N/A')}")

print("Full response:", result)

JavaScript

const { Copyleaks, CopyleaksWritingAssistantSubmissionModel } = require('plagiarism-checker');

async function getWritingFeedback() {
    try {
        // Initialize Copyleaks
        const copyleaks = new Copyleaks();

        // Login to get the authentication token object.
        // Replace with your email and API key.
        const loginResult = await copyleaks.loginAsync('[email protected]', 'YOUR_API_KEY');

        const scanId = "my-scan-123";

        // The text to be checked
        const textToCheck = "This is a sample text to check for grammar and writing quality.";

        // Create a submission model
        const submission = new CopyleaksWritingAssistantSubmissionModel(textToCheck);
        submission.sandbox = true;

        // Submit the text for analysis
        const response = await copyleaks.writingAssistantClient.submitTextAsync(loginResult, scanId, submission);
        console.log("Writing feedback results:", response);

    } catch (error) {
        console.error("An error occurred:", error);
    }
}

getWritingFeedback();

Java

import classes.Copyleaks;
import models.submissions.writingassistant.CopyleaksWritingAssistantSubmissionModel;
import models.submissions.writingassistant.ScoreWeights;
import models.response.writingassitant.WritingAssistantResponse;

public class WritingFeedbackExample {
    private static final String EMAIL_ADDRESS = "[email protected]";
    private static final String API_KEY = "00000000-0000-0000-0000-000000000000";

    public static void main(String[] args) {
        try {
            // Login to Copyleaks
            String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
            System.out.println("Logged successfully!\nToken: " + authToken);

            // Sample text to analyze for writing feedback
            String sampleText = "Copyleaks is a comprehensive plagiarism detection platform that performs " +
                "extensive searches across 60 trillion websites, 15,000+ academic journals, 20+ code data " +
                "repositories, and 1M+ internal documents. Using AI-powered text analysis, easily scan " +
                "documents, raw text, code, and URLs and instantly receive detailed reporting on the findings.";

            // Configure score weights for writing feedback
            ScoreWeights scoreWeights = new ScoreWeights();
            scoreWeights.setGrammarScoreWeight(0.25);
            scoreWeights.setMechanicsScoreWeight(0.25);
            scoreWeights.setSentenceStructureScoreWeight(0.25);
            scoreWeights.setWordChoiceScoreWeight(0.25);

            // Create writing assistant submission
            String scanId = "my-scan-123";
            CopyleaksWritingAssistantSubmissionModel writingSubmission =
                new CopyleaksWritingAssistantSubmissionModel(sampleText);
            writingSubmission.setScore(scoreWeights);
            writingSubmission.setSandbox(true);

            // Submit for writing feedback analysis
            WritingAssistantResponse result = Copyleaks.writingAssistantClient.submitText(
                authToken,
                scanId,
                writingSubmission
            );

            System.out.println("Writing feedback submitted successfully!");
            System.out.println("Overall Score: " + result.getScore().getOverallScore());
            System.out.println("Grammar Score: " + result.getScore().getCorrections().getGrammarCorrectionsScore());
            System.out.println("Mechanics Score: " + result.getScore().getCorrections().getMechanicsCorrectionsScore());
            System.out.println("Full result: " + result);

        } catch (Exception e) {
            System.out.println("Failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}