Detect AI-Generated Content in Documents

Q: How do I enable AI detection on a scan?

Set "aiGeneratedText": { "detect": true } inside the submission properties . Without it, the scan runs without AI-generated text analysis.

Q: Can I test AI detection without using credits?

Yes. Set "sandbox": true in the submission properties. Sandbox mode is free and returns mock results, so you can wire up the flow before going live.

Q: How do I know whether AI-generated content was found?

When the scan completes, check the notifications.alerts array in the webhook payload. An alert with the code suspected-ai-text indicates AI-generated content was detected; its additionalData field holds the detailed summary.

Q: How do I get the detailed AI detection breakdown?

After the completed webhook, call the export endpoint with the AI detection result ID to retrieve the AI Detection Result and the Crawled Version of the document.

The Copyleaks Authenticity API is a powerful way to analyze your content for AI-generated text. It allows you to scan documents like PDF, DOCX, TXT, and other formats to detect whether content was written by humans or generated by AI. This guide will walk you through the process of submitting a document, enabling AI content detection, and exporting the results.

Get started

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.

Installation

Choose your preferred method for making API calls.

# macOS
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Windows - download from https://curl.se

pip install copyleaks

npm install plagiarism-checker

Install-Package Copyleaks

composer require copyleaks/php-plagiarism-checker

gem install plagiarism-checker

<!-- Add to your pom.xml (requires Java 11+) -->
<dependency>
    <groupId>com.copyleaks.sdk</groupId>
    <artifactId>copyleaks-java-sdk</artifactId>
    <version>5.1.0</version>
</dependency>

HTTP needs no installation - call the API with any standard HTTP client, or import our Postman collection for a quicker start.

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.

POST https://id.copyleaks.com/v3/account/login/api

Headers
Content-Type: application/json

Body
{
    "email": "[email protected]",
    "key": "00000000-0000-0000-0000-000000000000"
}

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}\"
  }"

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)

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();

import classes.Copyleaks;
import models.response.CopyleaksAuthToken;

String EMAIL_ADDRESS = "[email protected]";
String API_KEY = "00000000-0000-0000-0000-000000000000";

// Login to Copyleaks
try {
    CopyleaksAuthToken authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
    System.out.println("Logged in successfully!");
} catch (Exception 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"
}

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

Submit for scanning

File Upload

Submit documents including PDF, DOCX, TXT, and other formats for scanning.

URL Scanning

Submit webpages and online documents directly by providing their URL.

Text from Images

Extract and scan text from images, including screenshots and photos.

For this guide, we’ll demonstrate document submission. Each submission requires a unique scanId for proper tracking and identification.

Filename: The file extension in the filename parameter must match your document type (e.g., .pdf, .docx, .txt). See the full list of supported ai text detection file types.
Content Encoding: The file content must be Base64 encoded and sent in the base64 property.

What is Base64 Encoding?Base64 converts binary files into text strings so they can be sent via JSON. All programming languages have built-in Base64 encoding functions, see the code examples below for your language.

For testing, set "sandbox": true. Sandbox mode is free and returns mock results.
To enable AI detection, ensure "aiGeneratedText": {"detect": true} is set in your properties.

PUT https://api.copyleaks.com/v3/scans/submit/file/my-ai-detection-scan

Headers
Authorization: Bearer <YOUR_AUTH_TOKEN>
Content-Type: application/json

Body
{
    "base64": "<BASE64_ENCODED_PDF_CONTENT>",
    "filename": "my-file.pdf",
    "properties": {
        "webhooks": {
          "status": "https://your-server.com/webhook/{STATUS}"
          },
        "sandbox": true,
        "aiGeneratedText": {
            "detect": true
        }
    }
}

# First, encode your PDF file to base64
base64_content=$(base64 -w 0 my-file.pdf)

curl -X PUT "https://api.copyleaks.com/v3/scans/submit/file/my-ai-detection-scan" \
     -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
     -H "Content-Type: application/json" \
     -d "{
           \"base64\": \"$base64_content\",
           \"filename\": \"my-file.pdf\",
           \"properties\": {
             \"webhooks\": {
               \"status\": \"https://your-server.com/webhook/{STATUS}\"
             },
             \"sandbox\": true,
             \"aiGeneratedText\": {
               \"detect\": true
             },
             \"scanning\": {
               \"internet\": false
             }
           }
         }"

