Copyleaks’ Data Hubs provide a powerful way to compare multiple documents against each other, allowing you to detect similarities and prevent plagiarism within a large batch of content.

This is particularly useful for educators who want to check if students have shared work or submitted identical content across a batch of assignments, or companies with large amounts of documents in order to find duplication.

How It Works

Copyleaks provides two types of databases for storing and comparing documents:

• Shared Data Hub: Global database that contains millions of documents from institutions worldwide.
• Private Cloud Hub: Private database that is exclusive to your organization, ensuring that your documents remain confidential and secure.

You can contribute documents to those databases and compare your documents against them.

Note

You can use both databases simultaneously to maximize detection coverage while keeping sensitive documents private.

Understanding Your Database Options

You have two database options for storing and comparing your documents:

Shared Data Hub (Free)

• Contains millions of documents from institutions worldwide
• When you index a document, it becomes available for everyone to compare against
• Contributes to the global academic integrity community
• Your documents will be matched against submissions from other institutions

Private Cloud Hub (Paid)

• Creates a completely private database for your organization only
• Your documents stay within your private environment
• Perfect for sensitive or confidential documents
• Only you and your organization can access and compare against these documents
• Built for large organizations looking to securely store and manage documents
• Enables team collaboration with controlled access and user management

Note

You can use both databases simultaneously. Your documents can be stored in your Private Cloud Hub while also being compared against the Shared Data Hub for maximum detection coverage.

How Cross-Comparison Works

The process involves two main steps:

1. 📥 Index your documents: Upload documents to your chosen database using IndexOnly mode.
2. 🚀 Start the comparison: Run a scan that compares all indexed documents against each other and your selected databases.

This two-step approach ensures all documents are properly stored before the comparison begins.

🚀 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. Index Your Documents

   For each document you want to include in the comparison, submit it for indexing using one of the submit endpoints (submit-file, submit-url, or submit-ocr).

   Set properties.action to 2 (IndexOnly) to store the document without scanning it immediately. This avoids consuming scan credits during the indexing phase. You also need to specify which repository to index the document into.

   Caution

   Important: Any other scanning options (like internet or aiDetection) must be configured during this indexing step. They cannot be changed later when you start the comparison scan.

   HTTP

   PUT https://api.copyleaks.com/v3/scans/submit/file/my-index-scan-1
   Content-Type: application/json
   Authorization: Bearer <YOUR_AUTH_TOKEN>
   
   {
     "base64": "SGVsbG8gd29ybGQh",
     "filename": "document1.txt",
     "properties": {
       "action": 2,
       "indexing": {
         "repositories": ["my-repo-id"]
       },
       "sandbox": true
     }
   }

   cURL

   curl --request PUT \
        --url https://api.copyleaks.com/v3/scans/submit/file/my-index-scan-1 \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "base64": "SGVsbG8gd29ybGQh",
              "filename": "document1.txt",
              "properties": {
                "action": 2,
                "indexing": {
                  "repositories": ["my-repo-id"]
                },
                "sandbox": true
              }
            }'

   Python

   from copyleaks.copyleaks import Copyleaks
   from copyleaks.models.submit.document import FileDocument
   from copyleaks.models.submit.properties.scan_properties import ScanProperties
   from copyleaks.models.submit.properties.indexing_properties import IndexingProperties
   
   scan_id = "my-index-scan-1"
   
   properties = ScanProperties()
   properties.set_action(2) # IndexOnly
   properties.set_sandbox(True)
   
   indexing = IndexingProperties()
   indexing.add_repository("my-repo-id")
   properties.set_indexing(indexing)
   
   file_submission = FileDocument(base64="SGVsbG8gd29ybGQh", filename="document1.txt", properties=properties)
   
   response = Copyleaks.Scans.submit_file(auth_token, scan_id, file_submission)
   print(response)

   You will need to wait for the IndexOnly webhook for each document to confirm it has been successfully indexed before proceeding to the next step.

5. Start Your Cross-Comparison

   Once all your documents are indexed, make a PATCH request to the /v3/scans/start endpoint. This will begin the comparison scan for all the documents you indexed.

   Provide the list of scanIds from the previous step in the trigger array.

   HTTP

   PATCH https://api.copyleaks.com/v3/scans/start
   Content-Type: application/json
   Authorization: Bearer <YOUR_AUTH_TOKEN>
   
   {
     "trigger": [
       "my-index-scan-1",
       "my-index-scan-2",
       "my-index-scan-3"
     ],
     "errorHandling": 0
   }

   cURL

   curl --request PATCH \
        --url https://api.copyleaks.com/v3/scans/start \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "trigger": [
                "my-index-scan-1",
                "my-index-scan-2",
                "my-index-scan-3"
              ],
              "errorHandling": 0
            }'

6. Interpreting The Results

   A successful 200 OK response from the start endpoint will confirm which scans were started. The actual scan results for each document will be delivered asynchronously via the Completed webhook, just like a regular scan.

   Example Success Response from /v3/scans/start:

   {
     "success": [
       "my-index-scan-1",
       "my-index-scan-2",
       "my-index-scan-3"
     ],
     "failed": []
   }

7. 🎉Congratulations!

   You have successfully started a cross-comparison scan between multiple documents in your Data Hub.

👥 Team Collaboration with Private Cloud Hub

Multiple users can access, scan against, and index to your Private Cloud Hub. Manage permissions and data masking settings through the admin dashboard.

💡 Best Practices

• Plan your scanning options: Configure settings during indexing.
• Monitor indexing progress: Wait for all IndexOnly webhooks before starting the comparison.
• Choose your database strategy: Decide whether to use Private, Shared, or both.
• Batch efficiently: Group related documents together.
• Respect API limits: Monitor your API dashboard.

🚀 Next Steps

Create Private Cloud Hub Set up your own private database for document storage.

Support

Should you require any assistance, please contact Copyleaks Support or ask a question on StackOverflow with the copyleaks-api tag.

Schedule a Live Demo

Want to see how Data Hubs can help you manage and compare your documents? Our technical team can walk you through live examples of setting up a Private Cloud Hub, indexing large batches of content, and running cross-comparisons in a secure environment.

Book a Demo