Get started with Copyleaks’ Writing Assistant API to detect and correct over 30 types of writing issues across grammar, mechanics, sentence structure, and word choice.

The API is available in two ways:

1. Sync: Submit text via an HTTP request and receive the analysis in the response.
2. Async: Use the Authenticity API to submit larger documents and receive results via webhook.

Note

This guide focuses on the synchronous option. For asynchronous submissions, see the Authenticity API Guide.

🚀 Get Started

1. Before you begin

   Before you start, ensure you have the following:

   • An active Copyleaks account. If you don’t have one, sign up for free.
   • You can find your API key on the API Dashboard.

2. Installation

   Choose your preferred method for making API calls.

   HTTP

   You can interact with the API using any standard HTTP client.

   For a quicker setup, we provide a Postman collection. See our Postman guide for instructions.

   cURL
   Ubuntu/Debian

   sudo apt-get install curl

   Windows

   Download it from curl.se.

   macOS

   brew install curl

   Python

   pip install copyleaks

   JavaScript

   npm install plagiarism-checker

   Java

   Download from Maven

3. Login

   To perform a scan, we first need to generate an access token. For that, we will use the login endpoint. The API key can be found on the Copyleaks API Dashboard.

   Upon successful authentication, you will receive a token that must be attached to subsequent API calls via the Authorization: Bearer <TOKEN> header. This token remains valid for 48 hours.

   HTTP

   POST https://id.copyleaks.com/v3/account/login/api
   
   Headers
   Content-Type: application/json
   
   Body
   {
       "email": "[email protected]",
       "key": "00000000-0000-0000-0000-000000000000"
   }

   cURL

   export COPYLEAKS_EMAIL="[email protected]"
   export COPYLEAKS_API_KEY="your-api-key-here"
   
   curl --request POST \
     --url https://id.copyleaks.com/v3/account/login/api \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data "{
       \"email\": \"${COPYLEAKS_EMAIL}\",
       \"key\": \"${COPYLEAKS_API_KEY}\"
     }"

   Python

   from copyleaks.copyleaks import Copyleaks
   
   EMAIL_ADDRESS = "[email protected]"
   API_KEY = "your-api-key-here"
   
   # Login to Copyleaks
   auth_token = Copyleaks.login(EMAIL_ADDRESS, API_KEY)
   print("Logged successfully!\nToken:", auth_token)

   JavaScript

   const { Copyleaks } = require('plagiarism-checker');
   
   const EMAIL_ADDRESS = "[email protected]";
   const API_KEY = "your-api-key-here";
   
   
   async function login() {
       const copyleaks = new Copyleaks();
       const loginResult = await copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY);
       console.log('Logged successfully!\nToken:', loginResult);
       return loginResult;
   }

   Java

   import com.copyleaks.sdk.api.Copyleaks;
   
   String EMAIL_ADDRESS = "[email protected]";
   String API_KEY = "00000000-0000-0000-0000-000000000000";
   
   // Login to Copyleaks
   try {
       String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
       System.out.println("Logged successfully!\nToken: " + authToken);
   } catch (CommandException e) {
       System.out.println("Failed to login: " + e.getMessage());
       System.exit(1);
   }

   Response

   {
       "access_token": "<ACCESS_TOKEN>",
       ".issued": "2025-07-31T10:19:40.0690015Z",
       ".expires": "2025-08-02T10:19:40.0690016Z"
   }

   Note

   Save this token! It’s valid for 48 hours and can be reused for subsequent API calls.

4. Send Request

   Use the Writing Feedback Endpoint. Provide a unique scanId for each request.

   Tip

   For testing, set "sandbox": true in the request body. Sandbox mode is free and returns mock results.

   HTTP

   POST https://api.copyleaks.com/v1/writing-feedback/my-scan-1/check
   
   Headers
   Authorization: Bearer <YOUR_AUTH_TOKEN>
   Content-Type: application/json
   
   Body
   {
     "text": "Copyleaks is a online plagarism detector that helps schools, business and content creators to make sure thier work is orginal. It scans textes from internet and databasis to find similerities. The tool is fast, accurate and supports multipal languages. However, some times it gives false possitives, so users should double check results. Overall, its a usefull platform for mantaining content integrity.",
     "sandbox": true
   }

   cURL

   curl -X POST "https://api.copyleaks.com/v1/writing-feedback/my-scan-1/check" \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "text": "Copyleaks is a online plagarism detector that helps schools, business and content creators to make sure thier work is orginal. It scans textes from internet and databasis to find similerities. The tool is fast, accurate and supports multipal languages. However, some times it gives false possitives, so users should double check results. Overall, its a usefull platform for mantaining content integrity.",
              "sandbox": true
            }'

   Python

   from copyleaks.copyleaks import Copyleaks
   from copyleaks.models.submit.writing_assistant_document import WritingAssistantDocument
   
   scan_id = "my-python-scan"
   sample_text = "Hello world, this is a test."
   
   submission = WritingAssistantDocument(sample_text)
   submission.set_sandbox(True)
   
   response = Copyleaks.WritingAssistantClient.submit_text(auth_token, scan_id, submission)
   print(response)

   JavaScript

   const { CopyleaksWritingAssistantSubmissionModel } = require('plagiarism-checker');
   
   const scanId = 'my-nodejs-scan';
   const sampleText = "Hello world, this is a test.";
   
   const submission = new CopyleaksWritingAssistantSubmissionModel(sampleText);
   submission.sandbox = true;
   
   const response = await copyleaks.writingAssistantClient.submitTextAsync(authToken, scanId, submission);
   console.log(response);

   Java

   import classes.Copyleaks;
   import models.submissions.CopyleaksWritingAssistantSubmissionModel;
   import models.responses.WritingAssistantResponse;
   
   String scanId = "my-java-scan";
   String sampleText = "Hello world, this is a test.";
   
   CopyleaksWritingAssistantSubmissionModel submission = new CopyleaksWritingAssistantSubmissionModel(sampleText);
   submission.setSandbox(true);
   
   WritingAssistantResponse response = Copyleaks.writingAssistantClient.submitText(authToken, scanId, submission);
   System.out.println(response);

5. Interpret The Response

   The Writing Assistant Response contains detailed feedback under the corrections and score properties. The score provides an overall quality metric and a breakdown by category, while corrections pinpoints the exact location and suggested changes for each issue.

   Example Response Snippet

   {
     "score": {
       "corrections": {
         "overallScore": 93,
         "grammarCorrectionsScore": 100
       },
       "readability": {
         "readabilityLevelText": "College Student"
       }
     },
     "corrections": {
       "text": {
         "chars": { "types": [18], "starts": [28], "lengths": [9], "operationTexts": ["stretches "] }
       }
     }
   }

🗺️ Next Steps

Full API Reference Explore the complete documentation for the Writing Assistant response object.

Correction Types See a detailed list of all supported correction types and languages.