The Copyleaks AI Detection API is a powerful tool to determine if a given text was written by a human or generated by an AI. The API is synchronous, meaning you get the results in the same API call.

This guide will walk you through the process of submitting text for AI detection and understanding 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 Analysis

   Use the Writer Detector Endpoint to send text 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

   POST https://api.copyleaks.com/v2/writer-detector/my-scan-1/check
   
   Headers
   Authorization: Bearer <YOUR_AUTH_TOKEN>
   Content-Type: application/json
   
   Body
   {
     "text": "Lions are social animals, living in groups called prides, typically consisting of several females, their offspring, and a few males. Female lions are the primary hunters, working together to catch prey. Lions are known for their strength, teamwork, and complex social structures.",
     "sandbox": true
   }

   cURL

   curl -X POST "https://api.copyleaks.com/v2/writer-detector/my-scan-1/check" \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "text": "Lions are social animals, living in groups called prides, typically consisting of several females, their offspring, and a few males. Female lions are the primary hunters, working together to catch prey. Lions are known for their strength, teamwork, and complex social structures.",
              "sandbox": true
            }'

   Python

   from copyleaks.copyleaks import Copyleaks
   from copyleaks.models.submit.document import NaturalLanguageDocument
   
   scan_id = "my-scan-1"
   sample_text = "Lions are social animals, living in groups called prides..."
   
   natural_language_submission = NaturalLanguageDocument(sample_text)
   natural_language_submission.set_sandbox(True)
   
   response = Copyleaks.AiDetectionClient.submit_natural_language(auth_token, scan_id, natural_language_submission)
   print(response)

   Node.js

   const { Copyleaks, CopyleaksNaturalLanguageSubmissionModel } = require('plagiarism-checker');
   
   const scanId = "my-ai-scan";
   const sampleText = "Lions are social animals, living in groups called prides...";
   
   const submission = new CopyleaksNaturalLanguageSubmissionModel(sampleText);
   submission.sandbox = true;
   
   const response = await copyleaks.aiDetectionClient.submitNaturalTextAsync(authToken, scanId, submission);
   console.log(response);

   Java

   import classes.Copyleaks;
   import models.submissions.CopyleaksNaturalLanguageSubmissionModel;
   import models.responses.AIDetectionResponse;
   
   String scanId = "my-ai-scan";
   String sampleText = "Lions are social animals, living in groups called prides...";
   
   CopyleaksNaturalLanguageSubmissionModel submission = new CopyleaksNaturalLanguageSubmissionModel(sampleText);
   submission.setSandbox(true);
   
   AIDetectionResponse response = Copyleaks.aiDetectionClient.submitNaturalLanguage(authToken, scanId, submission);
   System.out.println("AI Score: " + response.getSummary().getAi());

5. Interpreting The Response

   For a complete breakdown of the response structure, see the AI Detection Response documentation.

6. 🎉Congratulations!

   You have successfully submitted text for AI detection. You can now use the JSON response in your application to take further action based on the findings.

🗺️ Next Steps

API Reference Explore the full API reference for the AI Detection endpoint.

AI Logic Learn how to use AI logic can help you interpret the results of AI text detection.

Accuracy & 3rd Party Evaluations Discover how Copyleaks AI Detector maintains top accuracy in third-party evaluations.