import base64
import random
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.submit_webhooks import SubmitWebhooks
from copyleaks.models.submit.properties.ai_generated_text import AIGeneratedText

print("Submitting a PDF file for AI detection...")

# Read and encode the PDF file
with open('my-file.pdf', 'rb') as pdf_file:
    pdf_content = pdf_file.read()
    BASE64_FILE_CONTENT = base64.b64encode(pdf_content).decode('utf8')

FILENAME = "my-file.pdf"  # Important: extension must match file type
scan_id = random.randint(100, 100000)  # generate a random scan id
file_submission = FileDocument(BASE64_FILE_CONTENT, FILENAME)

# Configure AI-generated text detection
ai_generated_text = AIGeneratedText()
ai_generated_text.detect = True  # Enable AI detection

# Configure webhooks for notifications
webhooks = SubmitWebhooks()
webhooks.set_status('https://your.server/webhook/{STATUS}')
webhooks.set_new_result('https://your.server/webhook/new-results')

# Pass the webhooks and AI detection settings to ScanProperties
scan_properties = ScanProperties(status_webhook='https://your.server/webhook/{STATUS}')
scan_properties.set_webhooks(webhooks)
scan_properties.set_ai_generated_text(ai_generated_text)
scan_properties.set_sandbox(True)  # Turn on sandbox mode. Turn off on production.
file_submission.set_properties(scan_properties)

Copyleaks.submit_file(auth_token, scan_id, file_submission)
print("PDF sent to scanning")
print("You will be notified via webhook when the scan completes.")

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

