# Moderate Text

> Instantly flag hateful, explicit, toxic, or otherwise risky content in any text.

<RequestExample>

```bash title="cURL" icon="terminal"
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,
    "language": "en",
    "labels": [
      { "id": "toxic-v1" },
      { "id": "profanity-v1" },
      { "id": "hate-speech-v1" }
    ]
  }'
```

```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.TextModeration.Requests.CopyleaksTextModerationRequestModel import CopyleaksTextModerationRequestModel

auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")

submission = CopyleaksTextModerationRequestModel(
    text="Your text content to be moderated goes here.",
    sandbox=True,
    language="en",
    labels=[
        {"id": "toxic-v1"},
        {"id": "profanity-v1"},
        {"id": "hate-speech-v1"},
    ],
)

response = Copyleaks.TextModerationClient.submit_text(auth_token, "my-scan-123", submission)
print(response)
```

```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksTextModerationRequestModel } = require('copyleaks');

async function main() {
  const copyleaks = new Copyleaks();
  const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');

  const submission = new CopyleaksTextModerationRequestModel({
    text: 'Your text content to be moderated goes here.',
    sandbox: true,
    language: 'en',
    labels: [
      { id: 'toxic-v1' },
      { id: 'profanity-v1' },
      { id: 'hate-speech-v1' },
    ],
  });

  const response = await copyleaks.textModerationClient.submitTextAsync(auth, 'my-scan-123', submission);
  console.log(JSON.stringify(response, null, 2));
}

main();
```

```java title="Java" icon="java"
import classes.Copyleaks;
import models.request.TextModeration.CopyleaksTextModerationRequest;
import models.request.TextModeration.CopyleaksTextModerationLabel;
import models.response.CopyleaksAuthToken;

CopyleaksAuthToken authToken = Copyleaks.login("your@email", "API_KEY");

CopyleaksTextModerationRequest req = new CopyleaksTextModerationRequest(
  "Your text content to be moderated goes here.",
  true,
  "en",
  new CopyleaksTextModerationLabel[] {
    new CopyleaksTextModerationLabel("toxic-v1"),
    new CopyleaksTextModerationLabel("profanity-v1"),
    new CopyleaksTextModerationLabel("hate-speech-v1"),
  }
);

Copyleaks.textModerationClient.submitText(authToken, "my-scan-123", req);
```

</RequestExample>

<ResponseExample>

```json 200 OK
{
  "modelVersion": "v1",
  "moderations": {
    "text": {
      "chars": {
        "labels": [1, 1, 1, 0, 2, 2],
        "starts": [15, 73, 138, 287, 407, 446],
        "lengths": [4, 4, 4, 14, 12, 24]
      }
    }
  },
  "legend": [
    { "index": 0, "id": "toxic-v1" },
    { "index": 1, "id": "profanity-v1" },
    { "index": 2, "id": "hate-speech-v1" }
  ],
  "scannedDocument": {
    "scanId": "scan-id",
    "totalWords": 86,
    "actualCredits": 1,
    "expectedCredits": 1,
    "creationTime": "2025-08-06T08:05:20.6787519Z"
  }
}
```

</ResponseExample>

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.

<Warning>
**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 &lt;Your-Login-Token&gt;**
</Warning>

## Request

### Path Parameters

<ParamField path="scanId" type="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. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).

  `>= 3 characters` `<= 36 characters`
</ParamField>

### Headers

```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```

### Request Body

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

<ParamField body="text" type="string" required>
  Text to produce Text Moderation report for.

      `>= 2 characters` `<= 25000 characters`
</ParamField>
<ParamField body="sandbox" type="boolean" default="false">
  Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.
</ParamField>
<ParamField body="language" type="string">
  The language code of your content. Only English (`en`) is supported. If the `language` field is not specified, our system will automatically detect the language of the content; text in any other language returns `400 Bad Request`.

  Example: `"en"`
</ParamField>
<ParamField body="labels" type="array[object]" required>
  A list of label configurations to be used for the moderation process. Each result's label value in `moderations.text.chars.labels` is the position of that label in this list, as listed in the response's `legend`.

  `>= 1 items` `<= 16 items`
  <Expandable title="label properties">
    <ParamField body="id" type="string">
      Identifier for the label. [List of moderation labels](/reference/data-types/moderation/text-moderation-labels/).

      `>= 1 characters` `<= 32 characters`
    </ParamField>
  </Expandable>
</ParamField>

## Responses

<Tabs>
  <Tab title="200">
    <Check>**200 OK** - The moderation report was returned successfully.</Check>

    ```json
    {
      "modelVersion": "v1",
      "moderations": { "text": { "chars": { "labels": [1], "starts": [15], "lengths": [4] } } },
      "legend": [
        { "index": 0, "id": "toxic-v1" },
        { "index": 1, "id": "profanity-v1" },
        { "index": 2, "id": "hate-speech-v1" }
      ],
      "scannedDocument": {
        "scanId": "scan-id",
        "totalWords": 86,
        "creationTime": "2025-08-06T08:05:20.6787519Z"
      }
    }
    ```
  </Tab>
  <Tab title="400">
    <Warning>**400 Bad Request** - Bad Request.</Warning>
  </Tab>
  <Tab title="401">
    <Warning>**401 Unauthorized** - Authorization has been denied for this request.</Warning>
  </Tab>
  <Tab title="402">
    <Warning>**402 Payment Required** - Insufficient credits.</Warning>
  </Tab>
  <Tab title="429">
    <Warning>**429 Too Many Requests** - Too many requests have been sent. The request has been rejected.</Warning>
  </Tab>
</Tabs>
