The Copyleaks Text Moderation API empowers you to build safer online environments by proactively identifying and flagging harmful or risky content in real-time. With support for a broad range of categories—including hate speech, toxic language, and more—our API provides the tools you need to enforce your community standards effectively.

This guide will walk you through submitting text for moderation and building a robust workflow based on 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 Moderation

   Use the Text Moderation Endpoint Provide a unique scanId for each request.

   Tip

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

   HTTP

   POST https://api.copyleaks.com/v1/text-moderation/my-scan-1/check
   Authorization: Bearer <YOUR_AUTH_TOKEN>
   Content-Type: application/json
   
   {
     "text": "Your text content to be moderated goes here.",
     "sandbox": true,
     "language": "en",
     "labels": [
       { "id": "toxic-v1" },
       { "id": "profanity-v1" },
       { "id": "hate-speech-v1" }
     ]
   }

   cURL

   curl -X POST "https://api.copyleaks.com/v1/text-moderation/my-scan-1/check" \
        -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "text": "Copyleaks is a damn useful tool when youre tired of people copying your shit and posting it like its theirs. It doesnt just catch that crap — it can also flag stuff that’s offensive or even sexually suggestive garbage you don’t want in your public content. Platforms are flooded with toxic nonsense and hate these days, and Copyleaks helps clean that up before it turns into a PR nightmare. Whether its racist rants, plagiarism, or just some jerk spewing sexist crap, this tool can spot it.",
              "sandbox": false,
              "language": "en",
              "labels": [
                { "id": "toxic-v1" },
                { "id": "profanity-v1" },
                { "id": "hate-speech-v1" }
              ]
            }'

   Python

   from copyleaks.copyleaks import Copyleaks
   from copyleaks.models.submit.document import TextDocument
   from copyleaks.models.submit.properties.moderation_properties import ModerationLabel
   
   scan_id = "my-moderation-scan"
   sample_text = "Your text content to be moderated goes here."
   
   text_submission = TextDocument(sample_text)
   text_submission.set_sandbox(True)
   text_submission.set_language("en")
   text_submission.set_labels([ModerationLabel("toxic-v1"), ModerationLabel("profanity-v1")])
   
   response = Copyleaks.moderate_text(auth_token, scan_id, text_submission)
   print(response)

   Node.js

   const { Copyleaks, CopyleaksTextModerationModel, ModerationLabel } = require('plagiarism-checker');
   
   const scanId = "my-moderation-scan";
   const sampleText = "Your text content to be moderated goes here.";
   
   const submission = new CopyleaksTextModerationModel(
     sampleText,
     [new ModerationLabel("toxic-v1"), new ModerationLabel("profanity-v1")],
     'en',
     true // sandbox
   );
   
   const response = await copyleaks.moderateTextAsync(authToken, scanId, submission);
   console.log(response);

   Java

   import classes.Copyleaks;
   import models.submissions.CopyleaksTextModerationModel;
   import models.submissions.properties.ModerationLabel;
   import models.responses.ModerationResponse;
   import java.util.Arrays;
   
   String scanId = "my-moderation-scan";
   String sampleText = "Your text content to be moderated goes here.";
   
   CopyleaksTextModerationModel submission = new CopyleaksTextModerationModel(
       sampleText,
       Arrays.asList(new ModerationLabel("toxic-v1"), new ModerationLabel("profanity-v1")),
       "en",
       true // sandbox
   );
   
   ModerationResponse response = Copyleaks.moderateText(authToken, scanId, submission);
   System.out.println(response);

5. Interpret The Response

   The API returns a legend array that maps labels IDs to numerical indices, and a moderations object that pinpoints the exact location of flagged content using those indices.

   • legend: A lookup table where each id (e.g., “toxic-v1”) corresponds to an index.
   • moderations.text.chars: Contains parallel arrays:
     • starts: An array of starting character positions for each flagged segment.
     • lengths: An array of character lengths for each segment.
     • labels: An array of numerical indices that correspond to the legend.

   Example Response

   {
     "moderations": {
       "text": {
         "chars": {
           "labels": [ 2, 4 ],
           "starts": [ 27, 100 ],
           "lengths": [ 2, 8 ]
         }
       }
     },
     "legend": [
       { "index": 2, "id": "toxic-v1" },
       { "index": 4, "id": "profanity-v1" }
     ]
   }

   In this example, the content is flagged for “toxic-v1” starting at character 27 and for “profanity-v1” starting at character 100.

6. 🎉Congratulations!

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

🗺️ Next Steps

Moderation Labels See a complete list of all supported content moderation labels and their descriptions.

Full API Reference Explore the complete documentation for the Text Moderation endpoint and response object.