Calling the moderation API

The API is a RESTful API that uses JSON for serialization and simple token included in header for authentication. This is to make sure that we don’t require you to change anything in your application code or add new libraries to benefit from the AI powered moderation. We have designed everything the way you can use fetch, curl, axios or any other HTTP client to call the API without being worried about the compatibility.

Authentication

You can find your API keys on in the settings of your project, within the organisation. You need to be either organisation admin or project admin to be able to create, access or rotate API keys. You can have one API key per project, which should make it easy to distinguish between different projects and use cases. Organisation x-client-id can be rotated only by the organisation admininistrator.

Our API expect two authentication headers to be present in each request

x-client-id - unique to your organisation
x-client-secret - unique to your project

Rate limiting

We don’t have any rate limit at the moment, but in case of excessive calls to the API they may be throttled ( and simply take a bit longer to respond ). The higher plan your organisation is on, the highest priority your requests will have. We do not drop authenticated requests.

User identification

We recommend that you pass some kind of user identifier with each request. This can be a user id, email address or any other unique identifier. This will help you to identify the user in case of any issues with the moderation and also help us to improve the moderation for your users. The user_id within your request is optional and can be ommited although we recommend to use it for the user behavioural tracking.

{
  "request": {
    "user_id": "12345"
  }
}

Request body format

The request body is a JSON object with two keys: request and settings. The request key contains the data you want to moderate and the settings key contains the additional settings or overrides for the moderation.

{
  "request": {
    "media": {
      "gif_url": [
        ""
      ],
      "image_url": [
        "https://example.com/image.jpg"
      ],
      "text": "Any text you want to check"
    },
    "user_id": "726fddcb-ba41-4eba-a14c-a5e2784c9925"
  },
  "settings": {
    "project_id": 31337
  }
}

Request body can contain any combination of the following keys:

media.gif_url - array of urls to GIFs you want to moderate
media.image_url - array of urls to images you want to moderate
media.text - text you want to moderate
user_id - user identifier

Note on images and GIFs moderation

Please note that media URLs must be publicly accessible and not require any authentication. We will not be able to moderate the media if it’s not accessible. Good practice in this case is to allow user upload into the temporary storage like separately created S3 bucket. If you check our (demo page)[/moderation-demo/] you can see that we are using lambda and S3 to store the media temporarily with demo_ prefix, and Amazon allows us to automatically expire the uploaded objects.

Response body format

Show full expected response body

{
  "trace_context": null,
  "links": {
    "status": "",
    "hit": false
  },
  "badwords": {
    "status": "",
    "hit": false
  },
  "antivirus": {
    "status": "",
    "hit": false
  },
  "language": {
    "expected": "en",
    "detected": "pl",
    "hit": true
  },
  "images": {
    "result": {
      "category": "neutral",
      "confidence": 0.95909999832510948
    },
    "status": "ok",
    "porn": 0.068999981880188,
    "sexual": 0.029999999329447746,
    "neutral": 0.95909999832510948,
    "hit": true
  },
  "gifs": {
    "result": {}
  },
  "sentiment": {
    "toxic": 0.78711975,
    "profanity": 0.7888968,
    "threat": 0.011353259,
    "insult": 0.61794597,
    "hit": true
  },
  "hits": true
}

Response body keys

trace_context (string) - unique identifier of the moderation request, you can pass the trace context from your application with initial request.
links (object) - moderation results for links in the text ( if any ) // feature not yet available
badwords (object) - moderation results for badwords in the text ( if any ) // feature not yet available
antivirus (object) - moderation results for antivirus in the text ( if any ) // feature not yet available
language - result of language detection if enabled in the project settings
- expected (string) - expected language of the text
- detected (string) - detected language of the text
- hit (bool) - boolean value if text violates thresholds set in your project settings.
images (object) - moderation results for the images supplied from URLs.
- result (object) - contains the moderation result for the image for the prevailing category.
  - category (string) - prevailing category for the image. Can be porn, sexual or neutral.
  - confidence (float) - confidence level for the prevailing category from 0.0 ( not likely ) to 1.0 ( very likely ).
- porn (float) - confidence level for the porn category from 0.0 ( not likely ) to 1.0 ( very likely ).
- sexual (float) - confidence level for the sexual category from 0.0 ( not likely ) to 1.0 ( very likely ).
- neutral (float) - confidence level for the neutral category from 0.0 ( not likely ) to 1.0 ( very likely ).
- status (string) - status of the moderation request for the image. Can be ok or error.
- hit (bool) - boolean value if image violates thresholds set in your project settings.
gifs (object) - moderation results for the GIFs supplied from URLs.
- Same as in images moderation section above
sentiment (object) - moderation results for the text supplied.
- toxic (float) - confidence level for the toxic category from 0.0 ( not likely ) to 1.0 ( very likely ).
- profanity (float) - confidence level for the profanity category from 0.0 ( not likely ) to 1.0 ( very likely ).
- threat (float) - confidence level for the threat category from 0.0 ( not likely ) to 1.0 ( very likely ).
- insult (float) - confidence level for the insult category from 0.0 ( not likely ) to 1.0 ( very likely ).
- hit (bool) - boolean value if text violates thresholds set in your project settings.

Example requests

You can find example calls to the api below. You can also mix and match the requests - by for example requesting moderation of text and image at the same time. You will be billed for each separately, but you can save the time on API calls and code.

See the example of text moderation

curl -X 'POST' \
  'https://api.discuse.com/api/v1/check' \
  -H 'accept: application/json' \
  -H 'x-client-id: xxx' \
  -H 'x-client-secret: xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "request": {
    "media": {
      "text": "Any text you want to check",
    },
    "user_id": "726fddcb-ba41-4eba-a14c-a5e2784c9925"
  },
  "settings": {
    "project_id": 31337
  }
}'

See the example of image moderation

curl -X 'POST' \
  'https://api.discuse.com/api/v1/check' \
  -H 'accept: application/json' \
  -H 'x-client-id: xxx' \
  -H 'x-client-secret: xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "request": {
    "media": {
      "gif_url": [
        ""
      ],
      "image_url": [
        "https://example.com/image.jpg"
      ]
    },
    "user_id": "726fddcb-ba41-4eba-a14c-a5e2784c9925"
  },
  "settings": {
    "project_id": 31337
  }
}'