The Copyleaks API is the most powerful way to analyze your content for plagiarism. This API is asynchronous - you submit a scan, and Copyleaks notifies your server via webhooks when the results are ready to be retrieved.

This guide will walk you through the process of submitting a scan, enabling plagiarism detection, and exporting the results.

🚀 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. Submit for Scanning

   Use the Submit File Endpoint to send content for analysis. You need to provide a unique scanId for each submission.

   Tip

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

   HTTP

   PUT https://api.copyleaks.com/v3/scans/submit/file/my-plagiarism-scan
   
   Headers
   Authorization: Bearer <YOUR_AUTH_TOKEN>
   Content-Type: application/json
   
   Body
   {
       "base64": "SGVsbG8gd29ybGQh",
       "filename": "file.txt",
       "properties": {
           "webhooks": {
             "status": "https://your-server.com/webhook/{STATUS}"
             },
           "sandbox": true
       }
   }

   cURL

   curl -X PUT "https://api.copyleaks.com/v3/scans/submit/file/my-plagiarism-scan" \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "base64": "SGVsbG8gd29ybGQh",
              "filename": "file.txt",
              "properties": {
                "webhooks": {
                  "status": "https://your-server.com/webhook/{STATUS}"
                },
                "sandbox": true,
                 "scanning": {
                   "internet": true,
                 },
                "cheatDetection": false,
              }
            }'

   Python

   import base64
   from copyleaks.copyleaks import Copyleaks
   from copyleaks.models.submit.document import FileDocument
   from copyleaks.models.submit.properties.scan_properties import ScanProperties
   
   scan_id = "my-plagiarism-scan"
   base64_content = base64.b64encode(b'Hello world.').decode('utf8')
   
   scan_properties = ScanProperties("https://your-server.com/webhook/{STATUS}")
   scan_properties.set_sandbox(True)
   scan_properties.set_plagiarism_scan(True) # Enable Plagiarism scan
   
   file_submission = FileDocument(base64_content, "file.txt")
   file_submission.set_properties(scan_properties)
   
   Copyleaks.submit_file(auth_token, scan_id, file_submission)
   print("Sent to scanning...")

   Node.js

   const { Copyleaks, CopyleaksFileSubmissionModel } = require('plagiarism-checker');
   
   const scanId = "my-plagiarism-scan";
   const base64Content = Buffer.from('Hello world').toString('base64');
   
   const submission = new CopyleaksFileSubmissionModel(
     base64Content,
     'file.txt',
     {
       webhooks: { status: 'https://your-server.com/webhook/{STATUS}' },
       sandbox: true,
       plagiarism: { scan: true } // Enable Plagiarism scan
     }
   );
   
   await copyleaks.submitFileAsync(authToken, scanId, submission);
   console.log('Sent to scanning...');

   Java

   import classes.Copyleaks;
   import models.submissions.CopyleaksFileSubmissionModel;
   import models.submissions.properties.*;
   import java.util.Base64;
   import java.nio.charset.StandardCharsets;
   
   String scanId = "my-plagiarism-scan";
   String base64Content = Base64.getEncoder().encodeToString("Hello world".getBytes(StandardCharsets.UTF_8));
   
   SubmissionWebhooks webhooks = new SubmissionWebhooks("https://your-server.com/webhook/{STATUS}");
   
   SubmissionProperties properties = new SubmissionProperties(webhooks);
   properties.setSandbox(true);
   properties.setPlagiarism(new SubmissionPlagiarism(true)); // Enable Plagiarism scan
   
   CopyleaksFileSubmissionModel submission = new CopyleaksFileSubmissionModel(base64Content, "file.txt", properties);
   
   Copyleaks.submitFile(authToken, scanId, submission);
   System.out.println("Sent to scanning...");

5. Wait for Completion Webhook

   The scan can take some time. Once it’s complete, Copyleaks will send a completed webhook to the status URL you provided. This webhook contains a summary of the scan results, including any result IDs for found plagiarism matches.

