POST https://api.copyleaks.com/v1/text-moderation/{scanId}/check

The Copyleaks Text Moderation API provides real-time content moderation capabilities to help you maintain safe and appropriate content across your platform. This API automatically scans and flags potentially harmful content across multiple categories, enabling you to take appropriate action to protect your users and maintain community standards.

Authentication Required

You need to login with a user and API key in order to access this method. Add this HTTP header to your request:

Authorization: Bearer < Your-Login-Token >

Request

Path Parameters

scanId string Required

A unique scan id provided by you. We recommend you use the same id in your database to represent the scan in the Copyleaks database. This will help you to debug incidents. Using the same ID for the same file will help you to avoid network problems that may lead to multiple scans for the same file. learn more about the criteria for creating a Scan ID.

>= 3 characters <= 36 characters

Match pattern: [a-z0-9] !@$^&-+%=_(){}<>';:/.",~|

Headers

Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

Request Body

The request body is a JSON object containing the text to scan.

text string Required

Text to produce Text Moderation report for.

>= 1 characters <= 25000 characters

sandbox boolean default: "false"

Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.

Submit content for Text Moderation and get returned mock results, simulating Copyleaks’ API functionality to ensure you have successfully integrated the API.

This feature is intended to be used for development purposes only.

language string

The language code of your content. The selected language should be on the Supported Languages list above. If the ‘language’ field is not specified, our system will automatically detect the language of the content.

Example: "en"

labels array[object]

A list of label configurations to be used for the moderation process.

id string

Identifier for the label. List of moderation labels.

>= 1 characters <= 32 characters

Responses

200

200 OK

The scan was Created.

Response Schema

The response contains the following fields:

modelVersion string

The version of the text moderation model used (e.g., "v1").

moderations object

Moderation results with flagged text segments.

text object

Text moderation data with character positions.

chars object

Character-level moderation results.

labels array

Array of label indices corresponding to detected issues.

starts array

Array of starting character positions for flagged content.

lengths array

Array of character lengths for flagged content.

legend array

Legend mapping label indices to moderation categories.

index integer

Numeric index for the moderation label.

id string

String identifier for the moderation category (e.g., "toxic-v1").

scannedDocument object

Metadata about the scan.

scanId string

The unique identifier for this scan.

totalWords integer

Total number of words analyzed.

totalExcluded integer

Number of words excluded from analysis.

actualCredits integer

Credits actually consumed for this scan.

expectedCredits integer

Expected credits for this scan.

creationTime string

ISO 8601 timestamp when the scan was created.

Example Response

A typical response from this endpoint:

Show full example (87 lines)

{
  "modelVersion": "v1",
  "moderations": {
    "text": {
      "chars": {
        "labels": [
          4,
          4,
          4,
          2,
          7,
          6
        ],
        "starts": [
          15,
          73,
          138,
          287,
          407,
          446
        ],
        "lengths": [
          4,
          4,
          4,
          14,
          12,
          24
        ]
      }
    }
  },
  "legend": [
    {
      "index": 0,
      "id": "other-v1"
    },
    {
      "index": 1,
      "id": "adult-v1"
    },
    {
      "index": 2,
      "id": "toxic-v1"
    },
    {
      "index": 3,
      "id": "violent-v1"
    },
    {
      "index": 4,
      "id": "profanity-v1"
    },
    {
      "index": 5,
      "id": "self-harm-v1"
    },
    {
      "index": 6,
      "id": "harassment-v1"
    },
    {
      "index": 7,
      "id": "hate-speech-v1"
    },
    {
      "index": 8,
      "id": "drugs-v1"
    },
    {
      "index": 9,
      "id": "firearms-v1"
    },
    {
      "index": 10,
      "id": "cybersecurity-v1"
    }
  ],
  "scannedDocument": {
    "scanId": "scan-id",
    "totalWords": 86,
    "totalExcluded": 0,
    "actualCredits": 1,
    "expectedCredits": 1,
    "creationTime": "2025-08-06T08:05:20.6787519Z"
  }
}

