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:
2

​
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
HTTP needs no installation - call the API with any standard HTTP client, or import our Postman collection for a quicker start.
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.
POST https://id.copyleaks.com/v3/account/login/api

Headers
Content-Type: application/json

Body
{
    "email": "[email protected]",
    "key": "00000000-0000-0000-0000-000000000000"
}
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.
4

​
Submit for moderation

Use the Text Moderation Endpoint. Provide a unique scanId for each request.
For testing, set "sandbox": true. Sandbox mode is free and returns mock results.
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" }
  ]
}
5

​
Interpreting 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" }
  ],
  "modelVersion": "v1",
  "scannedDocument": {
      "scanId": "test",
      "totalWords": 479,
      "totalExcluded": 0,
      "actualCredits": 2,
      "expectedCredits": 2,
      "creationTime": "2025-08-13T06:51:29.4899318Z"
  }
}
In this example, the content is flagged for “toxic-v1” starting at character 27 and for “profanity-v1” starting at character 100.
6

​
Summary

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.

Try it

See how Copyleaks text moderation flags unsafe content with your own examples.