6. Export Detailed Results

   After the completed webhook arrives, use the export endpoint to retrieve the detailed plagiarism results using the result IDs you received in the completion webhook.

   We will also export the Crawled Version. The crawledVersion webhook contains the text and html version of the document. This can later be used in order to display the report.

   In addition, you should also specify a completionWebhook to receive notifications when the export is ready.

   HTTP

   POST https://api.copyleaks.com/v3/downloads/my-plagiarism-scan/export/<export_id>
   
   Headers
   Authorization: Bearer <your_token>
   Content-Type: application/json
   
   Body
   {
       "completionWebhook": {
           "url": "https://your.server/webhook/export/completed",
           "headers": {
               "key": "value",
               "key2": "value2"
           },
           "maxRetries": 3
       },
       "developerPayload": "custom_data_identifier",
       "crawledVersion": {
           "endpoint": "https://your.server/webhook/export/crawled",
           "verb": "POST",
           "headers": {
               "key": "value",
               "key2": "value2"
           }
       },
       "results": [
           {
               "id": "result-1",
               "endpoint": "https://your.server/webhook/export/result/result-1",
               "verb": "POST",
               "headers": {
                   "key": "value",
                   "key2": "value2"
               }
           }
       ]
   }

   cURL

   curl -X POST "https://api.copyleaks.com/v3/downloads/my-plagiarism-scan/export/my-export-1" \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "completionWebhook": "https://your-server.com/webhook/export/completion",
               "developerPayload": "custom_data_identifier",
               "crawledVersion": {
                   "endpoint": "https://your.server/webhook/export/crawled",
                   "verb": "POST",
                   "headers": {
                       "key": "value",
                       "key2": "value2"
                   }
               },
              "results": [
                {
                  "id": "<RESULT_ID_FROM_COMPLETED_WEBHOOK>",
                  "endpoint": "https://your-server.com/webhook/export/result/1",
                  "verb": "POST"
                }
              ]
            }'

   Python

   from copyleaks.copyleaks import Copyleaks
   from copyleaks.models.export import Export, ExportResult
   
   scan_id = "my-plagiarism-scan"
   export_id = "my-export-1"
   export = Export()
   export.set_completion_webhook('https://your-server.com/webhook/export/completion')
   
   # Export a specific plagiarism result
   result1 = ExportResult()
   result1.set_id('<RESULT_ID_FROM_COMPLETED_WEBHOOK>')
   result1.set_endpoint('https://your-server.com/webhook/export/result/1', 'POST')
   export.set_results([result1])
   
   Copyleaks.export(auth_token, scan_id, export_id, export)
   print("Export initiated.")

   Node.js

   const { Export, ExportResult } = require('plagiarism-checker');
   
   const scanId = 'my-plagiarism-scan';
   const exportId = 'my-export-1';
   
   const exportRequest = new Export();
   exportRequest.setCompletionWebhook('https://your-server.com/webhook/export/{STATUS}');
   
   // Export a specific plagiarism result
   const result1 = new ExportResult();
   result1.setId('<RESULT_ID_FROM_COMPLETED_WEBHOOK>');
   result1.setEndpoint('https://your-server.com/webhook/export/result/1', 'POST');
   exportRequest.setResults([result1]);
   
   await copyleaks.exportAsync(authToken, scanId, exportId, exportRequest);
   console.log('Export initiated.');

   Java

   import classes.Copyleaks;
   import models.exports.Export;
   import models.exports.ExportResult;
   import java.util.Arrays;
   
   String scanId = "my-plagiarism-scan";
   String exportId = "my-export-1";
   
   Export exportRequest = new Export();
   exportRequest.setCompletionWebhook("https://your-server.com/webhook/export/{STATUS}");
   
   // Export a specific plagiarism result
   ExportResult result1 = new ExportResult();
   result1.setId("<RESULT_ID_FROM_COMPLETED_WEBHOOK>");
   result1.setEndpoint("https://your-server.com/webhook/export/result/1", "POST");
   exportRequest.setResults(Arrays.asList(result1));
   
   Copyleaks.export(authToken, scanId, exportId, exportRequest);
   System.out.println("Export initiated.");

7. 🎉Congratulations!

   You have successfully submitted a scan for plagiarism detection and exported the results. You can now handle the results in your application, display them to users, or take further actions based on the findings.

🗺️ 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.