{
  "modelVersion": "v1",
  "moderations": {
    "text": {
      "chars": {
        "labels": [
          4,
          4,
          4,
          2,
          7,
          6
        ],
        "starts": [
          15,
// ... truncated

400

400 Bad Request

Bad Request.

401

401 Unauthorized

Authorization has been denied for this request.

402

402 Payment Required

Text Moderation is not enabled to your account.

429

429 Too Many Requests

Too many requests have been sent. The request has been rejected.

Examples

HTTP

POST https://api.copyleaks.com/v1/text-moderation/my-scan-123/check
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

{
  "text": "Your text content to be moderated goes here.",
  "sandbox": true,
  "labels": [
    { "id": "toxic-v1" },
    { "id": "profanity-v1" },
    { "id": "hate-speech-v1" }
  ]
}

cURL

curl --request POST \
  --url https://api.copyleaks.com/v1/text-moderation/my-scan-123/check \
  --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Your text content to be moderated goes here.",
    "sandbox": true,
    "labels": [
      { "id": "toxic-v1" },
      { "id": "profanity-v1" },
      { "id": "hate-speech-v1" }
    ]
  }'

Python

import requests

# Sample text to moderate
sample_text = "Your text content to be moderated goes here."

url = "https://api.copyleaks.com/v1/text-moderation/my-scan-123/check"
payload = {
    "text": sample_text,
    "sandbox": True,
    "language": "en",
    "labels": [
        {"id": "other-v1"},
        {"id": "adult-v1"},
        {"id": "toxic-v1"},
        {"id": "violent-v1"},
        {"id": "profanity-v1"},
        {"id": "self-harm-v1"},
        {"id": "harassment-v1"},
        {"id": "hate-speech-v1"},
        {"id": "drugs-v1"},
        {"id": "firearms-v1"},
        {"id": "cybersecurity-v1"}
    ]
}
headers = {
    "Authorization": "Bearer YOUR_LOGIN_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print("Text Moderation Results:")
if 'labels' in result:
    for label in result['labels']:
        print(f"Label: {label.get('id')}, Score: {label.get('score', 'N/A')}")

print("Full response:", result)

JavaScript

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

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

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

        const scanId = "my-scan-123";

        // The text to be moderated
        const textToModerate = "Your text content to be moderated goes here.";

        // Create a submission model
        const submission = new CopyleaksTextModerationRequestModel({
            text: textToModerate,
            sandbox: true,
            language: "en",
            labels: [
                { id: "toxic-v1" },
                { id: "profanity-v1" },
                { id: "hate-speech-v1" }
            ]
        });

        // Submit the text for moderation
        const response = await copyleaks.textModerationClient.submitTextAsync(loginResult, scanId, submission);
        console.log("Moderation results:", response);

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

moderateText();

Java

import classes.Copyleaks;
import models.request.TextModeration.CopyleaksTextModerationRequest;
import models.request.TextModeration.Label;
import models.response.textModeration.CopyleaksTextModerationResponseModel;

public class TextModerationExample {
    private static final String EMAIL_ADDRESS = "[email protected]";
    private static final String API_KEY = "00000000-0000-0000-0000-000000000000";

    public static void main(String[] args) {
        try {
            // Login to Copyleaks
            String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
            System.out.println("Logged successfully!\nToken: " + authToken);

            // Sample text to moderate
            String sampleText = "Your text content to be moderated goes here.";

            // Create text moderation request with all available labels
            String scanId = "my-scan-123";
            CopyleaksTextModerationRequest moderationRequest = new CopyleaksTextModerationRequest(
                sampleText,
                true, // sandbox
                "en", // language
                new Label[] {
                    new Label("other-v1"),
                    new Label("adult-v1"),
                    new Label("toxic-v1"),
                    new Label("violent-v1"),
                    new Label("profanity-v1"),
                    new Label("self-harm-v1"),
                    new Label("harassment-v1"),
                    new Label("hate-speech-v1"),
                    new Label("drugs-v1"),
                    new Label("firearms-v1"),
                    new Label("cybersecurity-v1")
                }
            );

            // Submit for text moderation analysis
            CopyleaksTextModerationResponseModel result = Copyleaks.textModerationClient.submitText(
                authToken,
                scanId,
                moderationRequest
            );

            System.out.println("Text moderation submitted successfully!");
            System.out.println("Moderation Results:");

            if (result.getLabels() != null) {
                for (var label : result.getLabels()) {
                    System.out.println("Label: " + label.getId() + ", Score: " + label.getScore());
                }
            }

            System.out.println("Full result: " + result);

        } catch (Exception e) {
            System.out.println("Failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}