You have granular control over what content is scanned and what data is stored when you submit a document to Copyleaks. This guide covers two distinct types of exclusion:

1. Excluding Parts of a Document from Scan Analysis: This allows you to refine the plagiarism scan by ignoring specific elements like quotes or code blocks.
2. Preventing a Document from Being Indexed: This allows you to control whether the entire document is added to the Copyleaks Internal Database for future comparisons.

Exclude Options

The exclude object can contain the following boolean properties:

• quotes: If set to true, all text within quotation marks will be ignored.
• citations: If set to true, citations and references will be ignored.
• references: If set to true, the bibliography or reference list will be ignored.
• tableOfContents: If set to true, the table of contents will be ignored.
• titles: If set to true, titles and headings will be ignored.
• code: If set to true, code blocks will be ignored.
• documentTemplateIds: An array of unique identifiers for predefined templates stored in your Private Cloud Hub or the Shared Data Hub. These templates’ content is then excluded from the document and won’t count towards plagiarism or AI analysis.

Note

Use these options to customize your scans and focus on the most relevant content.

Using the Exclude

The exclude property is a powerful feature with two primary uses:

1. Active Scans: When submitting a document for scanning, you can include the exclude object in the request payload to specify which parts of the document should be ignored during analysis, e.g., you can exclude quotes, citations, or code blocks to focus on the most relevant content.

2. Exclude Template: The exclude template allows you to refine the analysis of documents by excluding specific sections based on a predefined template. The template document could be located in either your Private Cloud Hub or the Shared Data Hub, e.g., excluding exam questions from a student’s filled out exam.

Tip

Use documentTemplateIds to streamline your workflow when dealing with repetitive document structures. This ensures consistency and saves time during the scanning process.

🚀 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";
   const copyleaks = new Copyleaks();
   
   // Login function
   function loginToCopyleaks() {
     return copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY).then(
       (loginResult) => {
         console.log("Login successful!");
         console.log("Access Token:", loginResult.access_token);
         return loginResult;
       },
       (err) => {
         console.error('Login failed:', err);
         throw err;
       }
     );
   }
   
   loginToCopyleaks();

   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. Indexed Scan

   Use the following example to index a document as a template in your Private Cloud Hub.

   HTTP

   PUT https://api.copyleaks.com/v3/scans/submit/file/my-template-index
   Content-Type: application/json
   Authorization: Bearer YOUR_LOGIN_TOKEN
   
   {
     "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
     "filename": "student_solved_exam",
     "properties": {
       "indexing": {
         "action": 2,
         "repositories": ["my_private_cloud_exam_template"]
       },
       "sandbox": true
     }
   }

   cURL

   curl --request PUT \
     --url https://api.copyleaks.com/v3/scans/submit/file/my-template-index \
     --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
       "filename": "student_solved_exam",
       "properties": {
         "indexing": {
           "action": 2,
           "repositories": ["my_private_cloud_exam_template"]
         },
         "sandbox": true
       }
     }'

   Python

   import requests
   import base64
   
   # Document content
   document_content = "This is a test document."
   base64_content = base64.b64encode(document_content.encode()).decode('utf-8')
   
   url = "https://api.copyleaks.com/v3/scans/submit/file/my-template-index"
   payload = {
       "base64": base64_content,
       "filename": "student_solved_exam",
       "properties": {
           "indexing": {
               "action": 2,
               "repositories": ["my_private_cloud_exam_template"]
           },
           "sandbox": True
       }
   }
   headers = {
       "Authorization": "Bearer YOUR_LOGIN_TOKEN",
       "Content-Type": "application/json"
   }
   
   response = requests.put(url, json=payload, headers=headers)
   print(response.json())

   JavaScript

   const { Copyleaks } = require('plagiarism-checker');
   
   const EMAIL_ADDRESS = "[email protected]";
   const API_KEY = "your-api-key-here";
   
   async function indexTemplate() {
       const copyleaks = new Copyleaks();
       const authToken = await copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY);
   
       const documentContent = "This is a test document.";
       const base64Content = Buffer.from(documentContent).toString('base64');
   
       const scanId = "my-template-index";
       const fileSubmission = {
           base64: base64Content,
           filename: "student_solved_exam",
           properties: {
               indexing: {
                   action: 2,
                   repositories: ["my_private_cloud_exam_template"]
               },
               sandbox: true
           }
       };
   
       try {
           const result = await copyleaks.submitFileAsync(authToken, scanId, fileSubmission);
           console.log('Template indexed successfully!', result);
       } catch (error) {
           console.error('Failed to index template:', error);
       }
   }
   
   indexTemplate();

   Java

   import classes.Copyleaks;
   import models.submissions.CopyleaksFileSubmissionModel;
   import models.submissions.properties.*;
   import java.util.Base64;
   import java.nio.charset.StandardCharsets;
   
   public class IndexTemplateExample {
       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 {
               String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
   
               String documentContent = "This is a test document.";
               String base64Content = Base64.getEncoder().encodeToString(
                   documentContent.getBytes(StandardCharsets.UTF_8)
               );
   
               SubmissionProperties properties = new SubmissionProperties();
               properties.setSandbox(true);
               properties.setIndexing(new SubmissionIndexing(2, new String[]{"my_private_cloud_exam_template"}));
   
               CopyleaksFileSubmissionModel fileSubmission = new CopyleaksFileSubmissionModel(
                   base64Content,
                   "student_solved_exam",
                   properties
               );
   
               Copyleaks.submitFile(authToken, "my-template-index", fileSubmission);
               System.out.println("Template indexed successfully!");
           } catch (Exception e) {
               System.out.println("Failed: " + e.getMessage());
               e.printStackTrace();
           }
       }
   }

