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 >

Need Help?

Not sure how to generate your login token? Read here.

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 moderation model used.

moderations object

An object containing the moderation results for the text. See Text Moderation Response for more details.

legend array<object>

A legend mapping label indices to label IDs. See Text Moderation Labels for more details.

scannedDocument object

Metadata about the moderation scan. See Scanned Document for more details.

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.

Example Response

A typical response from this endpoint:

{
  "ErrorMessage": "Id Label my-label is not supported",
  "ErrorCode": "Bad Request"
}

401

401 Unauthorized

Authorization has been denied for this request.

Example Response

A typical response from this endpoint:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-ef0db7690ced98431ac97782051edc77-2c4194d74ae6c08b-00"
}

409

409 Conflict

A scan with the same Id already exists in the system.

Example Response

A typical response from this endpoint:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Conflict",
  "status": 409,
  "traceId": "00-561fe3b2451eb51ce489557a2f34f247-3acd41c0b4ad1295-00"
}

429

429 Too Many Requests

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

Example Response

A typical response from this endpoint:

{
  "error": "Rate limit exceeded",
}

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" }
    ]
  }'