async function submitFileForAiDetection() {
    try {
        // Initialize Copyleaks
        const copyleaks = new Copyleaks();
        
        // Login to get the authentication token.
        // Replace with your email and API key.
        const loginResult = await copyleaks.loginAsync('[email protected]', 'YOUR_API_KEY');

        const scanId = `ai-scan-${Date.now()}`;
        const WEBHOOK_URL = "https://your-server.com/webhook";

        // Read a file and convert it to base64
        const filePath = 'path/to/your/document.pdf';
        const fileContent = fs.readFileSync(filePath);
        const base64Content = fileContent.toString('base64');

        // Create a submission model
        const submission = new CopyleaksFileSubmissionModel(
            base64Content,
            'document.pdf',
            {
                sandbox: true, // Use sandbox for testing
                webhooks: {
                    // Copyleaks will notify this URL when the scan is complete.
                    status: `${WEBHOOK_URL}/{STATUS}`
                },
                aiGeneratedText: {
                    detect: true // Enable AI detection
                }
            }
        );

        // Submit the file for scanning
        await copyleaks.submitFileAsync(loginResult, scanId, submission);
        console.log(`Submission successful. Scan ID: ${scanId}`);

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

submitFileForAiDetection();

import classes.Copyleaks;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.io.IOException;

String scanId = "my-ai-detection-scan";

// Read and encode the PDF file
byte[] pdfBytes = Files.readAllBytes(Paths.get("my-file.pdf"));
String base64Content = Base64.getEncoder().encodeToString(pdfBytes);

// Configure webhooks
SubmissionWebhooks webhooks = new SubmissionWebhooks("https://your-server.com/webhook/{STATUS}");
webhooks.setNewResult("https://your-server.com/webhook/new-results");

// Create submission properties
SubmissionProperties properties = new SubmissionProperties(webhooks);
properties.setSandbox(true);

// Configure AI-generated text detection
SubmissionAIGeneratedText aiGeneratedText = new SubmissionAIGeneratedText();
aiGeneratedText.setDetect(true);
properties.setAiGeneratedText(aiGeneratedText);

// Set action to scan for AI content
properties.setAction(SubmissionActions.Scan);

// Create and submit the file - Important: extension must match file type
CopyleaksFileSubmissionModel submission = new CopyleaksFileSubmissionModel(
    base64Content, 
    "my-file.pdf", 
    properties
);

Copyleaks.submitFile(authToken, scanId, submission);
System.out.println("PDF sent to scanning...");

Wait for the completion webhook

The scan times differ depending on document length. Once it’s complete, Copyleaks will send a completed webhook to the status URL you provided.

For complete details on the webhook response structure, see the Scan Completed Webhook Reference.

Interpreting AI detection results

When the scan is complete, check the notifications.alerts array in the webhook payload.

If the array is empty or does not contain an alert with the code suspected-ai-text, you can assume no AI-generated content was detected.
If such an alert is present, you can inspect its additionalData field for a detailed summary of the AI Detector results.

Export detailed results

Once the scan is complete, you’ll receive a completed webhook. To get the full analysis needed to display a report, you need to export two key pieces of data using the export endpoint:

AI Detection Results: It provides a detailed breakdown of which parts of the text were identified as potentially AI-generated. You’ll receive a result ID for the AI detection in the completed webhook, which you’ll use for the export. See the AI Detection Result data type.
Crawled Version: This is the plain text or HTML representation of the original scanned document. See the Crawled Version data type.

Your export request must specify a completionWebhook to be notified when the exported data is ready for download.

POST https://api.copyleaks.com/v3/downloads/my-ai-detection-scan/export/<export_id>

Headers
Authorization: Bearer <your_token>
Content-Type: application/json

Body
{
    "completionWebhook":  "https://your.server/export/completed",
    "maxRetries": 3,
    "developerPayload": "custom_data_identifier",
    "crawledVersion": {
        "endpoint": "https://your.server/webhook/export/crawled",
        "verb": "POST",
        "headers": [
            [
                "header-key",
                "header-value"
            ]
        ]
    },
    "results": [
        {
            "id": "ai-result-1",
            "endpoint": "https://your.server/webhook/export/ai-result/ai-result-1",
            "verb": "POST",
            "headers": [
                [
                    "header-key",
                    "header-value"
                ]
            ]
        }
    ]
}

curl -X POST "https://api.copyleaks.com/v3/downloads/my-ai-detection-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",
          "maxRetries": 3,
          "developerPayload": "custom_data_identifier",
          "crawledVersion": {
              "endpoint": "https://your-server.com/webhook/export/crawled",
              "verb": "POST",
              "headers": {
                  "header-key": "header-value",
                  "header-key-2": "header-value-2"
              }
          },
          "results": [
              {
                  "id": "<AI_RESULT_ID_FROM_COMPLETED_WEBHOOK>",
                  "endpoint": "https://your-server.com/webhook/export/ai-result/1",
                  "verb": "POST",
                  "headers": {
                      "header-key": "header-value"
                  }
              }
          ]
        }'

from copyleaks.copyleaks import Copyleaks
from copyleaks.models.export import Export, ExportResult

export_id = "my-export-1"
export = Export()
export.set_completion_webhook('https://your-server.com/webhook/export/completion')

# Export a specific AI detection result
result1 = ExportResult()
result1.set_id('<AI_RESULT_ID_FROM_COMPLETED_WEBHOOK>')
result1.set_endpoint('https://your-server.com/webhook/export/ai-result/1')  # Only URL
result1.set_verb('POST')  # HTTP method separately
export.set_results([result1])

Copyleaks.export(auth_token, scan_id, export_id, export)
print("Export initiated.")

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

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

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

          const scanId = "YOUR_SCAN_ID"; // The ID of the scan you want to export
          const exportId = `export-${scanId}-${Date.now()}`;
          const WEBHOOK_URL = "https://your-server.com/webhook";
          
          // The AI detection result ID to export, obtained from the completion webhook
          const aiResultId = "AI_RESULT_ID_FROM_WEBHOOK"; 

          const results = [{
              id: aiResultId,
              endpoint: `${WEBHOOK_URL}/export/${exportId}/result/${aiResultId}`,
              verb: "POST"
          }];

          // Create an export model
          const exportModel = new CopyleaksExportModel(
              `${WEBHOOK_URL}/export/${exportId}/completion`, // Completion webhook URL
              results,
              {
                  // Request to export the crawled version of the original document
                  endpoint: `${WEBHOOK_URL}/export/${exportId}/crawled-version`,
                  verb: "POST"
              }
          );

          // Start the export process
          await copyleaks.exportAsync(loginResult, scanId, exportId, exportModel);
          console.log(`Export initiated. Export ID: ${exportId}`);

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

  exportAiDetectionResults();

  import classes.Copyleaks;
  import models.exports.*;

  String scanId = "my-ai-detection-scan"; // Your scan ID from submission
  String exportId = "my-export-1"; // Your chosen export ID

  // Create headers (optional)
  String[][] headers = new String[][]{
      new String[]{"header-key", "header-value"}, 
      new String[]{"header-key-2", "header-value-2"}
  };

  // Export a specific AI detection result
  ExportResults aiResult = new ExportResults(
      "<AI_RESULT_ID_FROM_COMPLETED_WEBHOOK>", // Result ID from completed webhook
      "https://your.server/webhook/export/ai-result/1", // Endpoint URL
      "POST", // HTTP method
      headers // Optional headers
  );

  // Create array of results to export
  ExportResults[] exportResultsArray = new ExportResults[1];
  exportResultsArray[0] = aiResult;

  // Export crawled version of original document
  ExportCrawledVersion crawledVersion = new ExportCrawledVersion(
      "https://your.server/webhook/export/crawled",
      "POST",
      headers
  );

  // Create the export model
  CopyleaksExportModel exportModel = new CopyleaksExportModel(
      "https://your-server.com/webhook/export/completion", // Completion webhook
      exportResultsArray, // Results to export
      crawledVersion // Crawled version
  );

  // Execute the export with comprehensive exception handling
  try {
      Copyleaks.export(token, scanId, exportId, exportModel);
      System.out.println("Export initiated successfully.");
  } catch (ParseException e) {
      System.out.println("Parse error: " + e.getMessage());
      e.printStackTrace();
  } catch (AuthExpiredException e) {
      System.out.println("Authentication expired: " + e.getMessage());
      e.printStackTrace();
  } catch (UnderMaintenanceException e) {
      System.out.println("Service under maintenance: " + e.getMessage());
      e.printStackTrace();
  } catch (RateLimitException e) {
      System.out.println("Rate limit exceeded: " + e.getMessage());
      e.printStackTrace();
  } catch (CommandException e) {
      System.out.println("Command error: " + e.getMessage());
      e.printStackTrace();
  } catch (ExecutionException e) {
      System.out.println("Execution error: " + e.getMessage());
      e.printStackTrace();
  } catch (InterruptedException e) {
      System.out.println("Process interrupted: " + e.getMessage());
      e.printStackTrace();
  }

Summary

You have successfully submitted a scan for AI-generated content detection and exported the results. You can now handle the results in your application, display them to users with confidence scores and highlighted AI-generated sections, or take further actions based on the findings.

Frequently asked questions

How do I enable AI detection on a scan?

Set "aiGeneratedText": { "detect": true } inside the submission properties. Without it, the scan runs without AI-generated text analysis.

Which file types can I scan for AI-generated content?

Documents such as PDF, DOCX, and TXT are supported. See the full list of supported AI text detection file types.

Can I test AI detection without using credits?

Yes. Set "sandbox": true in the submission properties. Sandbox mode is free and returns mock results, so you can wire up the flow before going live.

How do I know whether AI-generated content was found?

When the scan completes, check the notifications.alerts array in the webhook payload. An alert with the code suspected-ai-text indicates AI-generated content was detected; its additionalData field holds the detailed summary.

How do I get the detailed AI detection breakdown?

After the completed webhook, call the export endpoint with the AI detection result ID to retrieve the AI Detection Result and the Crawled Version of the document.

Next steps

Webhooks Overview

Learn how to securely receive and process notifications from Copyleaks.

Viewing AI Detection Results

Understand the AI detection result format and how to display confidence scores to your users.

Get started

Guides

Using the APIs

Concepts

Resources

Detect AI-Generated Content in Documents

Get started

Before you begin

Installation

Submit for scanning

File Upload

URL Scanning

Text from Images

Wait for the completion webhook

Interpreting AI detection results

Export detailed results

Summary

Frequently asked questions

Next steps

Webhooks Overview

Viewing AI Detection Results

​Get started

​Before you begin

​Installation

​Login

​Submit for scanning

File Upload

URL Scanning

Text from Images

​Wait for the completion webhook

​Interpreting AI detection results

​Export detailed results

​Summary

​Frequently asked questions

​Next steps

Webhooks Overview

Viewing AI Detection Results

Get started

Before you begin

Installation

Login

Submit for scanning

Wait for the completion webhook

Interpreting AI detection results

Export detailed results

Summary

Frequently asked questions

Next steps