5. Submit for Scanning

   Include the exclude object in the request payload to specify which parts of the document should be ignored during analysis.

   HTTP

   PUT https://api.copyleaks.com/v3/scans/submit/file/my-scan-with-template
   Content-Type: application/json
   Authorization: Bearer YOUR_LOGIN_TOKEN
   
   {
     "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
     "filename": "document-to-scan.txt",
     "properties": {
       "exclude": {
         "documentTemplateIds": ["my-template-index"],
         "quotes": true,
         "citations": true,
         "references": true,
         "tableOfContents": true,
         "titles": true,
         "htmlTemplate": true,
         "code": {
           "comments": true
         }
       },
       "sandbox": true
     }
   }

   cURL

   curl --request PUT \
     --url https://api.copyleaks.com/v3/scans/submit/file/my-scan-with-template \
     --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
       "filename": "document-to-scan.txt",
       "properties": {
         "exclude": {
           "documentTemplateIds": ["my-template-index"],
           "quotes": true,
           "citations": true,
           "references": true,
           "tableOfContents": true,
           "titles": true,
           "htmlTemplate": true,
           "code": {
             "comments": true
           }
         },
         "sandbox": true
       }
     }'

   Python

   import requests
   import base64
   
   # Document content
   document_content = "This is a test document."
   base64_content = base64.b64encode(document_content.encode()).decode('utf-8')
   
   url = "https://api.copyleaks.com/v3/scans/submit/file/my-scan-with-template"
   payload = {
       "base64": base64_content,
       "filename": "document-to-scan.txt",
       "properties": {
           "exclude": {
               "documentTemplateIds": ["my-template-index"],
               "quotes": true,
               "citations": true,
               "references": true,
               "tableOfContents": true,
               "titles": true,
               "htmlTemplate": true,
               "code": {
                 "comments": true
               }
           },
           "sandbox": True
       }
   }
   headers = {
       "Authorization": "Bearer YOUR_LOGIN_TOKEN",
       "Content-Type": "application/json"
   }
   
   response = requests.put(url, json=payload, headers=headers)
   print(response.json())

   JavaScript

   const { Copyleaks } = require('plagiarism-checker');
   
   const EMAIL_ADDRESS = "[email protected]";
   const API_KEY = "your-api-key-here";
   
   async function submitScanWithTemplate() {
       const copyleaks = new Copyleaks();
       const authToken = await copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY);
   
       const documentContent = "This is a test document.";
       const base64Content = Buffer.from(documentContent).toString('base64');
   
       const scanId = "my-scan-with-template";
       const fileSubmission = {
           base64: base64Content,
           filename: "document-to-scan.txt",
           properties: {
               exclude: {
                   documentTemplateIds: ["my-template-index"],
                   quotes: true,
                   citations: true,
                   references: true,
                   tableOfContents: true,
                   titles: true,
                   htmlTemplate: true,
                   code: {
                     comments: true
                   }
               },
               sandbox: true
           }
       };
   
       try {
           const result = await copyleaks.submitFileAsync(authToken, scanId, fileSubmission);
           console.log('Scan submitted successfully!', result);
       } catch (error) {
           console.error('Failed to submit scan:', error);
       }
   }
   
   submitScanWithTemplate();

   Java

   import classes.Copyleaks;
   import models.submissions.CopyleaksFileSubmissionModel;
   import models.submissions.properties.*;
   import java.util.Base64;
   import java.nio.charset.StandardCharsets;
   
   public class SubmitScanWithTemplate {
       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 {
               String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
   
               String documentContent = "This is a test document.";
               String base64Content = Base64.getEncoder().encodeToString(
                   documentContent.getBytes(StandardCharsets.UTF_8)
               );
   
               SubmissionProperties properties = new SubmissionProperties();
               properties.setSandbox(true);
               properties.setExclude(new SubmissionExclude(new String[]{"my-template-index"}));
   
               CopyleaksFileSubmissionModel fileSubmission = new CopyleaksFileSubmissionModel(
                   base64Content,
                   "document-to-scan.txt",
                   properties
               );
   
               Copyleaks.submitFile(authToken, "my-scan-with-template", fileSubmission);
               System.out.println("Scan submitted successfully!");
           } catch (Exception e) {
               System.out.println("Failed: " + e.getMessage());
               e.printStackTrace();
           }
       }
   }

Response Example

When the scan is processed, the scannedDocument object in the response will reflect the number of words that were excluded.

201

201 Created

The scan was successfully created and is now processing. The excluded word count is reflected in the response.

Example Response

A typical response from this endpoint:

Show full example (39 lines)

{
  "scannedDocument": {
    "scanId": "my-scan-exclude-example",
    "totalWords": 8,
    "totalExcluded": 4,
    "credits": 0,
    "expectedCredits": 1,
    "creationTime": "2025-08-10T10:00:00.000000Z",
    "metadata": {
      "filename": "document-with-exclusions.txt"
    },
    "enabled": {
      "plagiarismDetection": true,
      "aiDetection": false,
      "explainableAi": false,
      "writingFeedback": false,
      "pdfReport": true,
      "cheatDetection": false,
      "aiSourceMatch": false
    },
    "detectedLanguage": "en"
  },
  "results": {
    "score": {
      "identicalWords": 0,
      "minorChangedWords": 0,
      "relatedMeaningWords": 0,
      "aggregatedScore": 0
    },
    "internet": [],
    "database": [],
    "batch": [],
    "repositories": []
  },
  "notifications": {},
  "writingFeedback": {},
  "status": 0,
  "developerPayload": ""
}

{
  "scannedDocument": {
    "scanId": "my-scan-exclude-example",
    "totalWords": 8,
    "totalExcluded": 4,
    "credits": 0,
    "expectedCredits": 1,
    "creationTime": "2025-08-10T10:00:00.000000Z",
    "metadata": {
      "filename": "document-with-exclusions.txt"
    },
    "enabled": {
      "plagiarismDetection": true,
      "aiDetection": false,
      "explainableAi": false,
// ... truncated

🗺️ Next Steps

Webhooks Overview Learn how to securely receive and process notifications from Copyleaks.

Viewing Scan Results Understand the scan result format and how to display it to your users.